# 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`