hj01857655/dsh-theme-studio

dsh-theme-studio

npm version
npm downloads
CI
license
node
GitHub stars
dsh plugin

一个 dsh 插件，用于自定义 UI 主题：强调色预设、自定义强调色、内容密度、字体系列、动画开关，以及原始设计令牌覆盖。

它能改变什么，不能改变什么

此插件只写入实际存在于 dsh 中的设计令牌，这一点已通过读取随附的样式表（@deepseek-ai/dsh-client-ui-theme/lib/client.js）验证。它写入的每个令牌都列在 src/tokens.ts 中，并由 tests/tokens.test.mjs 强制执行。

更改通过 ctx.theme.overrideTokens() 进行——这是 dsh 自带的主题服务——而不是直接写入 DOM。关于这样做的好处，请参见机制。

这一约束有两个可见的后果：

- 无法控制 border-radius。 dsh 为每个组件硬编码了 border-radius——包括 50% 圆形和 corner-shape: round——并且没有提供圆角令牌。没有忠实的方式提供此功能，因此不提供。
- 动画开关是一个样式表，而不是令牌。 dsh 没有提供动效令牌，因此禁用动画会注入一条规则，将过渡和动画时长压缩为 0.001ms 而不是 0s——零时长会阻止 transitionend / animationend 触发，并挂起等待它们的组件。该样式表由此插件的 effect 作用域拥有，因此卸载时会移除它。

功能

- 12 个预设：Ocean、Forest、Sunset、Monochrome、Nord、Dracula、Gruvbox、Solarized、Tokyo Night、Catppuccin、Rosé、Ember
- 感知深色模式的预设——当 dsh 进入深色模式时，深色强调色与浅色强调色不同的预设会自动适配
- 自定义强调色，外加单独的深色模式强调色
- 对比度保护——低于 WCAG 亮度下限的深色模式强调色会逐步调亮，面板会报告它已被调整
- 密度：紧凑 / 舒适 / 宽松——通过 ctx.theme.setFontSize() 写入 dsh 自己的内容字体
大小，因此它与官方
外观控件保持一致，而不是遮蔽它
- 字体系列：系统 / 等宽 / 衬线
- 动画开关
- 自定义 CSS — 覆盖任意 --dsw- 或 --dsh- 令牌
- 导入 / 导出主题为经过验证的 JSON。由旧版本导出的主题
会带有一个 density 字段；导入时它会被忽略，因为字体大小
现在是宿主状态
- 实时预览渲染真实的令牌，显示当前生效的强调色值

安装

dsh plugin add dsh-theme-studio

从源码安装：

git clone https://github.com/hj01857655/dsh-theme-studio.git
cd dsh-theme-studio
npm install && npm run build
dsh plugin add link:.

工作原理

该插件注册了一个 settings.section 插槽（顺序为 47）。偏好设置持久化在 localStorage 中。

机制

每次主题更改都会经过 dsh 的主题服务：

export const inject = ['slots', 'locale', 'theme']
…
ctx.theme.overrideTokens('dsh-theme-studio', overrides)

overrideTokens 会在当前活动主题之上叠加一个部分令牌层。其余由该服务处理：

- 各层按顺序组合，每个令牌以最后写入者为准。 两个主题插件可以共存，而不会有一方悄悄覆盖另一方无关的令牌。
- 每个值都是一个 { light, dark } 对。 单一值在另一种配色方案下会变得难以辨认，因此该 API 会拒绝单一值。src/apply.ts 构建这些对；tests/apply.test.mjs 断言它能够输出的每个值的形状。
- 该层是可释放的。 卸载插件会精确移除它自己的层，恢复宿主在其下原有的内容——包括用户在官方外观行中选择的字体大小。

该层以来源（dsh-theme-studio）为键，重新发布时会整体替换它，因此不断缩小的覆盖集永远不会留下过期的令牌。

早期版本使用 style.setProperty 将自定义属性直接写到 document.body 上。那碰巧能工作——dsh 的呈现器只会撤回它自己写入的变量——但它绕过了叠加顺序、成对的值和释放机制，并且让每次重置都成为插件自己的责任。

密度驱动官方字体大小设置

--dsh-content-font-size 是官方外观行所拥有的轴，而覆盖层位于主题快照之上。因此覆盖该令牌并不会更改该设置——它会隐藏该设置，使官方步进器显示一个 UI 不再渲染的数字。

所以密度根本不使用覆盖。它调用 ctx.theme.setFontSize()，也就是官方控件使用的同一个入口点，并通过 getTheme().fontSize 读回：

- 官方步进器会继续显示（并设置）相同的值。
- 在那里更改大小，此处匹配的预设会高亮；选择 15px 或 17px 则不会高亮任何内容，因为没有预设声称这些值。
- --dsh-content-font-size 永远不会出现在此插件的覆盖层中。自定义 CSS 框仍然可以设置它，因为那是你在要求，而不是插件在决定。
- 重置会恢复你首次在此更改之前宿主所拥有的大小。
早期版本将尺寸视为该插件自身的状态，这导致了一个控件在安装时静默禁用了官方控件（0.5.0），随后，当默认值被设为惰性后，该控件在使用时仍会遮蔽官方控件（0.5.1）。

预览不是模拟

它使用与应用程序相同的变量名进行渲染，因此错误的令牌在预览中也会显示为错误，而不会被硬编码的回退颜色所掩盖。

所有偏好设置入口共用一个验证器

偏好设置通过三种方式进入——localStorage、导入的 JSON 文件，以及手动编辑的上述任一形式。这三种方式都经过 normalizePreferences()，这是唯一进行验证的地方：未知的枚举值回退到惰性默认值，0.5.0 写入的 density: "comfortable" 迁移为 "default"，格式错误的颜色变为 null，非字符串/非布尔字段回退到默认值。parseTheme 有意不保留自己的白名单，因此两个入口点不会产生偏差。

许可证

MIT