# dsh-theme 主题设计规范

## 设计目标

主题不是一组孤立色值，而是由配色层级、界面字体、代码字体和字号共同组成的视觉方案。选择预设时必须同步应用这些设置；用户修改其中任意一项后，界面应显示为“自定义”，避免继续冒充原预设。

## 语义层级

- `background`：正文和主要工作区。
- `surface`：卡片和次级容器。大型弹窗与浮层从背景独立派生，不能直接复用表面色。
- `sidebar`：导航区域，可以与正文不同色，不能再强制同底色。
- `inlineCode`：行内代码和输入型内嵌表面。
- `foreground`：主文字，需在以上所有承载面保持可读。
- `accent`：链接、主操作和业务状态，不用于大面积填充。

VS Code 将编辑区、侧栏、输入、列表状态和组件颜色拆成独立语义角色；One Dark 也使用正文、侧栏、输入区逐级变深的关系。dsh-theme 不照搬其字段，而是将这种层级关系映射到 Harness 已公开的 Theme Token。

## 排版规则

- 阅读型主题优先使用衬线体或人文无衬线体，并适当提高界面字号。
- 代码型主题使用系统无衬线体搭配等宽字体，代码字号可以比默认值略大。
- 不打包或复制 Typora、VS Code 主题中的字体文件；只声明字体栈，未安装时使用系统后备字体。
- 字号通过 Harness 语义字体 Token 缩放，不覆盖组件 DOM，也不写全局选择器。

## 命名与来源边界

- 外部主题只能作为设计研究参考，公开预设必须使用独立名称。
- “碳夜代码”参考 One Dark 的暗色空间层级，但使用独立名称，并补充了满足本项目可访问性阈值的正文色和浅色方案。
- 五组阅读型主题只提取本机 Typora 主题的色调、字体类别和阅读密度，不复制 CSS、选择器、图片或字体资源。

## 回归要求

- 主文字在正文、表面、行内代码和侧栏上的对比度不得低于 7:1。
- 强调色在正文背景上的对比度不得低于 4.5:1。
- 背景层级、边框和普通交互态只能用中性黑白派生，禁止混入正文色，避免带色文字污染大面积表面。
- 阅读型主题与“碳夜代码”的侧栏必须和正文形成明确层级。
- 预设 ID、字典文案、完整设置和测试必须同步更新。
- 新增 Theme Token 前必须先确认当前 Harness 类型或运行时确实公开该 Token，禁止凭名称猜测。

## 版本与兼容边界

- 当前开发依赖固定为 DeepSeek Harness `0.1.2-rc.1`，构建结果以该公开类型契约为准。源码证据和发布检查见[兼容说明](./compatibility.md)。
- DSH Desktop 可能携带更新的内部运行时。发布前除单元测试、类型检查和构建外，还必须在实际 Desktop profile 中重装，并确认插件锁文件、启动清单和客户端 bundle 指向同一提交。
- 本插件使用浏览器本地存储保存主题偏好，且不通过 DOM/CSS 强行补齐未公开的主题能力。

## 参考

- [VS Code 主题能力](https://code.visualstudio.com/api/extension-capabilities/theming)
- [VS Code 主题颜色参考](https://code.visualstudio.com/api/references/theme-color)
- [One Dark Pro 主题定义](https://github.com/Binaryify/OneDark-Pro/blob/master/themes/OneDark-Pro.json)