主题调色板 zuoyunlai/dsh-theme-palette

dsh-theme-palette

English · · 日本語 · Español · Português · हिन्दी

DeepSeek Harness（web 与桌面端）的主题调色板：4 套预设调色板 + 自定义 × 浅色/深色，两条独立轴线。

设置页：五套调色板、强度与面板表面

设置页静态渲染，按真实面板宽度（内容区 564 px）。

| 深色 | 自定义调色板 | 高对比度 |
| 深色 | 自定义调色板 | 高对比度 |

兼容性

| 运行环境 | 状态 |
| DSH 桌面端 / web 客户端 | 0.2.x |
| Node.js | 22.19.0+（22.x 系列）或 24.0.0+ |
| 对宿主源码的改动 | 无 |

包的 engines 字段为 ^22.19.0 || >=24.0.0，上表是同一要求的中文表述。

插件只通过 ctx.theme.overrideTokens 叠加颜色 token；不注册主题，不打补丁改宿主，也不碰外观偏好。

功能

- 4 套预设 + 自定义：Mono、Warm sand、Indigo、Moss（各自独立适配浅色和深色），外加一套由三种颜色推导出的自定义调色板；
- 整条色阶重新计算，不是简单替换：OKLCH 重建 → 按角色分配色度 → sRGB 色域裁剪 → 在真实表面上求解对比度；
- 宿主颜色 token：着色调色板 179 个，加上 13 个插件自有 token；Mono 为 19 个（1080 种设置组合全部扫描）；构建后的 CSS 实际用到的 66 个颜色 token 全部解析到插件——正文、次级、三级、说明文字、链接、侧边栏、卡片、用户气泡、主按钮、滚动条、开关、Markdown 标题/加粗、代码块，现在还覆盖错误/成功/警告状态，以及文件 diff 的 +/− 行（红/绿/琥珀色阶首次加入重建：只调温度，色相旋转上限 8°，语义不会漂移）；
- 可调项：文字着色（3 档）、侧边栏深度（3 档）、Markdown 强调、滚动条、开关颜色；
- 自定义调色板（选表面 / 文字 / 强调色——文字色相参与推导，明显偏暗或偏亮的表面会成为该模式的画布亮度；引擎仍保证对比度），配置导出/导入，用 dshs1. 开头的代码，高对比度模式，以及 4 种界面语言；
- 自愈：宿主丢掉覆盖层时，调色板会重新应用；连续失败后自动恢复暂停，设置页提供重新启用按钮；
- 对比度承诺：正文在浅色下承诺 12:1，深色下 10:1（高对比度下 15:1）；次要文字浅色 ≥ 6.2、深色 ≥ 8.0（高对比度 9 / 9.6）；三级文字浅色 ≥ 4.85、深色 ≥ 6.4（高对比度 7 / 7.6）；链接浅色 ≥ 4.95、深色 ≥ 4.62（高对比度 7；浅色下限留了色觉余量；深色链接还要过 APCA Lc ≥ 60 这道关，高对比度下 75）——全部在文字实际落到的表面上测量（深色侧要求更高，因为 WCAG 比值在深色背景上会高估可读性）；
- 承诺的表面是浅色 00/60 和深色 950/875；深色 800（模块表面）和 850（子表面）不承载正文——报告把它们单独算作「超出策略」（既不算通过也不算失败）；
- 界面支持简体中文 / 繁體中文 / English / 日本語（跟随宿主语言，也可固定）。

安装

from npm
cd ~/.dsh/profiles/desktop
pnpm add dsh-theme-palette

要固定版本，用 pnpm add dsh-theme-palette@<version> —— CHANGELOG.md 标出了从未发布到 npm 的段落，别固定到那些版本。
从 GitHub Release 的 tarball 安装：在发布页挑一个资源，用 pnpm add <path-to-tgz> 安装。

然后重启 GUI —— 运行中的进程还留着旧模块。从头像 → 设置 → Color theme 打开。

配置

| 项 | 选项 |
| 调色板 | Mono · Warm sand · Indigo · Moss（缩略图跟随浅色/深色） |
| 强度 | Quiet / Standard / Strong —— 正文跟随调色板的程度 |
| 面板表面 | Sidebar（Lighter / Same / Deeper）。右侧面板永不着色——它是全高透明覆盖层，涂色会盖住对话（该设置已在 1.9.10 移除） |
| 更多选项 | 语言、Markdown 强调、滚动条、开关/勾选 |

每项选择立即生效，存进 localStorage。浅色/深色仍由宿主的 Appearance 控制。

调色板引擎

OKLCH(L, C, hue) ──► gamut clamp (binary search on C) ──► sRGB hex
▲
└── role chroma × intensity, then contrast solve on {canvas, card, sidebar, overlay}

- 语义别名保留 var(--dsw-static-neutral-bluish-NN) 链，所以跟随 token 的东西都会跟随调色板；
- 浅色表面用 00–300 档，深色表面用 800–950 档；
- 语义色（1.13.5）：宿主的红/绿/琥珀色阶保留宿主亮度，只做一次朝调色板色相的温度协调（harmonizeSemantic：色相旋转上限 8°，彩度缩放到 88–92%）——错误仍是红，成功仍是绿，警告仍是琥珀，只是落在调色板的暖/冷调上；无彩色的自定义调色板（纯黑/白/灰）原样不动；
- 覆盖率声明可验证：tools/check-host-contract.mjs 会提取构建后 CSS 实际用到的每一个颜色 token，并要求每个 token 要么由插件声明，要么其 var() 链最终落在已声明的 token 上——1.13.4 及更早版本有 30 处泄漏（红/绿/琥珀、danger hover、diff 行），无法通过；1.13.5 报告零泄漏；
- 文字对比度下限在构建时强制执行：正文在浅色下 ≥ 12:1、深色下 ≥ 10:1（高对比度：15:1），次要文字浅色 ≥ 6.2 / 深色 ≥ 8.0（HC 9 / 9.6），三级文字浅色 ≥ 4.85 / 深色 ≥ 6.4（HC 7 / 7.6），链接浅色 ≥ 4.95 / 深色 ≥ 4.62（HC 7），深色下链接 APCA Lc ≥ 60（HC 75）；侧边栏和气泡文字遵循同一梯度，实测 ≥ 7（不单独设对比度门槛）；
- 承诺的表面是浅色 00/60 和深色 950/875；深色 800（模块表面）和 850（子表面）不承载正文——报告把它们单独计为「超出策略」（既不算通过也不算失败），但每个表面仍须达到 AA 下限 4.5；
- 报告区分三件事：声明的目标、物理上限（黑或白在该表面上能达到的值）和策略豁免；0.93 只是求解器余量，用来判断目标是否高于上限；
- node palette-dev.mjs 会检查 1080 种配置组合（5 套调色板 × 216 项设置，含两个对比度层级）。

设计说明、各组件设计理由和对比度表格见 docs/DESIGN.md。发布历史：CHANGELOG.md。

开发

npm run report # token report for every palette (add -- --hc for the high-contrast tier)
npm run sheet # palette board → tools/sheet.html
npm run shot-sheet # screenshot the board (headless Chrome/Edge)
npm run compare -- --dir tools/out/<run> # diff against the local baseline
npm run preview -- --lang en # render the settings page
npm run contract # host token / DOM contract (strict: SKIP becomes a failure)
npm run release -- --dry # release preflight
npm run release -- --tag # publish to npm + tag
npm run release -- --ci # CI publish: tag only; Actions publishes via Trusted Publishing
npm run clean # drop local tarballs / tools/out / dist

截图回归分两层：调色板看板（无需认证）和通过 CDP 截取的真实桌面窗口（tools/shoot-desktop.mjs，需要 --remote-debugging-port）。详见 tools/README.md。

我们踩过的坑

1.7.0 审计期间最让我们意外的五个坑——每一个都是测试发现的，不是看截图看出来的。

- 白色强调色生成了白色链接（1.13:1）。对比度求解器只会朝一个方向远离背景，所以比背景更亮的强调色会一路走向白色。
- 选颜色只改了页面，没改面板。 组件订阅的是调色板 id，而颜色变化时这个 id 从不变动——React 对比快照，看不出差异，就跳过了重新渲染。
- 分享配置没有分享颜色。 短码带上了模式，却没带三个自定义颜色，于是在另一台机器导入时提示成功，却悄悄保留了本地值。
- 「没承诺」不等于「做不到」。 报告把深色模块表面标为「受表面限制」，因为它拿正文目标去对比最深的表面（800）。但 800 配白色前景的对比度约为 10.22:1，850 约为 15.27:1——都高于 10:1 的目标——所以从来没有什么不可达；那些表面只是没被承诺而已。报告现在把声明目标、物理上限和政策豁免分开，并把深色 800/850 记为「超出政策」，而不是「物理不可达」。
- 我们以为死掉的某个选择器其实活着。 审计最初报告 _markdown_ 钩子已损坏；针对已发布 CSS 的契约测试证明并非如此。错的是结论，不是代码。

分享

每一项设置——包括三个自定义颜色——都装在一个短码里。把它粘贴到导入框，按 Preview，就能在应用前看清它到底会改什么：

dshs1.eyJ2IjoxLCJwIjoiY3VzdG9tIiwicyI6ImRlZXAiLCJ0IjoidGludGVkIiwiYyI6InRpbnRlZCIsImsiOiJhY2NlbnQiLCJtIjoib24iLCJoIjoib2ZmIiwibCI6InpoLUNOIiwieCI6eyJiZyI6IiNmNWVmZTYiLCJ0ZXh0IjoiIzFkMWExNyIsImFjY2VudCI6IiMzZjY2YTMifX0

这个真实示例解码后是：

- 调色板：custom · 侧边栏：deep · 文本：tinted
- 滚动条：tinted · 控件：accent · Markdown 强调：开 · 高对比度：关 · 语言：zh-CN
- 三个颜色：#f5efe6（画布）· #1d1a17（文本）· #3f66a3（强调色）

短码由生产编码器生成，写进这份 README 之前会先做往返自检——从不手写。

取舍

这个生态里其他主题插件会提供玻璃、壁纸和动画。我们刻意不做：

- 不做玻璃，不做壁纸。 那条赛道靠截图取胜；我们更愿意在证据上竞争。
- 不做主题市场，不做 AI 配色。 两者都会引入我们无法保证的颜色——对比度求解器才是资产，喂给它不可预测的输入就是在消耗它。
- 不再增加调色板。 四个预设加一个三色生成器，胜过十个手挑的预设；数量不是护城河。
- 不宣称护眼。 我们报告的是文本实际落到的那些表面上的实测比值，某个表面不在我们承诺范围内时就说「超出政策」——这是测量，不是借口。

License

MIT © 2026 Zuoyunlai