暖色护眼主题 yrsxy/dsh-warm-theme

dsh-warm-theme

DSH 护眼配色包 —— 5 套低蓝光配色，通过官方 ctx.theme.overrideTokens() 扩展点覆盖语义 token。

零布局改动 · 热生效 · 卸载即可还原 · macOS / Windows 双平台。

安装

从 npm（推荐，秒装）
dsh plugin --profile desktop add dsh-warm-theme

或直接从 GitHub
dsh plugin --profile desktop add github:yrsxy/dsh-warm-theme

也可以在 插件市场 里搜索「护眼配色」一键安装。

装好后进入 设置 → 通用 → 配色主题，点选即刻生效。

平台支持

| | macOS | Windows |
| 配色 token 覆盖 | ✓ | ✓ |
| 侧栏两段式底色 | ✓（原生同底，本包补色） | ✓（原生即两段式，无需干预） |
| 浅色 / 深色 | ✓ | ✓ |
| 实测宿主版本 | 0.2.1-rc.2 | 继承同一套 token，未单独实测 |

Windows 的正文卡片带 --dsh-windows-content-radius（16px 圆角），这是 DSH 原生布局；本包只改颜色与材质，不动圆角结构，所以两套平台各自保留自己的原生外观。

配色

| id | 名称 | 底色 | 特点 |
| paper | 暖纸 Warm Paper | #f6f1e7 | 纸质书感，降蓝光最多 |
| sepia | 柔褐书页 Old Book | #f2e8d5 | 旧书页黄，层次分明 |
| tea | 茶褐 Tea Brown | #f1e9e4 | 偏红暖棕，最浓郁 |
| olive | 橄榄静绿 Quiet Olive | #eff2e6 | 最低存在感，最专注 |
| mist | 雾蓝 Mist Blue | #eef1f4 | 唯一冷调，最清醒 |

每套覆盖 66 个 token（浅/深各一组值），其余沿用 DSH 内置值。分四类：

① 22 个手工调校的基础色 —— 画布、层次、文字、边框、链接、代码块。

② 19 个派生色（见 lib/palettes.js 的派生层），处理容易被忽略、但一旦不同调就很显眼的地方：

| 派生 token | 用途 | 为什么必须派生 |
| interactive-bg-hover / -active / -hover-accent | 悬停、选中的叠加底色 | 内置是冷蓝灰 #263148，叠在暖底上会发灰（实测色相差最高 9°）；改用本套文字色做叠加源后归零 |
| interactive-bg-hover-solid | 不透明的悬停底 | 需与浅色第三层同调 |
| interactive-bg-hover-danger | 危险操作的悬停态 | 保留红调但压暗，避免在暖底上刺眼 |
| toast-bg / toast-label | 右下角通知浮层 | 内置是冷灰 #353638，与暖色主题割裂 |
| tooltip-bg / tooltip-key-bg | 悬停提示气泡 | 同上，内置冷灰 #2c2c2e |
| specific-（10 个） | 侧边栏、输入框、气泡等部位专用 | 这是独立于 --dsw-alias- 的另一族；不覆盖的话侧边栏等部位会一直用内置冷灰 |

③ 8 个残留纯白与冷色（Plan B）：switch-thumb（内置纯白，米黄底上突兀）、 border-l4、menu-icon、menu-group-header-fill、 markdown-code-block-banner、code-segment-selected/unselected。

④ 17 个形状与材质（Plan B）：

| token | 内置 | 本包 | 说明 |
| radius-xs/sm/md/lg/xl/panel | 4/8/12/16/20/28 | 5/9/14/18/22/32 | 整体上调一档，配合超椭圆更柔和 |
| shadow-lv1/2/3、elevation- | 纯黑 #000000 | 暖黑 | 浅色用各套文字色，深色用 #0a0806；纯黑叠在米黄底上会发灰 |
| ds-transition-duration | .1/.2/.3s | .12/.24/.34s | 略放缓，纸感更「沉」 |
| dsh-scrollbar-width | 5px | 8px | 更好抓取 |

阴影的一个细节：深色模式下暖黑 #0a0806 比纯黑亮，直接换会削弱阴影。
因此 alpha 乘了 1.35 做补偿，实测强度为内置的 0.97–1.05× —— 是「等重的暖」，不是「更重的暖」。（首次实现没做补偿，实测 2.19×，明显偏重，已修正。）

对比度

全部 10 种组合（5 套 × 浅/深）的 5 个角色均 ≥ 4.5:1（WCAG AA），正文 ≥ 10.6:1（AAA）：

| 方案 | 模式 | 正文 | 次要 | 三级 | 强调 | 链接 |
| 暖纸 | 浅 / 深 | 11.06 / 13.47 | 5.39 / 7.54 | 5.11 / 4.87 | 5.12 / 7.27 | 4.55 / 7.27 |
| 柔褐书页 | 浅 / 深 | 11.72 / 13.37 | 6.03 / 7.37 | 5.09 / 4.69 | 4.81 / 7.15 | 4.86 / 7.15 |
| 橄榄静绿 | 浅 / 深 | 11.36 / 13.85 | 5.48 / 8.13 | 4.62 / 5.18 | 4.84 / 8.06 | 5.61 / 8.06 |
| 茶褐 | 浅 / 深 | 10.67 / 13.41 | 6.21 / 7.26 | 4.59 / 4.61 | 5.33 / 6.11 | 5.16 / 6.11 |
| 雾蓝 | 浅 / 深 | 11.28 / 13.91 | 6.59 / 8.43 | 4.86 / 5.58 | 6.11 / 7.31 | 6.11 / 7.31 |

使用

安装后进入 设置 → 通用 → 配色主题，点选即可，立即生效并跨重启保留。
选「跟随内置」即恢复 DSH 原生配色。选项旁的色块就是该套配色的实际底色与强调色。

卸载

dsh plugin --profile desktop remove dsh-warm-theme

覆盖层随插件卸载一起注销，配色立即回到 DSH 内置值 ——没有残留文件，也没有改过任何内置资源。

工作原理

DSH 的主题系统把「第三方主题」设计成一个扩展点：

ctx.theme.overrideTokens(source, { '--dsw-alias-bg-base': { light, dark }, ... })

- 覆盖层是 token 级的，按注册顺序折入活动主题；不修改内置主题。
- 返回 disposer：本包在切换时会先撤销旧层再叠新层，保证任何时刻最多只贡献一层。
- 插件卸载时自动移除覆盖层，不会留下污染。

本包因此不需要重建前端、不需要 fork、也不受 DSH 升级影响。

开发

node build.mjs # 把 palettes.js 与 styles.css 内联进 lib/client.js
node test/smoke.mjs # 冒烟测试：mock DSH 运行时，验证注入层与卸载行为

lib/client.src.js 是源码模板（含 __PALETTES__ / __CSS__ 占位符）， lib/client.js 是构建产物，即 DSH 实际加载的文件。

已知限制

- 不改变布局：只覆盖颜色与材质 token。侧边栏位置、composer 结构等需 fork dsh-web-frontend 重建，不在本包范围内。
（唯一例外是 macOS 侧栏底色，见下。）
- 不做完整性校验：按官方说明，注册主题意味着覆盖同名别名变量，运行时不会校验一组覆盖是否完整。本包覆盖 66 个 token（22 个手调 + 19 个派生 + 8 个残留色 + 17 个形状材质）（含 10 个 --dsw-specific-）。
- 持久化用 localStorage：未走 Host settings API，因此不参与 DSH 的设置同步；无痕模式下降级为仅当前进程生效。

macOS 侧边栏底色（唯一的非 token 例外）

ui-sidebar 的根容器本来写了 background: var(--dsw-specific-sidebar-fill)，但紧接着有一条平台覆盖把它置空：

[data-platform=darwin] .<hash>_root { background: 0 0 }

于是 macOS 上侧栏透明，透出 ui-layout 的 ._<hash>_frame （background: var(--dsw-alias-bg-base)）—— 与正文区同色。
这是 DSH 在 macOS 上的原生设计：侧栏与正文同底，靠边框分隔。
Windows 则走另一条分支（frame 用 sidebar-fill），天然两段式。

本包用一条 CSS 规则给 macOS 补上同类效果：

[data-platform='darwin'] div[class='_sidebarCol'],
div:has(> [data-window-drag]):not([data-window-drag]) {
background: var(--dsw-specific-sidebar-fill);
}

为什么不能只覆盖 token：macOS 那条规则不是纯 token，里面混了硬编码的蓝色：

color-mix(in srgb, color-mix(in srgb, var(--dsw-specific-sidebar-fill) 97%, #7a9bf0) 40%, transparent)

只覆盖 --dsw-specific-sidebar-fill 会留下一个蓝色调，必须整条 background 覆盖。

两条选择器，一主一备：

| | 锚点 | 为什么 |
| 主 | [class*='_sidebarCol'] | CSS Modules 只给哈希前缀加随机值，sidebarCol 这个 local 名是稳定的；不依赖 DOM 层级，也不怕哈希变化 |
| 备 | div:has(> [data-window-drag]) | 万一 ui-layout 改了类名，还能按结构反查（data-window-drag 是 macOS 标题栏拖拽区，仅在 macOS 渲染） |

两条都命中时取值相同，重复也无害。.centerCol / .frame 本包一概不碰 ——那两个在 Windows 上由原生布局正确驱动，越位覆盖会破坏 Windows 的圆角卡片。

失效行为：若 DSH 升级后类名与属性都改名，本规则静默失效，侧栏回落到原生同色 ——不报错、不影响任何其它样式。test/smoke.mjs 里有断言盯着这件事。

许可

MIT © 2026 yrsxy