home / skills / hotovo / aider-desk / theme-factory

theme-factory skill

safe

This skill guides you through adding a new UI theme to AiderDesk, covering SCSS variables, i18n, and TS type registration.

npx playbooks add skill hotovo/aider-desk --skill theme-factory

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.3 KB

---
name: theme-factory
description: Step-by-step guide to add a new UI theme to AiderDesk (SCSS + CSS variables + types + i18n).
---

# Theme Factory

Use this skill when you need to add a **new theme** to AiderDesk.

AiderDesk themes are implemented as **SCSS files** that define a `.theme-<name>` class with a full set of **CSS custom properties** (variables). The UI uses Tailwind utilities mapped to these CSS variables.

## Where themes live

- Theme files: `src/renderer/src/themes/theme-<name>.scss`
- Theme aggregator (imports all themes): `src/renderer/src/themes/themes.scss`
- Theme type registry: `src/common/types.ts` (`THEMES`)
- Theme selector UI: `src/renderer/src/components/settings/GeneralSettings.tsx`
- Theme application: `src/renderer/src/App.tsx` (applies `theme-<name>` class to `document.body`)
- Theme display names (i18n):
  - `src/common/locales/en.json` (`themeOptions.<name>`)
  - `src/common/locales/zh.json` (`themeOptions.<name>`)

## Definition format

Each theme is a class:

- Class name: `.theme-<name>`
- Contents: a complete set of `--color-*` variables.

Best workflow: **copy an existing theme** (e.g. `theme-dark.scss`) and adjust values.

## Checklist: add a new theme

### 1) Choose a theme name

Pick a kebab-case name, e.g. `sunset`, `nord`, `paper`.

You will reference it consistently in:
- CSS class: `.theme-<name>`
- filename: `theme-<name>.scss`
- `THEMES` array value: `'<name>'`
- i18n key: `themeOptions.<name>`

### 2) Create the theme SCSS file

Create:
- `src/renderer/src/themes/theme-<name>.scss`

Start by copying a similar theme (dark -> dark-ish, light -> light-ish), then update the hex colors.

Minimum requirement: define **all variables** expected by the app.

Practical way to ensure completeness:
- Compare with `src/renderer/src/themes/theme-dark.scss` (or another full theme)
- Keep variable names identical; only change values.

### 3) Register the theme in the theme aggregator

Edit:
- `src/renderer/src/themes/themes.scss`

Add:
```scss
@use 'theme-<name>.scss';
```

If the file is not imported here, it won’t be included in the built CSS.

### 4) Register the theme in TypeScript types

Edit:
- `src/common/types.ts`

Add `'<name>'` to the exported `THEMES` array.

This makes the theme selectable and type-safe.

### 5) Add i18n display names

Edit:
- `src/common/locales/en.json`
- `src/common/locales/zh.json`

Add entries under `themeOptions`:

```json
{
  "themeOptions": {
    "<name>": "Your Theme Name"
  }
}
```

### 6) Verify in the UI

- Open Settings → General → Theme
- Confirm the new theme appears in the dropdown
- Switch to it and confirm the whole UI updates (no restart)

### 7) Quality checks

- Contrast: confirm text is readable on all backgrounds (aim for WCAG AA)
- Verify key surfaces:
  - main background panels
  - inputs
  - buttons
  - borders/dividers
  - diff viewer colors
  - code blocks
  - muted/secondary text
- Check both states:
  - normal
  - hover/active

## Troubleshooting

- Theme not showing up:
  - missing `@use` import in `src/renderer/src/themes/themes.scss`
  - missing entry in `THEMES` array in `src/common/types.ts`
  - typo mismatch between `.theme-<name>` and the `<name>` stored in settings

- Some UI areas look “unstyled”:
  - you likely missed one or more `--color-*` variables; compare against a known-good theme and fill in the missing ones.

Overview

This skill is a step-by-step guide for adding a new UI theme to AiderDesk using SCSS, CSS variables, TypeScript types, and i18n entries. It explains where theme files live, how to register them in the build and types, and how to verify and quality-check the new theme. Follow it to ensure consistent appearance and runtime selection without rebuilding core logic.

How this skill works

The guide shows how to create a .theme-<name> SCSS class that declares the full set of --color-* CSS custom properties the app expects. It then walks through importing the SCSS into the theme aggregator, adding the theme name to the THEMES array for type-safe selection, and adding localized display names in locale files. Finally it outlines manual UI verification and accessibility checks to ensure the theme applies correctly at runtime.

When to use it

You want to add a new color palette or visual style to AiderDesk.
You are creating a brand-specific theme for a customer or deployment.
You need to prototype light/dark variations or accessibility-friendly palettes.
You are fixing missing or inconsistent UI colors across the app.
You want to add localized display names for a new theme.

Best practices

Copy an existing full theme (e.g., theme-dark.scss) and change only values to avoid missing variables.
Use a kebab-case theme name and keep it consistent across the SCSS class, filename, THEMES array, and i18n key.
Always import the new theme in src/renderer/src/themes/themes.scss so it’s included in the built CSS.
Add the name to src/common/types.ts THEMES to make the option selectable and type-safe.
Run contrast checks (aim for WCAG AA) on primary text, buttons, inputs, code blocks, and diff viewer colors.

Example use cases

Add a corporate-branded theme with company colors and logo accents.
Create a high-contrast theme for accessibility or low-vision users.
Introduce a seasonal or limited-time theme without changing app logic.
Provide light and dark variants for different user preferences.
Fix visual regressions by replacing inconsistent color values in one theme file.

FAQ

The theme doesn't appear in the settings dropdown. Why?

Check that the SCSS file is imported in src/renderer/src/themes/themes.scss and that the theme name is added to the THEMES array in src/common/types.ts. Also verify there are no typos between the filename, class name, and array entry.

Some UI areas look unstyled after switching themes. What should I do?

Compare your theme file to a known-good theme and ensure you defined every --color-* variable. Missing variables cause fallbacks to default styles. Fill in any missing entries and re-test hover/active states.