# 前端 CSS 治理规范 [English](./frontend-css-governance.md) 本仓库的前端样式体系由 Astryx、`@maka/ui` 产品组合样式和 renderer surface CSS 组成。级联顺序必须被明确约束,不能随意改动。 ## 1. 入口文件规则 - `apps/desktop/src/renderer/styles.css` 只能作为样式入口文件使用。 - 它只允许包含 `@import` 和顶层入口编排语句。 - 新增的 per-surface selector 规则块必须放在 `apps/desktop/src/renderer/styles/**/*.css`。 - `maka-tokens.css` 尾部的历史 recipe 和 `reference-shell.css` 是待收敛的 transitional exceptions;不要继续向这两个例外增加 surface 规则。 ### Selector 命名 - renderer 与 `@maka/ui` 的共享 selector 使用 kebab-case `.maka-*` 方言。 - 已有的 `styles/settings/**` surface 使用 camelCase `.settings*` selector;settings 内的新 selector 应延续该方言,避免同一 surface 混用两套命名。 - 在 settings 的 concern 文件之间移动现有 selector 时不要求全仓重命名;未来若统一命名,应作为显式兼容性改动单独推进。 ## 2. Layer 规则 - 纯展示规则应尽量放进: - `@layer base` - `@layer components` - 只有在构建链明确支持时,才使用 `@import "./file.css" layer(components)`。 - 不要使用 `@layer { @import ... }` 这种写法。 Astryx reset 和组件层在前,Maka base token 与产品 `components` 在后。应在最近的现有职责缝隙解决覆盖,不再增加更高优先级的兼容层。 ## 4. `!important` 使用规则 - 默认只允许两类场景使用 `!important`: - 无障碍辅助规则,例如 `.maka-visually-hidden` - reduced-motion / e2e-fixture 这类测试或可访问性覆盖 - 其他任何 `!important` 都必须同时满足: - 就地写明 `Justified:` 注释 - 如果 primitive API 或语义类可以直接表达,优先在该职责层解决,不要继续叠更多 `!important`。 ## 5. Token 规则 - 自定义 CSS 变量统一放在: - `apps/desktop/src/renderer/maka-tokens.css` - 只有组件局部变量允许例外,但必须带: - `/* local: ... */` - 禁止新增以下硬编码值: - 颜色 - radius - 未纳入约束体系的 z-index ## 6. 这些规则靠什么保证 这些规则靠评审保证。静态正确性交给 Biome、Knip 和 typecheck;accessibility 保留聚焦的检查。CSS 使用关系和 Story 文案不再由全仓 regex baseline 决定。 - renderer CSS 的行为在它真正渲染的地方验证:Storybook、app,或对真实界面的 e2e 断言。 - selector 应随其 source 或 surface 一起删除,不维护运行时字符串 allowlist。 ## 7. 推荐改动顺序 调整 renderer CSS 时,建议按下面顺序推进: 1. 把 `styles.css` 中的真实规则块迁到子文件。 2. 通用组件外观留给 Astryx,产品组合样式放在 `@maka/ui` 或对应 renderer surface。 3. 清理 dead selector。 4. 只有在 primitive / layer 架构已经稳定后,再移除剩余 `!important`。 ## 8. 当前治理原则 - 先保证 CI 护栏可信,再做结构收敛。 - 先删 dead CSS,再谈样式“美化性重构”。 - 对共享 `Button` / `Textarea` / `EmptyState` 这类 primitive 的覆盖,优先从组件接口层解决,不要长期依赖 renderer CSS 强压。 - 任何会影响级联顺序的改动,都必须配合对真实渲染结果的最小回归验证一起提交。