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 完整中性阶梯

--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 系列，新增）

--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 字体族

/* 正文（优先 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（亚克力）

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

--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（云母）

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

--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 背后的遮罩层：

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

---

9. 动效与缓动（新增）

9.1 缓动曲线

--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 时长

--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
• Fluent 2 Design Tokens
• Fluent 2 Typography
• Fluent 2 Layout
• Fluent 2 Shapes
• Windows 11 Design Principles
• Windows 11 Typography
• Fluent UI Web Components Design Tokens