a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
158 lines
6.9 KiB
Markdown
158 lines
6.9 KiB
Markdown
# Ant Design（ANTD）设计规范
|
||
|
||
> 本文档汇总 **Ant Design 官方设计理念** 与 **在本仓库（ONE-OS / web 端原型）中的落地约定**。
|
||
> 官方参考：[设计价值观](https://ant.design/docs/spec/values-cn) · [设计模式](https://ant.design/docs/spec/overview-cn) · [组件总览](https://ant.design/components/overview-cn)
|
||
|
||
主题内更细的 Token 与主题说明见：`axhub-make/src/themes/antd-new/DESIGN.md`。
|
||
|
||
---
|
||
|
||
## 一、产品定位与适用场景
|
||
|
||
Ant Design 面向 **企业级中后台**：数据密集、流程复杂、角色多样。目标是 **降低协作成本、保证一致性、提升交付效率**。
|
||
|
||
| 适合 | 需谨慎 |
|
||
|------|--------|
|
||
| 管理后台、运营台、审批与报表 | 强品牌 C 端营销页（需额外视觉体系） |
|
||
| 表单、表格、筛选、仪表盘 | 与另一套 UI 库混用（易产生样式与交互冲突） |
|
||
| 内部工具、B 端 SaaS | 极简移动端 H5（可评估 [Ant Design Mobile](https://mobile.ant.design)） |
|
||
|
||
---
|
||
|
||
## 二、四大设计价值观（官方）
|
||
|
||
设计语言层面的「为什么这样设计」，实现组件与文档时应与之对齐。
|
||
|
||
### 1. 自然（Natural）
|
||
|
||
- 感知、行为符合用户习惯，减少刻意学习与记忆。
|
||
- 文案、隐喻贴近真实业务场景，避免生造概念。
|
||
- 动效克制，用于说明状态与空间关系，而非炫技。
|
||
|
||
### 2. 确定性（Certainty）
|
||
|
||
- **设计确定性**：模式可预期（同类操作用同类组件与布局）。
|
||
- **实现确定性**：设计 Token、组件 API 稳定，减少「同一需求多种写法」。
|
||
- **用户心智确定性**：同一语义的按钮、颜色、反馈在全站一致。
|
||
|
||
### 3. 意义感（Meaning）
|
||
|
||
- 每个元素应有清晰目的：为何展示、为谁服务、与上下游任务的关系。
|
||
- 避免为填满版面而堆组件；信息层级服务于 **主任务路径**。
|
||
|
||
### 4. 生长感（Growth）
|
||
|
||
- 系统随业务扩展：模块、主题、国际化可演进。
|
||
- 优先使用 Token / `ConfigProvider` 扩展，而非大量硬编码覆盖组件内部样式。
|
||
|
||
---
|
||
|
||
## 三、页面与交互层面的设计原则（落地检查清单）
|
||
|
||
在画原型或写页面时，可逐条对照（与 Arco 等体系表述不同，但可并行使用）。
|
||
|
||
| 原则 | 要求 |
|
||
|------|------|
|
||
| **Stay on the Page** | 能在当前页完成的，尽量不跳转；必要时用抽屉、步骤条、标签页拆分。 |
|
||
| **React Immediately** | 点击、提交、加载、成功/失败要有即时可见反馈（按钮 loading、表格骨架屏、`message` 等）。 |
|
||
| **Provide an Invitation** | 主操作、可编辑区域通过主次按钮、留白与分组被自然发现。 |
|
||
| **Make it Direct** | 能直接点的不要藏三层菜单；表格行内操作与批量操作语义区分清楚。 |
|
||
| **Keep it Lightweight** | 同一屏信息密度可控；复杂筛选可折叠或分步；避免无意义装饰。 |
|
||
| **Use Transition** | 展开/收起、抽屉、模态出现与消失使用组件自带动效，保持节奏一致。 |
|
||
|
||
---
|
||
|
||
## 四、视觉与 Token（摘要）
|
||
|
||
详细数值与分类见 `axhub-make/src/themes/antd-new/DESIGN.md`。此处仅列 **命名与用法约定**。
|
||
|
||
### 1. 色彩语义
|
||
|
||
- **主色（Primary）**：主按钮、链接、关键选中态。
|
||
- **功能色**：Success / Warning / Error / Info 仅表达对应语义，不混用作装饰。
|
||
- **中性色**：标题、正文、次要说明、边框、背景层级与 antd 文字色阶梯对齐。
|
||
|
||
### 2. 间距与布局
|
||
|
||
- 以 **4px 基准网格** 思考间距；列表、表单优先用 `Space`、`Row`/`Col` 而非零散 `margin`。
|
||
- 使用 **24 栅格** 做响应式分栏；断点含义与 antd 文档一致。
|
||
|
||
### 3. 字体与层级
|
||
|
||
- 正文默认 **14px**；标题用 `Typography.Title` 层级，避免随意放大字号破坏韵律。
|
||
- 辅助说明可用 **12px** 次要色，但需保证对比度与可读性。
|
||
|
||
### 4. 圆角与层级
|
||
|
||
- 控件与卡片圆角与主题 Token 一致；弹层类（Modal、Dropdown）阴影强于内容区卡片，体现 **Z 轴层级**。
|
||
|
||
---
|
||
|
||
## 五、组件选用与反馈层级
|
||
|
||
### 1. 反馈方式选择
|
||
|
||
| 场景 | 推荐 |
|
||
|------|------|
|
||
| 操作成功/失败一句话 | `message` |
|
||
| 需稍后查看或带标题的通告 | `notification` |
|
||
| 需用户明确确认或中断流程 | `Modal` / `Popconfirm` |
|
||
| 复杂表单、多步编辑、详情+编辑 | `Drawer` 或独立页 |
|
||
| 行内轻确认 | `Popconfirm` |
|
||
|
||
原则：**能不打断主流程就不弹 Modal**；全局提示不要过于频繁堆叠。
|
||
|
||
### 2. 表单
|
||
|
||
- 使用 **Form** 管理字段、校验与提交；标签、必填星号、错误信息与 antd 默认模式一致。
|
||
- 长表单：分组（`Divider` / 卡片）、分步（`Steps`）或分 Tab，避免单屏过长。
|
||
|
||
### 3. 表格
|
||
|
||
- **小数据**：常规分页即可。
|
||
- **大数据**：虚拟滚动、列固定、合理 `scroll`；避免无分页的一次性超大渲染。
|
||
- 操作列：主次分明（主操作用 `Button type="link"` 或主色按钮，危险操作用 `danger` + 二次确认）。
|
||
|
||
### 4. 按钮语义
|
||
|
||
| 类型 | 用途 |
|
||
|------|------|
|
||
| `primary` | 每区块/每弹窗 **唯一** 主路径提交或强引导 |
|
||
| `default` | 次要操作 |
|
||
| `dashed` | 添加、可选扩展 |
|
||
| `link` | 表格行内、弱干扰文字链 |
|
||
| `text` | 工具栏内轻量操作 |
|
||
|
||
---
|
||
|
||
## 六、无障碍与国际化（建议）
|
||
|
||
- **键盘**：焦点顺序合理，Modal 打开后焦点 trap；可交互元素可被 Tab 聚焦。
|
||
- **颜色**：不单独依赖颜色传达状态（配合图标、文案）。
|
||
- **文案**：按钮与标题用 **动词或动宾结构**（如「设为已读」「导出报表」）；错误信息说明原因与下一步。
|
||
- **国际化**：面向多语言时避免写死拼接顺序，使用参数化文案；日期数字格式交给 `ConfigProvider` locale。
|
||
|
||
---
|
||
|
||
## 七、在本项目中的开发约定（web 端 JSX 原型）
|
||
|
||
1. **入口**：通过 `window.antd` 取组件时，保持与官方 API 一致，避免魔改组件封装导致文档与代码脱节。
|
||
2. **主题**：全局主题以 `ConfigProvider` + Token 为准；局部特殊色尽量与 Token 映射一致，减少 `#` 硬编码。
|
||
3. **样式覆盖**：优先 `className` + 外层布局控制；避免对 `.ant-*` 大段 `!important`。
|
||
4. **一致性**：同一业务场景（如列表筛选、详情抽屉）在不同页面复用相同结构与组件组合，便于用户形成习惯。
|
||
|
||
---
|
||
|
||
## 八、文档与协作
|
||
|
||
- 新增复杂页：在原型或 PR 中说明 **主任务、信息架构、关键反馈** 与本文档哪几条原则对应。
|
||
- 与设计师对齐时：以 antd 组件名为沟通基准，减少「自定义组件名」与实现不一致。
|
||
|
||
---
|
||
|
||
## 九、延伸阅读
|
||
|
||
- [定制主题](https://ant.design/docs/react/customize-theme-cn)
|
||
- [从 v4 到 v5](https://ant.design/docs/react/migration-v5-cn)（若仓库存在混版本引用）
|
||
- 仓库内主题细则：`axhub-make/src/themes/antd-new/DESIGN.md`
|