yueqian/wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9d2851dc56288a77cfacba4ae045142f4a7cf608
wiki/.claude/design-tokens.md
T
zdh 9d2851dc56
Deploy Wiki to Production / deploy (push) Has been cancelled
Details
fix: 修复返回链接路径 + 添加侧栏目录 + 布局规范 
- 修复 3 个错误 href（graphify-analysis、沈阳顺义×2）：../ → ../../
- 4 个沈阳顺义报告 + 到家业态分类：添加左侧 260px 粘性侧栏目录
- 所有 <h2> 添加 id 锚点，侧栏自动生成 TOC 导航
- design-tokens.md 新增 §17《页面布局与导航规范》
  - 强制要求：所有页面必须有返回链接 + 粘性顶栏
  - 报告页标准布局：顶栏 + 侧栏目录 + 主内容
  - 页面创建检查清单
- 变更日志更新至 2.1
2026-06-05 19:19:24 +08:00

23 KiB
Raw Blame History

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

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

0. 变更日志

日期 版本 变更
2026-06-05 2.1 全站 49/50 页面添加「← 返回知识库」导航链接；修复 3 个错误 href 路径；4 个沈阳顺义报告 + 到家业态分类添加侧栏目录；新增 §17 页面布局与导航规范
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 不可点击区域

17. 页面布局与导航规范

17.1 强制要求

所有页面（不含 index.html 首页本身）必须满足：

要求 说明
返回链接 顶部固定导航栏内包含 ← 返回知识库 链接，指向 index.html
顶部导航栏 粘性顶栏（position: sticky; top: 0; z-index: 100），高度 64px
统一路径规则 根级文件 ./index.html，一级子目录 ../index.html，二级子目录 ../../index.html

17.2 报告页布局标准

所有 {主题}/报告/*.html 报告页 必须使用以下布局：

┌──────────────────────────────────────────┐
│  Header Bar (sticky, 64px)               │
│  ← 返回知识库    报告标题                  │
├────────┬─────────────────────────────────┤
│ Sidebar│  Main Content                   │
│ 260px  │  (flex: 1, max-width: 1200px)   │
│        │                                 │
│ 目录   │  ## 章节                         │
│ · 1.   │  ...                            │
│ · 2.   │  ## 章节                         │
│ · 3.   │  ...                            │
│ (sticky│                                 │
│  TOC)  │                                 │
├────────┴─────────────────────────────────┤

核心 CSS 结构：

.layout { display: flex; max-width: 1200px; margin: 0 auto; }
.sidebar { width: 260px; flex-shrink: 0; position: sticky; top: 64px;
           height: calc(100vh - 64px); overflow-y: auto;
           background: var(--bg-container); border-right: 1px solid var(--border); }
.sidebar a { /* 目录链接，需包含 .active 激活态样式 */ }
.main-content { flex: 1; padding: 32px 40px 64px; min-width: 0; }

侧栏目录（TOC）规则：

  • 自动提取页面内所有 <h2> 标题作为目录项
  • 每个 <h2> 必须有 id 属性（作为锚点）
  • 目录链接 href 指向对应 #id
  • 激活项添加 .active 类（配合 IntersectionObserver 或手动标记）
  • 移动端（≤768px）隐藏侧栏，全宽内容

17.3 非报告页（特殊布局）

以下页面类型可使用简化布局，但必须保留顶部返回栏：

页面类型 示例 最低要求
独立子站首页 mcp-services-guide/index.html 顶栏 + 返回链接
交互式演示 交互式演示/tetrahedron-interactive.html 页面顶部返回链接
演示文稿 YqBoot系统说明书/系统说明书-演示文稿.html 固定定位返回链接
个人简历 张德海_简历.html 页面顶部返回链接
系列索引页 深国际综合改革方案/index.html 顶栏 + 返回链接

17.4 页面分类与布局要求

类别 特征 布局要求 文件数
标准报告页 使用 var(--color-primary) 等 Token 顶栏 + 侧栏目录 + 主内容 ~33
无侧栏报告页 有 Token 但缺侧栏 补齐侧栏目录 ~10（逐步修复）
自定义样式页 独立色板/布局 至少顶栏 + 返回链接 ~4
特殊布局页 Canvas/Reveal.js/简历 至少返回链接 ~3

17.5 页面创建检查清单

新建报告页时必须逐项检查：

  • 顶部固定导航栏（64px, sticky top:0）
  • ← 返回知识库 链接，href 按目录深度计算
  • 左侧 260px 侧栏，含按 <h2> 标题生成的目录
  • 所有 <h2> 有 id 锚点
  • 使用 CSS 变量（var(--color-primary) 等）而非硬编码颜色
  • 移动端（≤768px）隐藏侧栏，全宽布局
  • font-family 引用 var(--fluent-font-family-text)
  • 内容区 max-width: 1200px 居中

参考资料

Reference in New Issue View Git Blame Copy Permalink