外观与主题定制
理解主题层级与六色体系，配置工作区主题、覆盖文件与风景模式，并为来源和状态定制图标。
主题层级
主题由四层组成，越靠前的层级优先级越高。没有单独设置主题的工作区，会沿用应用默认主题。
| 层级 | 位置 | 作用 |
|---|---|---|
| 工作区主题 | 设置 → 外观 → 工作区主题 | 为单个工作区指定主题，覆盖应用默认 |
| 应用默认主题 | 设置 → 外观 → 默认主题 | 所有工作区的默认外观 |
| 覆盖文件 | ~/.zero-works/theme.json | 只改写指定的具体颜色 |
| 预设主题 | ~/.zero-works/themes/{name}.json | 包含完整配色与元信息的主题包 |
工作区主题
每个工作区可以使用与全局不同的主题，方便用颜色区分不同的项目或场景。工作区主题的选择保存在该工作区自己的配置里。
- 打开设置 → 外观，在默认主题一栏设定全局外观。
- 在工作区主题一栏，为每个工作区选择沿用默认或某个具体预设。
- 切换工作区，确认配色已经跟着变化。
{ "id": "ws_abc123", "name": "我的项目", "defaults": { "colorTheme": "nord" } }
六色语义体系
工作台的整体视觉由六个语义色控制。所有组件、状态提示和图标都从这六个颜色取值，因此只改其中一个，界面的整体观感就会跟着变化。
| 颜色 | 用途 | 使用场景 |
|---|---|---|
| background | 页面与面板底色 | 浅色或深色模式下的表面颜色 |
| foreground | 文字与图标 | 主要文字颜色 |
| accent | 品牌色、执行模式 | 高亮、激活状态 |
| info | 警告、编辑前确认模式 | 提示色、需要留意的地方 |
| success | 已连接状态 | 成功提示、正常状态 |
| destructive | 错误与删除操作 | 告警、失败状态 |
主题覆盖文件
只想改一两个颜色时，不必准备完整主题。创建覆盖文件并写入要改的颜色即可，其余部分继续沿用当前主题。
{ "accent": "oklch(0.58 0.22 293)", "dark": { "accent": "oklch(0.65 0.22 293)" } }
深色模式
dark 对象为深色模式提供可选覆盖。系统切换到深色模式时，顶层颜色作为默认值，dark 中定义的颜色会覆盖它们。
这意味着可以只针对深色模式调整个别颜色，不必复制整套配色。
- 顶层颜色先作为默认值生效。
- dark 里写过的颜色在深色模式下替换对应顶层颜色。
- 没有写进 dark 的颜色在两种模式下保持一致。
预设主题
预设主题是放在配置目录 themes 目录下的完整主题包，每个文件包含配色与元信息。安装方式是把主题文件放进去，再在设置里选中它。
| 字段 | 说明 |
|---|---|
| name | 主题显示名称 |
| description | 一句话说明 |
| author | 主题作者 |
| license | 授权类型 |
| source | 主题原始出处地址 |
| supportedModes | 支持的模式，可写 light、dark 或两者 |
| shikiTheme | 代码高亮主题的浅色与深色变体 |
{ "name": "深色示例", "description": "一套深色配色", "supportedModes": ["dark"], "background": "oklch(0.22 0.02 280)", "foreground": "oklch(0.95 0.01 270)", "accent": "oklch(0.70 0.20 320)", "info": "oklch(0.78 0.14 70)", "success": "oklch(0.72 0.18 145)", "destructive": "oklch(0.65 0.22 28)", "shikiTheme": { "light": "github-light", "dark": "dracula" } }
风景模式
风景模式会用整窗背景图配合半透明面板，营造更有氛围感的界面。开启方式是在主题里把 mode 设为 scenic，并指定背景图片。
| 属性或表面颜色 | 说明 |
|---|---|
| mode | 设为 scenic，默认是 solid |
| backgroundImage | 背景图片文件名，相对于主题文件，或一个可访问的地址 |
| paper | 表面颜色：对话消息、卡片等抬升的内容 |
| navigator | 表面颜色：左侧导航栏背景 |
| input | 表面颜色：输入框背景 |
| popover | 表面颜色：下拉、弹窗、右键菜单 |
| popoverSolid | 表面颜色：保证完全不透明的弹窗背景 |
{ "mode": "scenic", "backgroundImage": "mountains.jpg", "background": "oklch(0.15 0.02 270 / 0.8)", "paper": "oklch(0.18 0.02 270 / 0.6)", "navigator": "oklch(0.12 0.02 270 / 0.7)" }
颜色格式
任何合法的 CSS 颜色写法都可以使用。推荐 OKLCH，因为它在不同模式下的表现更稳定。
| 格式 | 示例 |
|---|---|
| 十六进制 | #8b5cf6，或带透明度的 #8b5cf6cc |
| RGB | rgb(139, 92, 246)，或 rgba(139, 92, 246, 0.8) |
| HSL | hsl(262, 83%, 58%) |
| OKLCH | oklch(0.58 0.22 293) |
| 具名色 | purple、rebeccapurple |
OKLCH 参考
OKLCH 的写法是 oklch(明度 彩度 色相)，用感知均匀的方式描述颜色，因此更贴近人眼对深浅的感受。
- 红色约 25，橙色约 70，黄色约 100。
- 绿色约 145，青色约 195，蓝色约 250。
- 紫色约 293，粉色约 330。
| 分量 | 取值范围 | 含义 |
|---|---|---|
| 明度 | 0 到 1 | 0 是黑色，1 是白色 |
| 彩度 | 0 到 0.4 | 0 是灰色，越大越饱和 |
| 色相 | 0 到 360 | 色轮上的角度 |
示例
下面三个例子分别对应最小改动、替换品牌色和提高对比度三种常见需求。
最小改动：{ "accent": "#3b82f6" } 品牌色：{ "accent": "oklch(0.55 0.25 250)", "info": "oklch(0.70 0.15 200)", "dark": { "accent": "oklch(0.65 0.25 250)", "info": "oklch(0.75 0.12 200)" } } 高对比度：{ "background": "#ffffff", "foreground": "#000000", "dark": { "background": "#000000", "foreground": "#ffffff" } }
实时更新
主题改动会立即生效，不需要重启应用。编辑覆盖文件后，界面会自动刷新。
在设置里切换预设主题同样是即时的，不需要重新打开工作区。
图标定制
来源、技能和状态都可以配置图标。图标可以直接写成一个表情符号，也可以指向一个图片文件。
- 在实体的配置文件里写入 icon 字段，可以是表情符号，也可以是相对路径。
- 或者把图标文件放在实体目录中，命名为 icon.svg、icon.png 或 icon.jpg，工作台会自动发现。
- 需要固定指向某个文件时，用相对路径明确指定。
- 多个格式同时存在时，优先顺序是 SVG、PNG、JPG。
- 来源还可以填一个图片地址，工作台会把它下载成本地图标文件后使用。
- 使用 currentColor 的 SVG 会跟随当前主题变色，没有使用它的 SVG 保持自身配色。
| 格式 | 扩展名 | 适合 |
|---|---|---|
| SVG | .svg | 可缩放，可用 currentColor 跟随主题 |
| PNG | .png | 带透明通道的位图 |
| JPG | .jpg、.jpeg | 照片或复杂插画 |
| 表情符号 | Unicode | 不需要文件，快速区分来源 |
{ "icon": "🔧" } { "icon": "./my-custom-icon.svg" }
状态图标
状态图标与普通实体图标略有不同：文件名使用状态 ID，而不是 icon.svg。状态本身还可以指定颜色，颜色会用于图标和列表中的视觉标记。
- 把图标文件命名为状态 ID，例如 in-progress.svg，即可在对应状态目录下被发现。
- 系统颜色名区分大小写，写成 accent 而不是 Accent 才会生效。
- 透明度取值范围是 0 到 100，例如 foreground/50，而不是 foreground/0.5。
- 自定义颜色需要至少提供 light 一个值。
| 状态 | 默认颜色 | 外观 |
|---|---|---|
| backlog | foreground/50 | 中性 |
| todo | foreground/50 | 中性 |
| needs-review | info | 琥珀色 |
| done | accent | 品牌色 |
| cancelled | foreground/50 | 中性 |
{ "id": "in-progress", "label": "进行中", "color": "success", "category": "open" }
排障
- 主题不生效：确认 JSON 语法正确，文件放在配置目录下的 theme.json，预设主题放在 themes 目录中，颜色值是合法的 CSS 颜色。
- 深色模式下颜色不对：补上 dark 覆盖，并检查预设主题的 supportedModes 是否包含当前模式。
- 背景图不显示：确认 mode 设为 scenic，图片路径相对于主题文件且文件存在可读。
- 图标不显示：确认文件放在实体对应的目录里，文件名符合约定，SVG 内容是合法 XML。
- 颜色改了但界面没变：检查是否被更高层级的工作区主题覆盖。