设计标记被字面量覆写绕过：settings.css 等 7 个文件仍有不可主题化的表面

[Tioit-Wang]

标题建议：设计标记被字面量覆写绕过 —— settings.css 等 7 个文件仍有不可主题化的表面
标签：bug、area: ui-ux
目标仓库：vastsa/PI-Desktop
关联：#339（本 issue 是它在全仓的延续）

---

以下正文可直接粘贴。

1. 场景

我在验证插件主题 ui.theme 的能力边界时发现右侧工作面板不可主题化，已在 #339 修复（work-panel.css 的 6 处字面量覆写改为 --ds-bg-dock / --ds-bg-dock-raised）。

修完后我用同一条判据把整个 apps/desktop/src/styles/ 过了一遍 —— 判据是「被 :root[data-theme] 覆写、且不读变量的字面量表面色」 —— 结果同类洞还在 7 个文件里。

这类覆写的失效机制都一样：基础规则读 token，覆写规则

:root[data-theme="light"] .settings-search { background: #ffffff; }   /* settings.css:114 */

既把特异度从 (0,1,0) 抬到 (0,2,0)，又完全不引用变量，所以主题把 --ds-* 改成什么都会被它盖掉。

一个额外的坏味道：settings.css 的覆写是成对出现的（浅色 + 深色两条），也就是说这两个表面在两个调色板下都被钉死，比 #339 里的单边覆写更彻底。

2. 基于场景提炼需要的能力

能力	来自哪个场景	具体含义
外壳表面色只能来自标记	基础规则用 token、覆写用字面量，同一份文件里两种写法并存	任何「主题应能改的表面」都由 --ds-* 表达；禁止在 :root[data-theme] 覆写里写字面量
缺口可被自动发现	这轮靠人工逐个文件读才找全	有一条机械规则能在 CI 里挡住新增的字面量表面色，不依赖评审记忆
覆盖范围有文档	主题作者不知道哪些表面可改	设计系统的表面层级表登记全部可达 token

3. 现有能力与期待能力的差异

期待能力	现状	差距
外壳表面色只能来自标记	settings.css：:54 / :58（设置页导航轨）、:114 / :118（导航轨搜索框）、:185 / :189（选中导航胶囊）、:706（开关旋钮）、:1241 / :1246（能力页搜索井）	8 处确认缺陷，浅深两套均不可主题化
同上	composer-menus.css:11（输入框壳 #212121f5，覆盖了 var(--ds-bg-elevated-primary)）、plugins.css:248 / :252 / :1755、ui-kit.css:140 / :147、overlays.css:18、theme-overrides.css:81	又 9 处确认缺陷
同上	prose.css：:110、:176、:229、:274-280、:304-305、:320-322、:364-365、:438-440、:454-455、:458-469、:615-616、:734-741（含 Mermaid 块底色）	十余处，正文区同样不可主题化
缺口可被自动发现	scripts/check-style-tokens.mjs:21 只守 font-size / font-weight / line-height / letter-spacing / border-radius，颜色完全没守	新增字面量表面色无任何 CI 阻力
覆盖范围有文档	docs/spec/04-ux/07-ui-design-system.md §6.4 的表面层级表只登记 --ds-bg-primary / --ds-tile / --ds-raised 与新增的 --ds-bg-dock / --ds-bg-dock-raised	上述表面的 token 一个都没有

需要一并注意的 CI 断言（改这些规则会挂）：

• apps/desktop/test/surface-polish.test.mjs:74-77 断言开关旋钮的浅色字面量，:106-109 禁止在 :root[data-theme] .settings-toggle 上写 background，:126-134 要求四个 switch token 各定义两次
• apps/desktop/test/agent-capability-settings.test.mjs:180 断言 :root[data-theme="dark"] .agent-capability-menu 规则存在，:174-177 断言能力分组计数使用 color-mix(var(--ds-text-primary)…)
• apps/desktop/test/settings-drag-region.test.mjs:21-45 断言导航轨的 width / flex 与标题栏定位顺序

4. 提案

对应能力 1：为上述每一组表面抽出 token，默认值取现值，保证内置观感逐像素不变。粗算需要 4 组：

建议 token	浅色	深色	覆盖
--ds-settings-rail-bg	#f4f4f4	#000000	settings.css:54/58
--ds-settings-field-bg	#ffffff	#212121	settings.css:114/118
--ds-settings-nav-active	color-mix(in oklab, #1a1c1f 12%, #ffffff)	color-mix(in oklab, var(--gray-0) 10%, transparent)	settings.css:185/189
--ds-field-inset-bg（含 :focus-within 一档）	#f3f3f3 / #ffffff	沿用现有 token 混合	settings.css:1241/1246、plugins.css:248/252

开关旋钮不需要新 token：浅色 --ds-switch-knob-on 已经是 #ffffff，删掉 :704-708 即可。

prose.css 与遮罩类（ui-kit.css:140、overlays.css:18、plugins.css:1755）的字面量涉及正文排版与 scrim 不透明度，建议单独一批处理，逐项确认是否符合既有设计决策。

对应能力 2：把 scripts/check-style-tokens.mjs 的检查面从字号/圆角扩到颜色 —— 属性集 color|background(-color)?|border(-[a-z]+)?-color|fill|stroke|box-shadow，并沿用现有的 -- 行豁免与 allowlist 机制（@font-face、纯 alpha 遮罩、Shiki 调色板）。

需要注意这条规则的能力边界：它能挡住 apps/desktop/src 下新增的裸 hex / rgb，但抓不到「选择器压过令牌」这类级联问题（#339 的成因），也抓不到插件自带 CSS。级联问题只能靠评审，因此建议在 07-ui-design-system.md §6.4 把该约定写成明文。

对应能力 3：surface 层级表补齐上述 token。

[vastsa]

已修复，PR：#438

先说明：这条 issue 的一部分在 main 上已经修过了。仓库里已有 scripts/style-surface-tokens.mjs，它自己的注释就写着覆盖「issue #341 迁移的常规外壳填充」，白名单是 .settings-nav | .settings-search | .settings-nav-item | .settings-toggle-thumb | .agent-capability-search-wrap | .plugins-search | .composer-shell，node scripts/check-style-tokens.mjs 通过。所以设置页导航轨 / 搜索框 / 选中胶囊 / 开关旋钮 / 能力页搜索井 / 插件页搜索 / 输入框壳这一批没有重做。

这个 PR 处理剩下那批，并把「有意保留」的部分写明白，而不是留成看不见的缺口。

已 token 化（默认值 = 原字面值，内置观感不变）

新 token	浅色	深色
--ds-prose-kbd-fg	#303030	var(--ds-text-secondary)
--ds-thinking-code-bg	#f0f0f0	color-mix(… var(--ds-text-primary) 4.5%, transparent)
--ds-mermaid-canvas	#ffffff	color-mix(… var(--ds-bg-primary) 94%, …)
--ds-code-head-bg	color-mix(in oklab, #1a1c1f 3.5%, transparent)	color-mix(in oklab, #fff 4%, transparent)
--ds-code-hover-bg	color-mix(in oklab, #1a1c1f 6%, transparent)	color-mix(in oklab, #fff 8%, transparent)
--ds-scrim	color-mix(in oklab, #1a1c1f 28%, transparent)	color-mix(in oklab, #000 45%, transparent)
--ds-modal-veil	color-mix(in oklab, #1a1c1f 32%, transparent)	color-mix(… var(--ds-bg-primary) 78%, …)
--ds-tool-row-bg	color-mix(in oklab, #1a1c1f 2%, transparent)	var(--ds-tile)
--ds-send-disabled-bg / -fg	#8e8e90 / #ffffff	color-mix(… 18%) / color-mix(var(--gray-900) 70%, …)
--ds-placeholder-ink	#4a4c4f	color-mix(… var(--gray-0) 42%, …)

prose.css 里那些浅色墨色混合现在读 --ds-text-primary，它的浅色值就是你原来硬编码的 #1a1c1f —— 像素一致，但主题可以一次改掉整个浅色墨色层级。

有意不动的（并按你的「逐项确认」要求写进了守卫与文档）

• Shiki 语法色板（.code-block / .prose-chat pre 的 one-dark-pro / one-light 底色与墨色）。样式表里明确写了代码块底色归 Shiki 所有，改成 --ds-* 会改变渲染并违背既有设计决策。现在它在 scripts/style-surface-tokens.mjs 里被具名登记 + 写明理由，而不是留在缺口里。
• 工具行级联变体（.tool-block.is-plain .tool-row-content、.tool-row-content.is-error）：浅色在 plain/error 变体上保留自己更浅的 tile。以 pinned 形式登记在级联夹具里，所以这个决定是可见的、且必须被有意重新审视。

守卫从少量外壳选择器扩到完整的已迁移集合 + 显式豁免，并且它现在会说明自己覆盖什么、不覆盖什么。docs/spec/04-ux/07-ui-design-system.md §6.4 的 surface 层级表补齐了所有可达 token，并把「:root[data-theme] 覆写里不得写死表面色字面量」写成明文约定；zh-CN 镜像同步。

像素一致性是「实测」而不是「断言」

pnpm test:e2e:theme-surfaces 会启动真实 Electron、链接构建产物的样式表，并在浅色 / 浅色+自定义主题 / 深色 / 深色+自定义主题四种情况下采样每个表面的计算 RGB。新表面被加进了这个夹具，并钉住了修复前的 RGBA（scrim [25,29,32,71]、modalVeil [25,28,31,82]、codeHead [28,28,28,9]、mermaidCanvas [255,255,255,255]、thinkingCode [240,240,240,255]、sendDisabled [142,142,144,255]、kbd [26,26,26,20] 等），同时断言每个 token 在自定义主题设置后确实会变。也就是说，它同时证明了「内置观感未变」和「该表面现在可达」。

验证

集成后的本地 main（merge commit ee5b00a1）上：check-style-tokens → style tokens OK；build:js、typecheck、lint:biome、docs:check(443 页) 通过；pnpm -r --if-present test 通过（desktop 2009/2009，0 fail）；test:e2e:theme-surfaces → ok:true, failures:[]；test:e2e:layout 37/37、test:e2e:boot、test:e2e:transcript 全部通过。

关于你提到的三个能力

• 能力 1（表面色只能来自标记）：剩余那批已按你的提案表处理，默认值取现值。
• 能力 2（缺口可被自动发现）：守卫已扩展，但它抓不到级联问题（也就是 工作面板底色无法由主题配置：work-panel.css 用字面量覆写绕过设计标记 #339 的成因：选择器压过令牌），也抓不到插件自带 CSS。这一点只能靠评审，所以已经写进 07-ui-design-system.md §6.4 作为明文约定。
• 能力 3（覆盖范围有文档）：§6.4 的表已补齐。

你列的 8 处 + 9 处 + prose 十余处 + 3 条 CI 断言，都逐条核对过；那 3 个测试文件（surface-polish、agent-capability-settings、settings-drag-region）里被本次改动触及的断言，已从「覆写里写死某个字面量」改成「token 在两个调色板各定义一次、且该覆写已消失」，属于收紧而非放宽。

[vastsa]

补一条：上一条评论里我说「有意不动的项已逐项确认并登记」，但只列了 Shiki 色板与工具行级联两类。复核后还有两处剩余缺口没写，一并补上 —— 其中第 2 条属于你这条 issue 的同一缺陷类，只是不在你给的字面量判据范围内。

1. .search-overlay（豁免，需你定夺）

apps/desktop/src/styles/overlays.css:17 的搜索遮罩在明暗两套调色板下都保持 45% 黑，这与 §8.4 / D148「浅色用约 28% ink」的口径不一致。它已在守卫里登记为豁免（scripts/style-surface-tokens.mjs:78，删掉该条目 pnpm lint 会失败，所以不是死代码）。

之所以没动：token 化要么改变内置浅色渲染（越过「默认值取现值、观感不变」这条硬约束），要么把一个设计系统并不拥有的值写成决策。这个取舍需要你决定：统一到 28% ink，还是给它一个独立 token 保留 45%。

2. 同一缺陷类的相邻残留：5 处覆写只读 --gray-* 而非 --ds-*

这些规则不写字面量，所以不在你给的判据内，我没有改。但效果与你的报告同类：只重写 --ds-* 的插件主题同样够不到它们（--gray-* 是缩放变量，主题不会去改）。

实测位置：

文件	行	规则
composer.css	~474	:root[data-theme="light"] .send-btn { background: var(--gray-1000); color: var(--gray-0) }
composer-menus.css	~26	:root[data-theme="dark"] .composer-input { color: var(--gray-0) }
composer-menus.css	~31	:root[data-theme="dark"] .mode-chip { color: color-mix(… var(--gray-0) 78% …) }
composer-menus.css	~36	:root[data-theme="dark"] .empty-hero-icon { color: var(--gray-0); opacity: 1 }
settings.css	~1719	:root[data-theme="dark"] .agent-capability-menu { background: color-mix(… var(--gray-0) 8%, var(--gray-800)) }

共 5 处，与你报告里同类问题的成因完全一致（覆写抬高了特异度 (0,2,0)），区别只是它搬的是 --gray-* 而不是字面量。建议要么把它们也改成 --ds-*，要么把 --gray-* 明确登记为「主题契约之外的内部缩放层」——这是设计系统层面的口径问题，所以我没有擅自决定，继续挂在本条 issue 下。

3. 说明守卫的能力边界（已在守卫头部与 §6.4 写明）

守卫是静态文本检查：抓不到两条都读 token 的规则之间的级联冲突（也就是 #339 的成因），也抓不到插件自带 CSS。族规则是固定清单，不等于覆盖整个渲染器。因此「缺口可被自动发现」这条能力只对「新增裸字面量」成立，级联类问题仍必须靠评审，我在 §6.4 把它写成了明文约定供评审引用。