test(css): restore renderer style contracts and governance

[somewan820]

背景

这是一版保守的 CSS 治理提交，目标是先把 renderer CSS 的真实结构、契约测试和治理护栏重新对齐，避免 styles.css 路径漂移、入口文件失真，以及 Tailwind v4 layer/cascade 回归。

本次提交参考了：

• issue styles.css 优化 #253
• PR fix(css): revert #257 @layer wrapping — sidebar content was centered #260 的 layer / utility 覆盖风险结论
• 上游已合入的 stale contract refresh（test(desktop): refresh stale contract checks #262）

主要改动

1. 恢复 contract tests 对真实 renderer CSS 的覆盖

• 新增 css-test-helpers.ts / contract-css-helpers.ts
• 将多处 contract test 从只读取 apps/desktop/src/renderer/styles.css
  改为读取真实 renderer CSS 聚合内容
• 保证 styles/**/*.css 拆分后，测试仍然覆盖真实规则位置，而不是扫一个已经失真的入口文件

2. 将 styles.css 收敛为真正的 entry file

• apps/desktop/src/renderer/styles.css 现在只保留：
  • @import
  • @source
  • @theme inline
• 原本的真实规则块已迁移到 styles/ 子文件
• 新增 renderer-styles-entry-contract.test.ts，锁定 entry-only 约束

3. 拆分 renderer CSS，并保留对 Tailwind utility 覆盖的安全策略

• 新增 apps/desktop/src/renderer/styles/ 多个按 surface 拆分的子文件
• 保持关键 override 规则不被误塞进 @layer components
• 新增 / 更新 renderer-style-layer-cascade-contract.test.ts
• 继续明确保护：
  • .maka-nav-row
  • .settingsHealthRefresh
  • .settingsPermissionRefresh
  • .settingsBotList button
    等需要压过 Tailwind utility 的选择器

4. 补充 CSS 治理护栏

• 新增 renderer-important-audit-contract.test.ts
• 新增 dead CSS 检查脚本：
  • scripts/check-dead-css.mjs
  • scripts/check-dead-css-baseline.json
• 清掉当前发现的 dead class，并把 baseline 收敛到 0

5. 文档化前端 CSS 规范

• 新增中文规范文档：
  • docs/frontend-css-governance.md

为什么这样做

这次没有继续激进推进“全部 layer 化”，而是优先做了更安全的治理动作：

• 先让 contract tests 扫到真实 CSS
• 先让 styles.css 回到入口文件职责
• 继续保留对 Tailwind utility override 的防回归护栏
• 用脚本和契约测试把 !important、dead CSS、entry-only、cascade 风险固定下来

这样后续如果继续推进 Round G / Round H，可以在更可信的安全网下逐步演进，而不是在失真的测试覆盖上改结构。

验证

已验证：

• npm run build:main
• node scripts/check-dead-css.mjs --check

关键 contract tests 已通过：

• renderer-important-audit-contract
• renderer-style-layer-cascade-contract
• renderer-styles-entry-contract
• project-context-badge
• bot-settings-ui-contract
• local-memory-ui-contract

风险说明

主要风险仍然集中在 Tailwind v4 的 cascade 顺序：

• base -> components -> utilities
• 任何试图覆盖 utility 的 bespoke selector，如果误放进 @layer components，都会静默失效

[jackwener]

@somewan820 @WAWQAQ 看完了，方向很好但 base 太旧、会回归我今天合的 selector 状态契约，建议先 rebase 再 review/merge。

大方向同意

• styles.css 收敛成 entry-only（仅 @import / @source / @theme inline）✓
• 按 surface 拆分到 styles/ 子文件夹 ✓
• 把 contract test 从单文件读取改成 readAllRendererCss() 聚合读取 ✓ —— 这一改让 @kenji 的 selector inventory guard（PR test(styles): guard renderer style selector inventory #256）依然有效，思路对
• 新增 renderer-styles-entry-contract.test.ts 把 entry-only 约束锁住 ✓
• renderer-important-audit-contract.test.ts + dead CSS 脚本 ✓

关键 blocker：base 太旧导致 selector 状态回归

这个 PR 的 base 是 04f6ab73，离当前 main（origin/main）有 146 个 commit。今天我和 @kenji 在 main 上 squash 了 16+ 个 CSS 治理 / primitive 化的 PR（#236 #237 #238 #240 #244 #247 #249 #250 #254 #255 #263 #265 #266 #267 #268；#256 #258 等是 kenji 的）。两组关键状态契约这个 PR 当前没拿到：

1. .settingsThemeOption 选中态选择子已变（PR #263 - ChoiceCard primitive）

本 PR diff 里仍是：

.settingsThemeOption[data-active="true"] {

当前 main 是 [data-checked]（Base UI Radio.Root 通过 ChoiceCard primitive 渲染时设置的状态属性）。如果合入，主题/调色板的选中态在视觉上会失效（CSS 选择器匹配不到被渲染的 data-checked 属性）。

2. .settingsSegmented button 选中态选择子已变（PR #268 - SettingsSegmented primitive）

本 PR diff 里仍是：

.settingsSegmented button[data-active="true"] {

当前 main 是 button[data-pressed]（Base UI ToggleGroup 通过 SettingsSegmented primitive 设置的状态属性）。如果合入，所有 Segmented 控件的选中 pill 视觉会失效。

3. 其它已 retired 的 dead selector 可能被复活

当前 main 上 @kenji 的 inventory guard + retired-hooks list 已经把这些 selector 钉死必须不存在：

• connectionStatus、providerCatalog、maka-nav-primary、maka-skill-workbench-rail、modePill 等共 17 条
• 本 PR base 时还没删；如果不 rebase，这些可能在 styles/*.css 拆分文件里复活，contract test 会红。

4. 其它今天的小型变更也会丢

• 重复 .settingsRow flex 规则的 dedup（chore(css): drop dead duplicate .settingsRow flex rule #266）
• 3 块合并的 .maka-onboarding-quickchat-submit（chore(css): merge 3 duplicate .maka-onboarding-quickchat-submit rule blocks #267）
• .settingsBaseSelectTrigger → .settingsSelectTrigger（refactor(ui,settings): unify Select wrappers into one primitive + dead selector sweep #254）：本 PR diff 里看起来包含了，但需要确认拆分后归属是否正确

建议路径

1. 先 rebase 到 origin/main：处理 146 个 commit 的冲突。重点检查：
   • 所有 [data-active="true"] → [data-checked] / [data-pressed] 的转写有没有传过来
   • retired-hooks contract test 的 list 是不是包含完整 17 条（不是合并前的 12 条）
2. rebase 后跑两个 contract test 确认绿：
   • renderer-style-pruning-contract.test.ts（kenji 的 inventory guard）
   • settings-theme-contract.test.ts（我的 ChoiceCard + SettingsSegmented lock）
3. 如果 styles/*.css 重新分配后 selector 跨文件移动了：确保 .settingsThemeOption、.settingsSegmented button、.settingsSelectTrigger 等几个 primitive-backed 的 chrome 规则都在同一个 styles/settings/*.css 文件里，避免 cascade 顺序漂。
4. check-dead-css.mjs 基线 JSON：rebase 后可能要重新生成，因为今天 retired 的 selector list 变了。

总结

PR #264 的治理方向是对的，contract test 改成读 aggregated CSS 也聪明。但 base 太旧导致 selector 状态契约会回归 — 主题选中态 + Segmented 选中态都会黑掉。先 rebase + 跑通两个状态 contract test 再合，我这边可以帮忙复核。

我自己今天 styles.css 已经从 14066 → 缩了多次，会跟你 rebase 的工作叠合，不会再继续往 styles.css 加新规则，把这条线让给你这个 PR，避免再次互相覆盖。

[somewan820]

收到，感谢详细的 review。会先 rebase 到 origin/main，重点修 [data-active] →
[data-checked] / [data-pressed] 两处选择器回归，顺带确认 retired-hooks 列表完整，
rebase 完重新生成 dead-css 基线，搞定后再请你复核。

[somewan820]

@jackwener 已经修改好了🥺非常抱歉，下次一定注意～

[jackwener]

@somewan820 rebase looks great — base is now on 01b18c91 (current main with my #265 / #266 / #267 / #268 + your #263 review). 2 critical regressions from my first review fixed ✓:

• .settingsThemeOption[data-checked] ✓
• .settingsSegmented button[data-pressed] ✓

But running the full contract test suite turned up 2 more issues I think need fixing before merge:

1. motion-token-converge-contract.test.ts fails (introduced by the split)

Now that readAllRendererCss() expands @import chains, the styles blob includes maka-tokens.css — including its legitimate --ease-out-strong: cubic-bezier(0.16, 1, 0.3, 1); token declaration. The bare-curve assertion in motion-token-converge-contract.test.ts:30 now trips on the token file's own definition (1 match where 0 are allowed).

Fix (1-line): strip TOKEN_DECL from the merged styles blob before counting — mirror the same strip the test already does for the tokens-file branch:

const styles = stripCssComments(await readAllRendererCss()).replace(TOKEN_DECL, '');

2. settings-roadmap-cleanup-contract.test.ts fails — unrelated copy edit

apps/desktop/src/renderer/settings/SettingsModal.tsx:1598 was rewritten from '当前版本仅本地数字聚合，定时生成 / LLM 摘要尚未连接到后端。' → '当前版本仍以本地汇总为主；定时生成 / LLM 摘要尚未连接到后端。'. The pre-existing settings-roadmap-cleanup-contract pins the original phrase and now fails on the rebased PR.

Fix: revert this single line. This PR's scope is CSS governance; the copy edit looks accidental, and the contract test pin should stay authoritative.

Both fixes pushed for cherry-pick

I cherry-picked the rebased PR onto my own branch and applied both fixes there: https://github.com/maka-agent/maka-agent/tree/yuejing/pr264-fixup

Specifically:

• 1fd0b09f test(motion): strip --ease-out-strong declaration before scanning expanded CSS
• 519e684e fix(daily-review): revert unrelated copy edit that breaks roadmap-cleanup contract

You can either cherry-pick those 2 commits onto your branch, or @WAWQAQ can merge from my branch — whichever is easier. After either of those, all 431 contract tests pass locally on my fixup branch.

Test verification (on my fixup branch)

apps/desktop$ npx tsx --test src/main/__tests__/*-contract.test.ts
ℹ tests 431  ℹ pass 431  ℹ fail 0

The big picture (file split + entry-only styles.css + readAllRendererCss helper + new entry/important/cascade contracts + dead-CSS script) all checks out. Excellent direction.

[jackwener]

Superseded by #269 (rebase + 2 fixup commits for motion-token + roadmap-cleanup contracts). Same intent, all 431 contract tests green there. Thank you for the big CSS-split work @somewan820 — credit preserved in #269's commits ffaf3f9 + 8154f4e.