theme-factory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当你需要为AiderDesk添加新主题时，可以使用本技能。

AiderDesk主题通过SCSS文件实现，这些文件定义了一个

.theme-<name>

类，并包含一整套CSS自定义属性（变量）。UI会使用与这些CSS变量映射的Tailwind工具类。

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>

)

主题文件：

src/renderer/src/themes/theme-<name>.scss

主题聚合文件（导入所有主题）：
```
src/renderer/src/themes/themes.scss
```
主题类型注册表：
```
src/common/types.ts
```
（
```
THEMES
```
）

主题选择器UI：

src/renderer/src/components/settings/GeneralSettings.tsx

主题应用逻辑：

src/renderer/src/App.tsx

（将

theme-<name>

类应用到

document.body

）

主题显示名称（国际化）：

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.

每个主题都是一个类：

类名：
```
.theme-<name>
```
内容：完整的
```
--color-*
```
变量集合。

最佳工作流程：复制现有主题（例如

theme-dark.scss

）并调整值。

Checklist: add a new theme

添加新主题的检查清单

1) Choose a theme name

1) 选择主题名称

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>
```

选取短横线分隔的名称（kebab-case），例如

sunset

、

nord

、

paper

。

你需要在以下位置统一引用它：

CSS类：
```
.theme-<name>
```
文件名：
```
theme-<name>.scss
```
```
THEMES
```
数组值：
```
'<name>'
```
国际化键：
```
themeOptions.<name>
```

2) Create the theme SCSS file

2) 创建主题SCSS文件

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.

创建文件：

src/renderer/src/themes/theme-<name>.scss

先复制一个类似的主题（深色主题→偏深色，浅色主题→偏浅色），然后更新十六进制颜色值。

最低要求：定义应用所需的所有变量。

确保完整性的实用方法：

与
```
src/renderer/src/themes/theme-dark.scss
```
（或其他完整主题）对比
保持变量名称完全一致，仅修改值。

3) Register the theme in the theme aggregator

3) 在主题聚合文件中注册主题

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.

编辑文件：

```
src/renderer/src/themes/themes.scss
```

添加：

scss

@use 'theme-<name>.scss';

如果未在此处导入该文件，它将不会被包含在构建后的CSS中。

4) Register the theme in TypeScript types

4) 在TypeScript类型中注册主题

Edit:

```
src/common/types.ts
```

Add

'<name>'

to the exported

THEMES

array.

This makes the theme selectable and type-safe.

编辑文件：

```
src/common/types.ts
```

将

'<name>'

添加到导出的

THEMES

数组中。

这会让主题可被选择且具备类型安全性。

5) Add i18n display names

5) 添加国际化显示名称

Edit:

```
src/common/locales/en.json
```
```
src/common/locales/zh.json
```

Add entries under

themeOptions

json

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

编辑文件：

```
src/common/locales/en.json
```
```
src/common/locales/zh.json
```

在

themeOptions

下添加条目：

json

{
  "themeOptions": {
    "<name>": "你的主题名称"
  }
}

6) Verify in the UI

6) 在UI中验证

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

打开设置 → 通用 → 主题
确认新主题出现在下拉菜单中
切换到该主题，确认整个UI更新（无需重启）

7) Quality checks

7) 质量检查

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

对比度：确认所有背景上的文本都可读（目标达到WCAG AA标准）
验证关键界面区域：
- 主背景面板
- 输入框
- 按钮
- 边框/分隔线
- 差异查看器颜色
- 代码块
- 次要/弱化文本
检查两种状态：
- 正常状态
- 悬停/激活状态

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.

主题未显示：
- 未在
```
src/renderer/src/themes/themes.scss
```
  中添加
```
@use
```
  导入
- 未在
```
src/common/types.ts
```
  的
```
THEMES
```
  数组中添加条目
- ```
.theme-<name>
```
  与设置中存储的
```
<name>
```
  存在拼写错误
部分UI区域看起来“未样式化”：
- 你可能遗漏了一个或多个
```
--color-*
```
  变量；与已知可用的主题对比，补全缺失的变量。