Files
maka/docs/frontend-css-governance.zh-CN.md
T
agent-radar 7be535059e
Dependency audit / audit (push) Canceled after 0s
CI / plan (push) Canceled after 0s
Gitoxide helper admission / macos-latest (push) Canceled after 0s
Gitoxide helper admission / ubuntu-latest (push) Canceled after 0s
Gitoxide helper admission / windows-latest (push) Canceled after 0s
Runtime Host peer admission / quality (push) Canceled after 0s
Windows recovery / windows_recovery (push) Canceled after 0s
CI / heavy (push) Canceled after 0s
CI / test (push) Canceled after 0s
源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
2026-09-01 19:05:14 +08:00

92 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# 前端 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 强压。
- 任何会影响级联顺序的改动,都必须配合对真实渲染结果的最小回归验证一起提交。