docs: 完善前端样式开发规范
This commit is contained in:
@@ -41,30 +41,74 @@
|
|||||||
|
|
||||||
## 样式开发规范
|
## 样式开发规范
|
||||||
|
|
||||||
前端基于 Ant Design 构建 UI。样式开发优先级：
|
前端基于 Ant Design 构建 UI。样式管理目标是让 antd 继续承担主视觉系统，项目 CSS 只补足页面外壳、局部布局和自有组件视觉，不另起一套与 antd 竞争的样式体系。
|
||||||
|
|
||||||
1. antd 组件
|
样式开发优先级：
|
||||||
2. 组件 props
|
|
||||||
3. antd Design Token / CSS 变量（--ant-\*）
|
1. antd 组件默认能力，例如 `Button`、`Card`、`Table`、`Form`、`Result`、`Empty`。
|
||||||
4. styles.css CSS 类
|
2. antd 组件 props，例如 `size`、`type`、`variant`、`color`、`status`、`layout`、`scroll`、`gutter`。
|
||||||
5. 自行开发组件
|
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 属性内联调整样式
|
- 严禁在组件中使用 `style` 属性内联调整样式。
|
||||||
- 严禁通过 CSS 覆盖 antd 组件内部类名
|
- 严禁通过 CSS 覆盖 antd 组件内部类名，例如 `.ant-*`。
|
||||||
- 严禁使用 !important
|
- 严禁使用 `!important`。
|
||||||
- 颜色统一使用 antd Design Token / CSS 变量，不使用硬编码色值
|
- 颜色统一使用 antd Design Token / CSS 变量，不使用硬编码色值。
|
||||||
|
- 默认不引入 Tailwind、UnoCSS、Sass、Less、CSS-in-JS 或额外 PostCSS 插件；确需引入时必须先说明现有 antd + CSS Modules 无法满足的具体问题、影响范围和迁移成本。
|
||||||
|
|
||||||
默认状态原则：如果 antd 组件默认样式已经满足当前需求，不为其增加额外 CSS 类；不要通过外层 CSS 修改 Sider、Menu、Table、Modal 等组件内部结构样式。
|
默认状态原则：如果 antd 组件默认样式已经满足当前需求，不为其增加额外 CSS 类；不要通过外层 CSS 修改 Sider、Menu、Table、Modal 等组件内部结构样式。
|
||||||
|
|
||||||
styles.css 组织：
|
全局 CSS 归属：
|
||||||
|
|
||||||
- 自定义 CSS 变量定义在 :root 中
|
- 当前入口保留 `src/web/styles.css`；当文件继续增长时，优先拆分为 `src/web/styles/global.css`、`src/web/styles/app-shell.css`、`src/web/styles/utilities.css` 等按职责命名的文件，再由入口样式文件集中导入。
|
||||||
- 布局类仅定义全局页面外壳，例如 `app-layout`、`app-header`、`app-content`
|
- `global.css` 仅放 `html`、`body`、`:root`、字体渲染、全局背景等应用级基础样式。
|
||||||
- 组件修饰类仅用于项目自有视觉组件，不用于覆盖 antd 内部结构
|
- `app-shell.css` 仅放应用外壳样式，例如 `app-layout`、`app-header`、`app-content`、Header 内容分布和主内容间距。
|
||||||
- 通用工具类必须有明确复用场景；只有一处使用时优先改为 antd 布局组件或局部结构
|
- `utilities.css` 只放至少两处复用、语义稳定、不会与 antd props 重叠的工具类；只有一处使用时优先改为 antd 布局组件或局部 CSS Modules。
|
||||||
- AppShell 可以保留最小必要样式，如页面高度、Header 内容分布和 Content 间距
|
- 全局类名必须带有明确前缀，应用外壳使用 `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`？如果是，不应合入。
|
||||||
|
|
||||||
## 表单与交互规范
|
## 表单与交互规范
|
||||||
|
|
||||||
|
|||||||
@@ -18,6 +18,7 @@ context: |
|
|||||||
- 后端库使用优先级：Bun 内置 API > es-toolkit > 主流三方库 > 项目公共工具 > 自行实现
|
- 后端库使用优先级：Bun 内置 API > es-toolkit > 主流三方库 > 项目公共工具 > 自行实现
|
||||||
- src/web目录下是基于Bun HTML import、React、Ant Design实现的前端代码
|
- src/web目录下是基于Bun HTML import、React、Ant Design实现的前端代码
|
||||||
- 前端最高规约：优先使用 antd 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节遵循 docs/development/frontend.md
|
- 前端最高规约：优先使用 antd 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节遵循 docs/development/frontend.md
|
||||||
|
- 前端样式管理：antd 组件/props/token 优先，AppShell 使用最小全局 CSS，页面和自有组件样式增长后使用就近 CSS Modules，默认不引入 Tailwind、UnoCSS、Sass、Less、CSS-in-JS 等额外样式体系
|
||||||
- 前端样式红线：禁止组件内联 style、覆盖 antd 内部类名、使用 !important、硬编码色值
|
- 前端样式红线：禁止组件内联 style、覆盖 antd 内部类名、使用 !important、硬编码色值
|
||||||
- Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
|
- Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
|
||||||
- 禁止创建git操作task
|
- 禁止创建git操作task
|
||||||
|
|||||||
Reference in New Issue
Block a user