# Ant Design（AntD）设计规范导出（v5）

> 说明：本文档基于 Ant Design v5 官方文档与设计令牌（Design Token）整理，用于项目内统一 UI 口径。若与线上文档不一致，以官方文档与实际 `token` 输出为准。
>
> 参考：
> - Ant Design 文档：`https://ant.design/docs/react/introduce`
> - 主题定制（Design Token）：`https://ant.design/docs/react/customize-theme`
> - CSS Variables：`https://ant.design/docs/react/css-variables`

## 1. 设计原则（适用于业务后台）

- **清晰**：信息层级明确（标题/正文/辅助信息/弱提示），减少不必要装饰。
- **一致**：同类型组件在同场景下外观与交互一致（按钮语义、表单校验、弹窗页脚等）。
- **高效**：高频任务优先（表格筛选、快捷操作、批量处理），减少路径长度。
- **可控**：可预期的反馈（加载/成功/失败/空态），避免“无响应”与不可逆操作。

## 2. 视觉基础（Design Token 口径）

### 2.1 色彩（Color）

#### 语义色（常用）

- **主色（Primary）**：品牌/主要操作按钮/高亮状态  
  - AntD v5 默认：`colorPrimary = #1677ff`
- **成功（Success）**：成功态、完成态、正向结果
- **警告（Warning）**：需要注意但不阻断流程
- **错误（Error）**：失败、阻断、危险操作
- **信息（Info）**：中性提示（一般与 Primary 同系或更弱）

#### 文本与背景（建议层级）

- **正文主文本**：用于标题、正文关键值
- **次级文本**：用于说明、辅助信息
- **弱文本**：用于占位、不可用、次要信息
- **容器背景**：页面背景、卡片/表格容器背景
- **分割/边框**：分割线、边框、表格网格线

> 落地建议：**不要直接手写颜色值**，优先使用 AntD token（如 `colorText` / `colorBgContainer` / `colorBorder` / `colorPrimary`），避免暗色模式或主题切换时失控。

### 2.2 字体（Typography）

- **基础字号**：AntD v5 默认 `fontSize = 14px`
- **字号体系**：在正文 14 的基础上，常用 `12/14/16/20/24`（具体以 token 为准）
- **字重**：正文 400，标题/强调 500/600（按设计与字体实际支持）
- **行高**：正文建议 1.4–1.6 区间；表格/表单密集场景可略收紧但要保证可读性

落地建议：
- 表单 label、辅助说明、错误提示使用 **次级/弱** 文本层级，避免与正文抢占注意力。
- 数字与金额在表格中建议 **右对齐**，并用等宽数字特性（如字体支持 `font-variant-numeric: tabular-nums`）提升可扫读性。

### 2.3 间距（Spacing）

推荐用 8px 网格作为基础节奏（token 会覆盖实际值）：
- **4/8/12/16/24/32**：常用间距档位
- 表单项上下间距、卡片内边距、区块间距尽量统一

落地建议：
- 页面区块：24（区块间）
- 卡片/容器内边距：16 或 24
- 表单项间距：16（常规）/ 12（密集）

### 2.4 圆角（Radius）

- AntD v5 默认 `borderRadius = 6px`  
  常见分层：`2/4/6/8`（不同组件会使用不同层级）

落地建议：
- 不要在同一页面混用多个“视觉上相近但不一致”的圆角（例如 4 与 6 随意混用）。

### 2.5 阴影与层级（Shadow & Elevation）

典型层级：
- **容器浮层**：Popover/Dropdown/Tooltip
- **对话框**：Modal
- **抽屉**：Drawer（靠近边缘）

落地建议：
- 阴影仅用于表达“悬浮/层级”，不要把阴影当分割线使用。

### 2.6 动效（Motion）

- **有意义**：动效用于表达状态变化（展开/收起/加载/反馈），避免纯装饰。
- **短而稳**：后台系统建议偏短时长，降低等待感；重要确认可以稍长但不要拖沓。
- **可中断**：用户快速操作时动效不应叠加导致卡顿或错位。

## 3. 布局与栅格（Layout & Grid）

- 使用 `Row/Col` 或 `Space/Flex` 组织布局，避免大量手写 margin 拼接。
- 表单与筛选区建议固定结构：
  - **筛选区**（可折叠）
  - **操作区**（主按钮 + 次按钮 + 批量操作）
  - **表格区**
  - **分页/汇总**
- 页面建议采用“标题 + 关键指标/说明 + 主体内容”层级，减少首屏信息噪声。

## 4. 组件使用规范（后台高频）

### 4.1 Button（按钮）

- **主按钮（Primary）**：每个视图/弹窗**尽量只有一个**主按钮（最主要动作）。
- **次按钮（Default）**：辅助动作、返回、取消。
- **危险（Danger）**：删除/作废/清空等不可逆操作，必须配确认（Popconfirm/Modal.confirm）。
- **禁用态**：禁用必须有原因（提示或辅助文案），避免“为什么点不了”。

弹窗页脚建议顺序（从右到左）：**主操作** → 次操作（取消/关闭）。

### 4.2 Form（表单）

- 校验提示就近展示，错误文案可读且可执行（告诉用户怎么改）。
- 必填项统一标识；不要同页混用不同必填标记策略。
- 长表单建议分组（Card/Collapse/Steps），并提供保存草稿/分步提交（视业务复杂度）。

### 4.3 Table（表格）

- 列宽：关键列固定宽度，描述列可自适应；避免全自适应导致抖动。
- 对齐：金额/数量 **右对齐**；状态/标签可居中；文本默认左对齐。
- 操作列：避免超过 3 个直出操作；其余收纳到 Dropdown/More。
- 空态：提供原因与下一步（调整筛选/新建/刷新）。

### 4.4 Modal / Drawer（弹窗/抽屉）

- **Modal**：用于强打断、需要确认的任务；内容不宜过长。
- **Drawer**：用于不中断上下文的编辑/详情；适合较长内容或分区信息。
- 关闭方式：提供右上角关闭；重要内容关闭需二次确认（有未保存变更时）。

### 4.5 Message / Notification / Alert（反馈）

- **Message**：短反馈（保存成功/复制成功），不承载复杂信息。
- **Notification**：较长信息、异步结果、可操作提示（带按钮/链接）。
- **Alert**：页面内静态提示/规则说明/风险提示。

落地建议：错误信息尽量包含 **定位信息 + 原因 + 建议动作**（例如“金额格式不合法，请输入最多两位小数”）。

## 5. 主题与 Token “导出”（工程落地）

### 5.1 通过 `ConfigProvider` 统一主题

在应用入口用 `ConfigProvider` 设置全局 token（示意）：

```tsx
import { ConfigProvider, theme } from 'antd';

export function App() {
  return (
    <ConfigProvider
      theme={{
        algorithm: theme.defaultAlgorithm,
        token: {
          colorPrimary: '#1677ff',
          borderRadius: 6,
          fontSize: 14,
        },
        components: {
          // 组件级 token 覆盖（按需）
        },
      }}
    >
      {/* routes */}
    </ConfigProvider>
  );
}
```

### 5.2 在页面/组件中打印当前 token（用于“导出当前主题规范”）

你可以在任意页面临时输出（开发态）：

```tsx
import { theme } from 'antd';

export function DebugTokens() {
  const { token } = theme.useToken();
  // 控制台复制即可作为“当前工程实际 token 导出”
  console.log('antd token =>', token);
  return null;
}
```

如果需要生成 JSON 文件，可以把 `token` 序列化后下载（浏览器端）：

```ts
export function downloadJson(filename: string, data: unknown) {
  const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json;charset=utf-8' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}
```

## 6. 默认关键值速查（AntD v5）

- **主色**：`#1677ff`
- **基础字号**：`14px`
- **默认圆角**：`6px`

> 注：完整 token 以 `theme.useToken()` 输出为准（因为你的工程可能有覆盖）。