wiki/.claude/design-tokens.md

# UI 设计规范 — Microsoft Fluent 2 / Windows 11

> 本项目设计系统已从 Ant Design v5（阿里云风格）迁移至 **Microsoft Fluent 2**（Windows 11 风格）。
> 旧 Token 名保留不变（向后兼容），新 Token 使用 `--fluent-*` 前缀。

---

## 0. 变更日志

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-06-05 | 2.0 | 主设计系统从 Ant Design v5 迁移至 Fluent 2；品牌色 `#1677FF`→`#0078D4`；新增材质/动效/完整色彩阶梯/字体体系；`index.html` 同步重设计 |
| ~2026-05 | 1.0 | 初始版本，基于 Ant Design v5 + 阿里云控制台风格 |

---

## 1. 品牌色

### 1.1 核心品牌色

| 用途 | Token | 值 | 说明 |
|------|-------|------|------|
| 品牌主色 | `--color-primary` | `#0078D4` | Fluent 2 Communication Blue |
| 悬停态 | `--color-primary-hover` | `#106EBE` | shade-10 |
| 激活态 | `--color-primary-active` | `#005A9E` | shade-20 |
| 浅色背景 | `--color-primary-bg` | `#DEECF9` | tint-30 |

### 1.2 Fluent 2 Tint/Shade 链（新增）

```
tint-40:  #EFF6FC   最浅（微妙填充）
tint-30:  #DEECF9   浅背景 = --color-primary-bg
tint-20:  #C7E0F4   hover 填充 / focus ring
tint-10:  #2B88D8   悬停轮廓 / 强调边框
primary:  #0078D4   品牌主色 = --color-primary
shade-10: #106EBE   悬停态 = --color-primary-hover
shade-20: #005A9E   激活态 = --color-primary-active
shade-30: #004578   最深（高亮文字 / 深色背景）
```

对应 CSS Token：

| Token | 值 |
|-------|-----|
| `--fluent-primary-tint-40` | `#EFF6FC` |
| `--fluent-primary-tint-30` | `#DEECF9` |
| `--fluent-primary-tint-20` | `#C7E0F4` |
| `--fluent-primary-tint-10` | `#2B88D8` |
| `--fluent-primary-shade-10` | `#106EBE` |
| `--fluent-primary-shade-20` | `#005A9E` |
| `--fluent-primary-shade-30` | `#004578` |

---

## 2. 功能色

| 用途 | Token | 值 | Fluent 语义 |
|------|-------|------|------------|
| 成功 | `--color-success` | `#107C10` | Green (深绿，更专业) |
| 警告 | `--color-warning` | `#FF8C00` | Orange (取代琥珀色) |
| 错误 | `--color-error` | `#FF4D4F` | Red (保留 Ant Design 红，对比度更优) |

### 2.1 功能色浅色背景（新增）

| Token | 值 | 说明 |
|-------|-----|------|
| `--fluent-success-bg` | `#DFF6DD` | 成功态浅色背景 |
| `--fluent-warning-bg` | `#FFF4CE` | 警告态浅色背景 |
| `--fluent-error-bg` | `#FDE7E9` | 错误态浅色背景 |
| `--fluent-success-border` | `#A7E3A1` | 成功态边框 |
| `--fluent-warning-border` | `#FFD335` | 警告态边框 |
| `--fluent-error-border` | `#EEACB2` | 错误态边框 |

### 2.2 废弃 Token

| Token | 状态 | 说明 |
|-------|------|------|
| `--color-info` | **已移除** | 0 个文件使用，死 Token |

---

## 3. 中性色

### 3.1 Fluent 2 完整中性阶梯

```css
--fluent-neutral-0:  #FFFFFF;   纯白（页面/卡片背景）
--fluent-neutral-2:  #F8F8F8;   微妙灰
--fluent-neutral-4:  #F4F4F4;
--fluent-neutral-6:  #F2F2F2;
--fluent-neutral-8:  #EBEBEB;
--fluent-neutral-10: #E1DFDD;   边框色
--fluent-neutral-20: #C8C8C8;
--fluent-neutral-30: #A6A6A6;   占位文字 / disabled
--fluent-neutral-60: #666666;   次要文字
--fluent-neutral-70: #3C3C3C;
--fluent-neutral-80: #201F1E;   主文字
```

### 3.2 旧 Token → 新值映射（亮色）

| Token | 旧值 (AntD) | 新值 (Fluent 2) | 对应 Fluent Token |
|-------|------------|----------------|-------------------|
| `--bg` | `#F5F5F5` | `#FAF9F8` | neutral-2 |
| `--bg-container` | `#FFFFFF` | `#FFFFFF` | neutral-0 |
| `--bg-elevated` | `#FAFAFA` | `#F3F2F1` | neutral-4 |
| `--border` | `#D9D9D9` | `#E1DFDD` | neutral-10 |
| `--border-light` | `#F0F0F0` | `#EDEBE9` | neutral-8 |
| `--text-primary` | `#141414` | `#201F1E` | neutral-80 |
| `--text-secondary` | `#595959` | `#605E5C` | neutral-70 |
| `--text-tertiary` | `#8C8C8C` | `#8A8886` | neutral-60 |

### 3.3 暗色主题（`[data-theme="dark"]`）

| Token | 旧值 (AntD) | 新值 (Fluent 2 Dark) |
|-------|------------|---------------------|
| `--bg` | `#0B0F1A` / `#111111` | `#1F1F1F` |
| `--bg-container` | `#111827` / `#1C1C1E` | `#292929` |
| `--bg-elevated` | `#1A2235` / `#242426` | `#333333` |
| `--border` | `#1E2A3A` / `#3A3A3C` | `#474747` |
| `--border-light` | `#151D2E` / `#2C2C2E` | `#3D3D3D` |
| `--text-primary` | `#E8ECF1` / `#D1D1D6` | `#DADADA` |
| `--text-secondary` | `#8892A4` / `#8E8E93` | `#A0A0A0` |
| `--text-tertiary` | `#5A6478` / `#636366` | `#7A7A7A` |

暗色品牌色：

| Token | 值 |
|-------|-----|
| `--color-primary` (dark) | `#479EF5` |
| `--color-primary-bg` (dark) | `rgba(71,158,245,0.15)` |

### 3.4 透明中性色（Fluent Alpha 系列，新增）

```css
--fluent-alpha-2:  rgba(0,0,0,0.02);
--fluent-alpha-4:  rgba(0,0,0,0.04);
--fluent-alpha-8:  rgba(0,0,0,0.08);
--fluent-alpha-10: rgba(0,0,0,0.10);
--fluent-alpha-20: rgba(0,0,0,0.20);
--fluent-alpha-30: rgba(0,0,0,0.30);
--fluent-alpha-40: rgba(0,0,0,0.40);
--fluent-alpha-80: rgba(0,0,0,0.80);
```

暗色对应 `rgba(255, 255, 255, ...)`。

---

## 4. 字体规范

### 4.1 字体族

```css
/* 正文（优先 Windows 11 可变字体） */
--fluent-font-family-text: 'Segoe UI Variable Text', 'Segoe UI', system-ui,
  -apple-system, BlinkMacSystemFont, 'PingFang SC', 'Hiragino Sans GB',
  'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif;

/* 标题 / 大字号展示 */
--fluent-font-family-display: 'Segoe UI Variable Display', 'Segoe UI',
  system-ui, -apple-system, BlinkMacSystemFont, sans-serif;

/* 等宽代码 */
--fluent-font-family-monospace: 'Cascadia Code', 'Fira Code', 'SF Mono',
  'Menlo', 'Monaco', 'Courier New', monospace;

/* 旧版兼容（无 Segoe UI Variable 的旧系统自动回退） */
--font-family: var(--fluent-font-family-text);
```

### 4.2 字号阶梯（Fluent 2 Type Ramp）

| 级别 | 字号 | 行高 | 字重 | 用途 |
|------|------|------|------|------|
| Caption 2 | 10px | 14px | 400 | 极小辅助文字 |
| Caption 1 | 12px | 16px | 400 | 辅助文字 / Tag / 日期 |
| **Body 1** | **14px** | **20px** | **400** | **正文（基准）** |
| Body 1 Strong | 14px | 20px | 600 | 强调正文 |
| Subtitle 2 | 16px | 22px | 600 | 卡片标题 |
| Subtitle 1 | 20px | 26/28px | 600 | 小节标题 |
| Title 3 | 24px | 32px | 600 | 区域标题 |
| Title 2 | 28px | 36px | 600 | 页面标题 |
| Title 1 | 32px | 40px | 600 | 大标题 |
| Large Title | 40px | 52px | 600 | Hero 标题 |
| Display | 68px | 92px | 600 | 超大展示 |

**与旧版（Ant Design）差异**：
- 正文行高 `22px → 20px`（更紧凑，Fluent 标准）
- 同一字号提供 Regular/Semibold/Bold 字重变体
- 新增 Display (68px) 和 Large Title (40px) 级别

---

## 5. 圆角规范

### 5.1 旧 Token → 新值

| Token | 旧值 | 新值 (Fluent 2) | 使用场景 |
|-------|------|----------------|---------|
| `--radius-xs` | 2px | 2px | Tag、极小 Badge |
| `--radius-sm` | 6px | **4px** | 按钮、输入框（Fluent 基准） |
| `--radius-md` | 8px | **6px** | 卡片、面板 |
| `--radius-lg` | 12px | **8px** | 弹窗、大容器 |

### 5.2 新增 Fluent 命名 Token

| Token | 值 | 说明 |
|-------|-----|------|
| `--fluent-radius-none` | 0px | 无线条 |
| `--fluent-radius-small` | 2px | = `--radius-xs` |
| `--fluent-radius-medium` | 4px | = `--radius-sm` |
| `--fluent-radius-large` | 6px | = `--radius-md` |
| `--fluent-radius-xlarge` | 8px | = `--radius-lg` |
| `--fluent-radius-circular` | 9999px | 胶囊形 / 圆形 |

---

## 6. 间距规范

### 6.1 旧版（保留，标记 Legacy）

基于 8px 基准，仅 3 个文件使用：

| Token | 值 | 状态 |
|-------|-----|------|
| `--space-xs` | 4px | Legacy — 已使用 |
| `--space-sm` | 8px | Legacy — 已使用 |
| `--space-md` | 12px | Legacy — 已使用 |
| `--space-lg` | 16px | Legacy — 已使用 |
| `--space-xl` | 24px | Legacy — 已使用 |
| `--space-2xl` | 32px | Legacy — 已使用 |
| `--space-3xl` | 48px | Legacy — 已使用 |

### 6.2 Fluent 2 间距阶梯（推荐新工作使用）

基于 4px 基准，17 级：

| Token | 值 | 使用场景 |
|-------|-----|---------|
| `--fluent-spacing-2xs` | 2px | 图标对齐微调 |
| `--fluent-spacing-xs` | 4px | 极紧凑 |
| `--fluent-spacing-sm` | 8px | 小间距 |
| `--fluent-spacing-md` | 12px | 中等间距 |
| `--fluent-spacing-lg` | 16px | 标准间距 |
| `--fluent-spacing-xl` | 20px | 紧凑段落 |
| `--fluent-spacing-2xl` | 24px | 大间距 |
| `--fluent-spacing-3xl` | 28px | 区块间距 |
| `--fluent-spacing-4xl` | 32px | — |
| `--fluent-spacing-5xl` | 40px | — |
| `--fluent-spacing-6xl` | 48px | 大区块间距 |
| `--fluent-spacing-7xl` | 56px | 最大间距 |

---

## 7. 阴影与层级

### 7.1 旧 Token → 新值

| Token | 新值 (Fluent 2) |
|-------|----------------|
| `--shadow-sm` | `0 0 2px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.14)` |
| `--shadow-md` | `0 0 2px rgba(0,0,0,0.12), 0 2px 4px rgba(0,0,0,0.14)` |
| `--shadow-lg` | `0 0 2px rgba(0,0,0,0.12), 0 4px 8px rgba(0,0,0,0.14)` |

### 7.2 Fluent 2 完整 Elevation 体系（新增）

| Token | z-index 层级 | 使用场景 |
|-------|-------------|---------|
| `--fluent-shadow-2` | 100 | 卡片静止态 |
| `--fluent-shadow-4` | 200 | 卡片悬停 / Tooltip |
| `--fluent-shadow-8` | 300 | 下拉菜单 / Flyout |
| `--fluent-shadow-16` | 400 | 对话框 / Modal |
| `--fluent-shadow-28` | 500 | 抽屉侧栏 / 教学气泡 |
| `--fluent-shadow-64` | 600 | 通知 / Toast |

### 7.3 z-index 层级表

| 层级 | z-index | 元素 |
|------|---------|------|
| Base | 0 | 正文内容 |
| Sticky | 90 | Chip 筛选栏 |
| Header | 100 | 顶栏 / 卡片静止 |
| Overlay | 200 | 遮罩层 / Tooltip |
| Flyout | 300 | 下拉菜单 |
| Modal | 400 | 模态弹窗 |
| Drawer | 500 | 抽屉 |
| Toast | 600 | 通知 |

---

## 8. 材质效果（Fluent 2 独有，新增）

### 8.1 Acrylic（亚克力）

半透明模糊材质，用于导航栏、侧栏面板：

```css
--fluent-acrylic-default: rgba(255, 255, 255, 0.7);
--fluent-acrylic-dark:    rgba(47, 47, 47, 0.85);
--fluent-backdrop-blur:   40px;

/* 使用示例 */
.header {
  background: var(--fluent-acrylic-default);
  backdrop-filter: blur(var(--fluent-backdrop-blur)) saturate(125%);
  border-bottom: 0.5px solid var(--fluent-alpha-4);
}
```

### 8.2 Mica（云母）

采样桌面壁纸色调的微弱材质，用于标题栏背景：

```css
--fluent-mica-bg:      rgba(243, 242, 241, 0.7);
--fluent-mica-bg-dark: rgba(32, 31, 30, 0.7);

/* 使用示例 */
.title-bar {
  background: var(--fluent-mica-bg);
  backdrop-filter: blur(8px);
}
```

### 8.3 Smoke（烟雾遮罩）

用于 Modal / Flyout 背后的遮罩层：

```css
--fluent-smoke-default: rgba(0, 0, 0, 0.4);
```

---

## 9. 动效与缓动（新增）

### 9.1 缓动曲线

```css
--fluent-easing-accelerate: cubic-bezier(0.9, 0.1, 1.0, 0.2);   /* 元素离开 */
--fluent-easing-decelerate: cubic-bezier(0.1, 0.9, 0.2, 1.0);   /* 元素进入 */
--fluent-easing-standard:   cubic-bezier(0.8, 0.0, 0.2, 1.0);   /* 通用状态变化 */
```

### 9.2 时长

```css
--fluent-duration-faster:  83ms;   /* 微交互（ripple、hover 开始） */
--fluent-duration-fast:    100ms;  /* hover 进出 */
--fluent-duration-normal:  167ms;  /* 标准过渡 */
--fluent-duration-slow:    250ms;  /* 面板展开/关闭 */
--fluent-duration-slower:  333ms;  /* 页面过渡 */
```

### 9.3 过渡速查

| 场景 | 属性 | 时长 | 缓动 |
|------|------|------|------|
| 链接颜色 | color | 100ms | standard |
| 卡片悬停 | box-shadow | 167ms | standard |
| 按钮 hover | background | 100ms | decelerate |
| 面板展开 | max-height | 250ms | standard |
| 抽屉进出 | transform | 250ms | standard |
| 遮罩淡入 | opacity | 167ms | decelerate |

---

## 10. 布局规范

| 元素 | 值 | 说明 |
|------|------|------|
| 顶栏高度 (`--header-h`) | `64px` | Fluent / Ant Design 通用 |
| 侧栏宽度 (`--sidebar-w`) | `260px` | 桌面端导航 |
| 内容区最大宽度 | `1200px` | 标准内容区 |
| 宽版内容区 | `1600px` | 大屏仪表盘 / Landing |
| 侧边距 | `5%` | 流式响应（Fluent 风格） |
| 移动端内边距 | `16px` | ≤639px |

---

## 11. 响应式断点

Fluent 2 使用自有断点体系（取代 Ant Design 断点）：

| 断点 | 值 | 说明 |
|------|------|------|
| sm | 480px | 小手机横屏 |
| md | 640px | 平板竖屏（侧栏隐藏） |
| lg | 1024px | 平板横屏（紧凑侧栏） |
| xl | 1366px | 桌面完整布局 |
| xxl | 1920px | 大屏 |

**本项目使用**：
- `≤639px`：移动端 — 隐藏侧栏，显示 Chip 筛选 + 抽屉导航
- `640px–1023px`：平板 — 紧凑侧栏（220px）
- `≥1024px`：桌面 — 完整布局（260px 侧栏）

---

## 12. 组件规范

### 12.1 卡片 Card（Fluent 2 风格）

- 背景：`--bg-container`
- 边框：`1px solid --border`
- 圆角：`6px`（`--radius-md`）
- 内边距：`20px`
- 静止态：`box-shadow: var(--fluent-shadow-2)`（极淡阴影）
- 悬停态：`box-shadow: var(--fluent-shadow-4)`（上浮一层），边框色不变
- 过渡：`box-shadow var(--fluent-duration-normal) var(--fluent-easing-standard)`
- **移除**：旧版 `border-color` 变色 + `transform: scale(0.99)` 点击缩放

### 12.2 标签 Badge

- 内边距：`2px 10px`
- 圆角：`2px`（`--radius-xs`，Fluent 直角风格） 或 `12px`（胶囊形，按场景选择）
- 字号：`12px`
- 字重：`600`
- 背景：`--fluent-primary-tint-30`
- 文字色：`--color-primary`

### 12.3 按钮 Button

- 主按钮背景：`--color-primary`
- 主按钮文字：`#FFFFFF`
- 次要按钮背景：`transparent`
- 次要按钮边框：`1px solid --border`
- 圆角：`4px`（`--fluent-radius-medium`）
- 最小高度：`32px`
- hover：背景色上浮至 `shade-10` / `tint-30`
- 过渡：`background var(--fluent-duration-fast) var(--fluent-easing-decelerate)`

### 12.4 输入框 Input

- 边框：`1px solid --border`
- 圆角：`4px`（`--fluent-radius-medium`）
- Focus ring：`0 0 0 2px var(--fluent-primary-tint-20)`（外发光，不占布局）
- 内边距：`8px 12px`
- 颜色：`--text-primary`
- 占位符：`--text-tertiary`

### 12.5 表格 Table

- 表头背景：`--bg-elevated`
- 表头字重：`600`
- 单元格背景：`--bg-container`
- 单元格内边距：`10px 14px`
- 边框：`1px solid --border`
- 表头 sticky top: 0
- 行悬停：背景色变为 `--color-primary-bg`（`tint-30`）
- 圆角：`6px`（整表圆角）

### 12.6 代码 Code

- 背景：`--bg-elevated`
- 内边距：`2px 8px`
- 圆角：`4px`
- 字号：`13px`
- 字体：`--fluent-font-family-monospace`
- 颜色：`--color-primary`

### 12.7 代码块 CodeBlock

- 背景：`--bg-elevated`
- 边框：`1px solid --border`
- 圆角：`6px`（`--radius-md`）
- 内边距：`16px`
- 行高：`1.7`
- 字体：`--fluent-font-family-monospace`

### 12.8 导航项 NavItem（侧栏）

- 圆角：`4px`（`--radius-sm`）
- 内边距：`8px 12px`
- 激活态背景：`--fluent-primary-tint-30`（`#DEECF9`）
- 激活态文字：`--color-primary`
- 激活态字重：`500`
- hover 背景：`--bg-elevated`
- 移动端最小高度：`44px`（触控友好）

---

## 13. 渐变色

| 用途 | 值 |
|------|-----|
| 标题渐变 | `linear-gradient(135deg, #0078D4 0%, #2B88D8 100%)` |
| 强调渐变 | `linear-gradient(135deg, #0078D4 0%, #106EBE 100%)` |

> **注意**：旧版标题渐变包含 `#722ED1`（紫色），约 34 个文件在 HTML 中直接硬编码该值。这些文件在独立打开时不使用此规范；通过 `index.html` iframe 导航时才能继承 CSS 变量。

---

## 14. 主题架构

- **索引页（`index.html`）**：支持亮色/暗色双主题，通过 `data-theme` 属性切换
  - 优先级：`localStorage('wiki-theme')` → `prefers-color-scheme: dark` 系统偏好 → light
  - 暗色模式使用 Fluent 2 暗色中性色 + `#479EF5` 品牌色
  - 亮色模式背景使用 `#FAF9F8`（Fluent neutral-2）
- **报告页**：统一使用**亮色主题**，不定义暗色 CSS 变量。通过 `index.html` iframe 导航时继承 Token 值

---

## 15. 向后兼容矩阵

### 15.1 已迁移（旧名 = 新值）

| 旧 Token | 新值来源 | 视觉变化 |
|----------|---------|---------|
| `--color-primary` | Fluent `#0078D4` | 偏青蓝（原 `#1677FF` 偏紫蓝） |
| `--color-primary-hover` | Fluent shade-10 `#106EBE` | 更深 |
| `--color-primary-active` | Fluent shade-20 `#005A9E` | 更深 |
| `--color-primary-bg` | Fluent tint-30 `#DEECF9` | 几乎一致 |
| `--color-success` | Fluent `#107C10` | **显著变化**：亮绿→深绿 |
| `--color-warning` | Fluent `#FF8C00` | 琥珀→橙色 |
| `--color-error` | 保留 `#FF4D4F` | 不变 |
| `--bg` | Fluent neutral-2 `#FAF9F8` | 微调 |
| `--bg-elevated` | Fluent neutral-4 `#F3F2F1` | 微调 |
| `--border` | Fluent neutral-10 `#E1DFDD` | 微调 |
| `--text-primary/secondary/tertiary` | Fluent neutral-80/70/60 | 暗色文本对比度改善 |
| `--radius-sm/md/lg` | Fluent 4/6/8px | 整体更方正 |
| `--shadow-sm/md/lg` | Fluent elevation 2/4/8 | 更轻、更自然 |
| `--gradient-title` | 纯蓝渐变（移除紫色） | 34 个硬编码文件不受影响 |

### 15.2 未迁移（独立 Token 体系的文件）

以下 7 个文件使用独立的命名体系，不受本次迁移影响：

| 文件 | Token 体系 | 命名示例 |
|------|-----------|---------|
| `深国际综合改革方案/index.html` | 自定 + 部分标准 | `--primary: #1a3a5c`, `--accent: #c8102e` |
| `深国际综合改革方案/报告/*.html` (3 文件) | 自定 + 部分标准 | 同上 |
| `YqBoot系统说明书/系统说明书.html` | Google 风格 | `--primary: #1a73e8` |
| `YqBoot系统说明书/系统说明书-演示文稿.html` | Google 风格 | 同上 |
| `政府审批流解决方案/政府审批流解决方案.html` | 暗红金色 | `--primary: #8B0000`, `--accent: #C9A84C` |
| `中医馆内部管理系统/报告/*.html` (2 文件) | 多色功能色 | `--green/red/orange/purple` |
| `szihl-soe-reform-report.html` | 混合 | 标准 + `--accent: #c8102e` + 暗色模式 |

### 15.3 废弃 Token

| Token | 原因 |
|-------|------|
| `--color-info` | 定义但从未被 `var()` 引用 |

---

## 16. 图标规范

| 规则 | Do | Don't |
|------|----|----- |
| 图标来源 | SVG Icon 库（Heroicons / Lucide） | Emoji 作为 UI 图标 |
| 图标尺寸 | 固定 24×24 viewBox，`w-6 h-6` | 混合不同尺寸 |
| 品牌 Logo | 从 Simple Icons 获取官方 SVG | 猜测或使用错误路径 |
| 悬停反馈 | `transition-colors duration-200` | 瞬时状态变化 |
| 触控目标 | 最小 44×44px | 不可点击区域 |

---

## 参考资料

- [Fluent 2 Design System](https://fluent2.microsoft.design)
- [Fluent 2 Design Tokens](https://fluent2.microsoft.design/design-tokens)
- [Fluent 2 Typography](https://fluent2.microsoft.design/typography)
- [Fluent 2 Layout](https://fluent2.microsoft.design/layout)
- [Fluent 2 Shapes](https://fluent2.microsoft.design/shapes)
- [Windows 11 Design Principles](https://learn.microsoft.com/en-us/windows/apps/design/design-principles)
- [Windows 11 Typography](https://learn.microsoft.com/en-gb/windows/apps/design/signature-experiences/typography)
- [Fluent UI Web Components Design Tokens](https://learn.microsoft.com/en-gb/fluent-ui/web-components/design-system/design-tokens)