docs: 完善前端样式开发规范

docs/development/frontend.md

@@ -41,30 +41,74 @@
 
 ## 样式开发规范
 
-前端基于 Ant Design 构建 UI。样式开发优先级：
+前端基于 Ant Design 构建 UI。样式管理目标是让 antd 继续承担主视觉系统，项目 CSS 只补足页面外壳、局部布局和自有组件视觉，不另起一套与 antd 竞争的样式体系。
 
-1. antd 组件
-2. 组件 props
-3. antd Design Token / CSS 变量（--ant-\*）
-4. styles.css CSS 类
-5. 自行开发组件
+样式开发优先级：
+
+1. antd 组件默认能力，例如 `Button`、`Card`、`Table`、`Form`、`Result`、`Empty`。
+2. antd 组件 props，例如 `size`、`type`、`variant`、`color`、`status`、`layout`、`scroll`、`gutter`。
+3. antd 布局组件，例如 `Layout`、`Flex`、`Space`、`Row`、`Col`，避免为普通排列关系新增 CSS。
+4. `ConfigProvider` theme token 和 antd 组件 token，处理主题级或组件级统一调整。
+5. antd CSS 变量（`--ant-*`），用于项目自有 CSS 中引用颜色、间距、字体、圆角和阴影等设计值。
+6. 全局 CSS，仅承载应用外壳、全局基础样式和少量明确复用的工具类。
+7. CSS Modules，用于页面专属布局或项目自有组件视觉；仅在局部样式增长到需要就近维护时使用。
+8. 自行开发视觉组件，仅在 antd 组件和组合方式无法表达明确产品需求时使用。
 
 红线：
 
-- 严禁在组件中使用 style 属性内联调整样式
-- 严禁通过 CSS 覆盖 antd 组件内部类名
-- 严禁使用 !important
-- 颜色统一使用 antd Design Token / CSS 变量，不使用硬编码色值
+- 严禁在组件中使用 `style` 属性内联调整样式。
+- 严禁通过 CSS 覆盖 antd 组件内部类名，例如 `.ant-*`。
+- 严禁使用 `!important`。
+- 颜色统一使用 antd Design Token / CSS 变量，不使用硬编码色值。
+- 默认不引入 Tailwind、UnoCSS、Sass、Less、CSS-in-JS 或额外 PostCSS 插件；确需引入时必须先说明现有 antd + CSS Modules 无法满足的具体问题、影响范围和迁移成本。
 
 默认状态原则：如果 antd 组件默认样式已经满足当前需求，不为其增加额外 CSS 类；不要通过外层 CSS 修改 Sider、Menu、Table、Modal 等组件内部结构样式。
 
-styles.css 组织：
+全局 CSS 归属：
 
-- 自定义 CSS 变量定义在 :root 中
-- 布局类仅定义全局页面外壳，例如 `app-layout`、`app-header`、`app-content`
-- 组件修饰类仅用于项目自有视觉组件，不用于覆盖 antd 内部结构
-- 通用工具类必须有明确复用场景；只有一处使用时优先改为 antd 布局组件或局部结构
-- AppShell 可以保留最小必要样式，如页面高度、Header 内容分布和 Content 间距
+- 当前入口保留 `src/web/styles.css`；当文件继续增长时，优先拆分为 `src/web/styles/global.css`、`src/web/styles/app-shell.css`、`src/web/styles/utilities.css` 等按职责命名的文件，再由入口样式文件集中导入。
+- `global.css` 仅放 `html`、`body`、`:root`、字体渲染、全局背景等应用级基础样式。
+- `app-shell.css` 仅放应用外壳样式，例如 `app-layout`、`app-header`、`app-content`、Header 内容分布和主内容间距。
+- `utilities.css` 只放至少两处复用、语义稳定、不会与 antd props 重叠的工具类；只有一处使用时优先改为 antd 布局组件或局部 CSS Modules。
+- 全局类名必须带有明确前缀，应用外壳使用 `app-*`，工具类使用 `u-*`；禁止新增 `.container`、`.title`、`.content` 等容易跨页面冲突的泛名类。
+
+CSS Modules 归属：
+
+- 页面专属样式与页面就近放置，例如 `src/web/pages/projects/projects.module.css`。
+- 自有组件样式与组件就近放置，例如 `src/web/components/FooCard/foo-card.module.css`。
+- CSS Modules 中类名使用职责语义，例如 `.root`、`.toolbar`、`.summaryCard`、`.emptyState`；通过导入对象绑定到组件，避免字符串拼写散落。
+- 同一类样式只服务当前页面或组件；一旦被多处复用，应先判断能否用 antd 组件或 props 表达，再考虑提取共享组件，而不是直接提升为全局 CSS。
+- 首次实际使用 `*.module.css` 时，同步补全 TypeScript 声明和必要测试，确保类型检查与构建链路稳定。
+
+antd 定制边界：
+
+- 优先使用官方 props、theme token 和组件 token；不要因为视觉微调直接写 CSS。
+- antd v6 组件暴露 `classNames` 语义插槽时，可以把项目自有类绑定到官方稳定插槽；仍然不得选择 `.ant-*` 内部 DOM 类名。
+- 避免使用 antd `styles` 语义插槽写内联样式；如果必须使用，应先评估是否可以通过 token、CSS 变量或 CSS Modules 表达。
+- 弹窗、下拉、表格、菜单等复杂组件不依赖内部 DOM 结构做布局修补；发现必须修补时，优先调整组件组合或交互设计。
+
+token 和 CSS 变量规则：
+
+- 颜色使用 `var(--ant-color-*)`，例如文本、边框、背景和状态色。
+- 间距、字号、圆角和阴影优先使用 `var(--ant-padding-*)`、`var(--ant-margin-*)`、`var(--ant-font-size-*)`、`var(--ant-border-radius*)`、`var(--ant-box-shadow*)` 等 antd 变量。
+- 项目自定义 CSS 变量只能定义在 `:root` 或清晰的主题容器上，并且必须基于 antd token 派生；不要创建与 antd 平行的颜色、间距、字号体系。
+- 主题切换统一通过 `ConfigProvider` theme algorithm 和 token 控制，不在 CSS 中硬编码亮色或暗色分支。
+
+响应式规则：
+
+- 页面必须在桌面和移动端正常加载和可读。
+- 优先使用 antd `Flex`、`Grid`、`Table scroll`、响应式列配置处理布局收缩。
+- 媒体查询只处理页面或自有组件的布局断点；不要用媒体查询覆盖 antd 内部结构。
+- 移动端适配优先保证内容可访问、操作可点击和横向溢出可控，不追求与桌面完全一致的排版。
+
+新增样式前检查：
+
+1. 这个需求是否可以由 antd 组件或 props 完成？
+2. 这个样式是否属于主题级统一调整，应该放到 `ConfigProvider` theme token？
+3. 这个样式是否只服务页面外壳，应该留在全局 CSS？
+4. 这个样式是否只服务单个页面或自有组件，应该使用 CSS Modules？
+5. 这个样式是否在覆盖 antd 内部结构？如果是，应重新设计组件组合。
+6. 这个样式是否引入了硬编码色值、`style`、`.ant-*` 或 `!important`？如果是，不应合入。
 
 ## 表单与交互规范