@umacloud/knowledge 1.0.1

package/design/04-antipatterns/design-antipatterns.md

@@ -0,0 +1,378 @@
+---
+id: design-antipatterns
+title: Design Antipatterns
+domain: design
+category: 04-antipatterns
+difficulty: intermediate
+tags: [antipatterns, chaos, design, excess, look, neglect, overload, template]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Design Antipatterns
+
+## 概述
+
+设计反模式（Design Antipatterns）是在产品设计过程中反复出现的、看似合理但实际上会损害用户体验和产品质量的做法。识别并规避这些反模式能够帮助团队避免常见陷阱，提升设计决策质量。本文档分为六大类别：信息过载、导航混乱、不一致性、忽略无障碍、过度动效和 AI 模板感。
+
+---
+
+## 一、信息过载（Information Overload）
+
+### 1.1 厨房水槽式界面
+
+**表现**：单个页面/屏幕试图展示所有功能和信息，没有层级优先。
+
+**为什么看似合理**：希望用户一眼看到所有功能，减少点击。
+
+**实际危害**：
+- 用户认知负担过重，决策瘫痪
+- 关键信息被淹没，核心任务完成率下降
+- 页面加载慢，首屏渲染时间长
+
+**修正方案**：
+- 使用渐进式披露（Progressive Disclosure），分层呈现信息
+- 按使用频率排列：高频 > 中频 > 低频
+- 遵循"5-7 规则"：单个视觉区域内选项不超过 7 个
+- 使用 Tab / Accordion / 分步向导拆分内容
+
+### 1.2 数据表格地狱
+
+**表现**：将所有字段塞进一个宽表格，用户需要横向滚动。
+
+**实际危害**：
+- 移动端完全不可用
+- 用户无法聚焦关键数据列
+- 数据比较困难
+
+**修正方案**：
+- 默认显示 5-7 个核心列，其余通过列选择器配置
+- 移动端将行转为卡片布局
+- 提供筛选/排序/搜索替代全量展示
+- 关键指标通过图表可视化
+
+### 1.3 通知轰炸
+
+**表现**：所有系统事件都以弹窗/Toast/红点形式通知用户。
+
+**实际危害**：
+- 用户产生"通知疲劳"，开始忽略所有提示
+- 真正重要的通知被淹没
+- 干扰用户当前任务流
+
+**修正方案**：
+- 通知分级：Critical（弹窗）、Important（Toast）、Info（通知中心）
+- 允许用户自定义通知偏好
+- 合并同类通知（"你有 3 条新消息"而非 3 个独立弹窗）
+- 非紧急通知进入通知中心而非打断用户
+
+---
+
+## 二、导航混乱（Navigation Chaos）
+
+### 2.1 深层嵌套导航
+
+**表现**：用户需要 5 次以上点击才能到达目标页面，导航层级超过 3 层。
+
+**实际危害**：
+- 用户迷失位置感，不知道自己在哪里
+- 返回路径不清晰，无法快速切换
+- SEO 爬虫难以到达深层页面
+
+**修正方案**：
+- 导航层级控制在 3 层以内
+- 提供面包屑导航（Breadcrumb）
+- 关键页面支持快捷入口或搜索直达
+- 扁平化信息架构，合并相似层级
+
+### 2.2 隐藏的汉堡菜单综合症
+
+**表现**：桌面端也把主导航藏在汉堡菜单里，页面看起来"干净"。
+
+**实际危害**：
+- 导航可发现性降低 50%+
+- 用户必须多一次点击才能看到选项
+- 新用户不知道系统有哪些功能
+
+**修正方案**：
+- 桌面端使用可见的顶部导航或侧边栏
+- 汉堡菜单仅用于移动端空间受限场景
+- 即使使用汉堡菜单，也保留 2-3 个高频入口可见
+
+### 2.3 不一致的返回逻辑
+
+**表现**：有时返回到列表页，有时返回到首页，有时返回到上一个操作步骤。
+
+**实际危害**：
+- 用户对"返回"按钮行为无法预期
+- 操作中断后无法恢复
+- 移动端尤为致命，因为用户重度依赖返回手势
+
+**修正方案**：
+- 明确定义返回逻辑：返回 = 浏览历史中的上一页
+- 分步流程中"返回"回到上一步，"关闭"回到起始页
+- 提供面包屑作为辅助导航手段
+- 测试用户的心理模型是否与实际行为一致
+
+---
+
+## 三、不一致性（Inconsistency）
+
+### 3.1 按钮风格不统一
+
+**表现**：同一个产品中按钮有 5 种以上样式，圆角、大小、颜色各不相同。
+
+**实际危害**：
+- 用户无法通过视觉快速识别可操作元素
+- 品牌感破碎，产品显得业余
+- 维护成本高，每个页面都是一次性设计
+
+**修正方案**：
+- 定义按钮系统：Primary / Secondary / Tertiary / Ghost / Danger
+- 每种按钮有 3 个尺寸：Small / Medium / Large
+- 所有按钮使用统一圆角和字重
+- 建立组件库并强制使用
+
+### 3.2 间距随机
+
+**表现**：组件之间的间距凭感觉设定，7px、13px、22px 等非标准值随意出现。
+
+**实际危害**：
+- 页面视觉节奏混乱
+- 开发还原困难，每个间距都要量
+- 修改时牵一发动全身
+
+**修正方案**：
+- 使用 4px/8px 基准网格（spacing scale: 4/8/12/16/24/32/48/64）
+- Design Token 中固定间距值
+- Auto Layout 强制约束
+- Code Review 中检查间距是否引用 Token
+
+### 3.3 交互模式不统一
+
+**表现**：删除操作有时需二次确认，有时直接执行；有时用 Modal，有时用 Toast。
+
+**实际危害**：
+- 用户无法建立操作心理模型
+- 误操作风险高
+- 新功能设计无章可循
+
+**修正方案**：
+- 建立交互模式库：确认 / 通知 / 错误 / 引导 / 加载
+- 定义每种模式的触发条件和展现形式
+- 破坏性操作统一使用二次确认
+- 成功反馈统一使用 Toast（非 Modal）
+
+---
+
+## 四、忽略无障碍（Accessibility Neglect）
+
+### 4.1 颜色是唯一信息通道
+
+**表现**：用红色/绿色区分状态，无其他视觉提示。
+
+**实际危害**：
+- 色盲用户（男性约 8%）完全无法获取信息
+- 低对比度屏幕上信息丢失
+- 打印时状态信息消失
+
+**修正方案**：
+- 颜色 + 图标 + 文字标签三重编码
+- 使用形状差异辅助（实心圆 vs 空心圆）
+- 确保仅黑白模式下信息仍可理解
+- 使用色盲模拟器（如 Stark 插件）验证
+
+### 4.2 对比度不足
+
+**表现**：浅灰色文字在白色背景上，设计师觉得"高级"。
+
+**实际危害**：
+- WCAG AA 不达标，可能面临法律风险
+- 阳光下/低亮度下不可读
+- 老年用户群体流失
+
+**修正方案**：
+- 正文对比度 >= 4.5:1，大字 >= 3:1
+- 使用 WebAIM 对比度检查器验证
+- 最浅的正文灰色不低于 #595959（在白底上）
+- 占位文本颜色也需可读
+
+### 4.3 仅鼠标可用
+
+**表现**：所有交互仅通过鼠标 hover 和 click 触发，无键盘支持。
+
+**实际危害**：
+- 键盘用户完全无法操作
+- 屏幕阅读器用户无法使用
+- 触摸设备上 hover 效果不可达
+
+**修正方案**：
+- 所有交互元素可 Tab 聚焦
+- 焦点样式清晰可见（不要 `outline: none` 无替代）
+- 下拉菜单支持方向键导航
+- Modal 支持 Esc 关闭和焦点陷阱
+
+---
+
+## 五、过度动效（Motion Excess）
+
+### 5.1 入场动画阻塞
+
+**表现**：页面加载时所有元素依次飞入，用户等待 2-3 秒才能操作。
+
+**实际危害**：
+- 首次访问体验差，用户可能在动画完成前离开
+- 重复访问时动画变成干扰
+- 移动端性能受损，低端设备卡顿
+
+**修正方案**：
+- 首屏内容立即可见，动画仅作为增强
+- 入场动画总时长 < 600ms
+- 仅对首次进入的用户播放完整动画
+- 尊重 `prefers-reduced-motion` 媒体查询
+
+### 5.2 不必要的加载动画
+
+**表现**：数据已就绪但仍展示 skeleton/spinner 以"显得在加载"。
+
+**实际危害**：
+- 人为增加等待时间
+- 用户信任度下降
+- 违背"系统应尽快响应"原则
+
+**修正方案**：
+- 数据 < 200ms 返回时不显示 Loading
+- 200-1000ms 显示简单 spinner
+- > 1000ms 使用 skeleton screen
+- 永远不人为延迟已就绪的内容
+
+### 5.3 视差滚动滥用
+
+**表现**：每个页面都有多层视差效果、滚动触发动画和固定背景。
+
+**实际危害**：
+- 晕动症用户不适（前庭功能障碍）
+- 移动端帧率暴跌
+- 内容可读性下降，用户注意力分散
+
+**修正方案**：
+- 视差效果仅用于营销着陆页，功能页不使用
+- 滚动动画不影响内容可读性
+- 提供 `prefers-reduced-motion` 替代版本
+- 动画性能测试在低端设备上通过
+
+---
+
+## 六、AI 模板感（AI Template Look）
+
+### 6.1 紫色渐变综合症
+
+**表现**：深紫→蓝紫渐变背景、发光边框、半透明毛玻璃卡片堆砌。
+
+**为什么会出现**：AI 工具生成的默认主题偏好紫色渐变和科技感。
+
+**实际危害**：
+- 产品与数千个 AI 生成的网站看起来一模一样
+- 无品牌辨识度
+- 用户直觉判断为"不可信"或"低质量"
+
+**修正方案**：
+- 使用品牌自有配色方案
+- 如无品牌色，选择非紫色系主色（蓝、绿、橙、红）
+- 避免大面积渐变，使用纯色 + 微妙纹理
+- 视觉差异化通过排版和布局而非颜色花样
+
+### 6.2 Emoji 替代图标
+
+**表现**：用 emoji（🚀🔥💡✨）替代专业设计的图标系统。
+
+**实际危害**：
+- 跨平台 emoji 渲染不一致
+- 无法控制大小、颜色、风格
+- 产品显得临时和不专业
+
+**修正方案**：
+- 使用统一的图标库（Lucide / Phosphor / Heroicons）
+- 图标与品牌调性匹配（线性 vs 填充）
+- 如需装饰元素，使用定制插画而非 emoji
+- 图标可通过 CSS 控制颜色和尺寸
+
+### 6.3 默认字体堆砌
+
+**表现**：仅使用 system-ui / Arial / sans-serif，全站无字体层次。
+
+**实际危害**：
+- 视觉单调，缺乏品牌感
+- 标题与正文无明确区分
+- 与操作系统默认界面混淆
+
+**修正方案**：
+- 至少引入一个品牌字体用于标题
+- 中文推荐：思源黑体 / 苍耳字体 / 阿里普惠体
+- 英文推荐：Inter / Plus Jakarta Sans / DM Sans
+- 定义完整的排版系统：标题字体 + 正文字体 + 等宽字体
+
+### 6.4 千篇一律的 Hero 区域
+
+**表现**：大标题 + 副标题 + CTA 按钮 + 抽象 3D 图形，所有页面 Hero 几乎相同。
+
+**实际危害**：
+- 无法传达具体价值主张
+- 用户略过 Hero 直接滚动到内容区
+- 浪费最有价值的首屏空间
+
+**修正方案**：
+- Hero 区展示真实产品截图或演示
+- 用具体数据和案例替代抽象口号
+- 提供可操作的入口（搜索框、快速开始）
+- 不同页面的 Hero 针对该页面内容定制
+
+### 6.5 功能展示千篇一律
+
+**表现**：三列卡片布局展示功能，每个卡片一个图标 + 标题 + 一句话描述。
+
+**实际危害**：
+- 用户无法理解功能的实际价值
+- 所有 SaaS 网站看起来一样
+- 缺乏信服力和差异化
+
+**修正方案**：
+- 用真实截图展示功能
+- 提供前后对比（使用前 vs 使用后）
+- 嵌入可交互的 Demo
+- 用客户证言和数据佐证
+
+---
+
+## 反模式检测矩阵
+
+| 反模式类别 | 检测信号 | 严重等级 |
+|-----------|---------|---------|
+| 信息过载 | 首屏 > 15 个可操作元素 | HIGH |
+| 信息过载 | 表格 > 10 列无列选择器 | MEDIUM |
+| 导航混乱 | 到达目标 > 5 次点击 | HIGH |
+| 导航混乱 | 无面包屑且层级 > 2 | MEDIUM |
+| 不一致性 | 按钮样式 > 5 种 | HIGH |
+| 不一致性 | 非标准间距值出现 > 3 处 | MEDIUM |
+| 无障碍 | 对比度 < 4.5:1 | HIGH |
+| 无障碍 | 交互元素无焦点样式 | HIGH |
+| 过度动效 | 入场动画 > 600ms | MEDIUM |
+| 过度动效 | 无 reduced-motion 支持 | MEDIUM |
+| AI 模板感 | 紫色渐变背景 | HIGH |
+| AI 模板感 | 使用 emoji 作为功能图标 | MEDIUM |
+
+---
+
+## Agent Checklist
+
+以下为 AI Agent 在执行设计评审时用于检测反模式的要点：
+
+- [ ] 检查页面信息密度，首屏可操作元素是否 <= 15 个
+- [ ] 验证导航层级 <= 3 层，关键页面可 3 步内到达
+- [ ] 确认视觉元素（按钮/间距/圆角）使用统一的 Design Token
+- [ ] 使用对比度工具验证文本可读性（WCAG AA）
+- [ ] 确认信息传递不仅依赖颜色，有图标/文字辅助
+- [ ] 检查动效时长和性能（仅 transform/opacity）
+- [ ] 扫描 AI 模板感特征：紫色渐变、emoji 图标、默认字体
+- [ ] 确认 Hero 区域有真实内容而非泛泛口号
+- [ ] 验证所有交互模式（确认/通知/错误）在全站一致
+- [ ] 确认 `prefers-reduced-motion` 媒体查询已实现

package/design/05-cases/case-design-system-adoption.md

@@ -0,0 +1,328 @@
+---
+id: case-design-system-adoption
+title: 案例：设计系统从零到全团队采用
+domain: design
+category: 05-cases
+difficulty: intermediate
+tags: [adoption, agent, case, checklist, design, system, 关键成功因素, 概述]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 案例：设计系统从零到全团队采用
+
+## 概述
+
+本案例记录一家中型 SaaS 公司（约 200 人研发团队，8 个产品线）从零开始搭建设计系统，到全团队采用的完整过程。项目历时 9 个月，最终实现组件复用率从 15% 提升至 82%，设计到开发交付周期缩短 40%，UI 一致性评分从 45 分提升至 91 分。本案例涵盖前期调研、核心搭建、推广策略、度量指标和踩过的坑。
+
+---
+
+## 背景
+
+### 组织现状
+
+- **团队规模**：6 名设计师、40 名前端工程师、8 个产品线
+- **技术栈**：React + TypeScript，部分产品线使用 Vue
+- **设计工具**：Figma（刚从 Sketch 迁移完成）
+- **现有状态**：无统一组件库，各产品线自建 UI 组件，风格差异大
+
+### 核心痛点
+
+1. **视觉不一致**：同一品牌下 8 个产品看起来像 8 家公司
+2. **重复造轮子**：每个产品线都有自己的 Button、Modal、Form 组件
+3. **交付效率低**：设计师每次都从零画组件，开发每次都从零写组件
+4. **维护成本高**：修改品牌色需要在 8 个代码库中分别修改
+5. **设计走查周期长**：每次走查发现大量一致性问题
+
+### 关键决策
+
+立项前团队面临的核心选择：
+
+| 选项 | 优点 | 缺点 | 决策 |
+|------|------|------|------|
+| 采用开源 UI 库（Ant Design / MUI） | 快速启动 | 品牌感弱，定制成本高 | 否决 |
+| 从最大产品线提取组件 | 有现成代码 | 其他产品线不认同 | 否决 |
+| 从零搭建品牌设计系统 | 高度定制，全团队认同 | 初期投入大 | 采纳 |
+
+---
+
+## 第一阶段：审计与规划（第 1-2 月）
+
+### 1.1 组件审计
+
+对 8 个产品线进行组件盘点：
+
+```
+审计结果摘要：
+- Button 变体：23 种（应统一为 5 种）
+- 颜色值：147 个（应统一为 36 个）
+- 字号：28 种（应统一为 8 种）
+- 间距值：41 种（应统一为 10 种）
+- 圆角值：12 种（应统一为 5 种）
+- 模态框实现：6 种不同的 Modal 组件
+```
+
+### 1.2 利益相关方访谈
+
+访谈了 30 人（设计师、前端、PM、技术负责人），关键发现：
+
+- 设计师最关心：减少重复绘制，提升设计一致性
+- 前端最关心：API 设计合理，不破坏现有代码
+- PM 最关心：不影响当前迭代进度
+- 技术负责人最关心：维护成本和升级策略
+
+### 1.3 路线图
+
+```
+M1-M2: 审计 + 规划 + 团队组建
+M3-M4: Design Token + 基础组件（Tier 1）
+M5-M6: 复合组件 + Figma 库 + 代码库发布
+M7-M8: 试点产品线接入 + 文档完善
+M9:    全团队推广 + 度量体系建立
+```
+
+### 1.4 团队组建
+
+成立 3 人核心小组（不是全职，各投入 50% 时间）：
+
+- 1 名设计师：负责 Figma 组件库和设计规范
+- 1 名前端工程师：负责 React 组件库开发
+- 1 名前端工程师：负责构建工具、文档站和 Token 管道
+
+---
+
+## 第二阶段：基础搭建（第 3-4 月）
+
+### 2.1 Design Token 体系
+
+首先建立 Token 而非直接画组件：
+
+```
+Token 层级：
+├── Global Tokens（全局原始值）
+│   ├── color.blue.500: #2196F3
+│   ├── spacing.16: 16px
+│   └── font.size.16: 16px
+├── Alias Tokens（语义别名）
+│   ├── color.primary: {color.blue.500}
+│   ├── spacing.component-gap: {spacing.16}
+│   └── font.size.body: {font.size.16}
+└── Component Tokens（组件级）
+    ├── button.primary.bg: {color.primary}
+    ├── button.padding-x: {spacing.16}
+    └── button.font-size: {font.size.body}
+```
+
+工具链选择：
+
+- **设计端**：Figma Tokens Studio（同步 Token 到 JSON）
+- **转换层**：Style Dictionary（JSON -> CSS Variables / TS Constants）
+- **代码端**：CSS Custom Properties + Tailwind Config
+- **版本管理**：Token JSON 文件纳入 Git，变更走 PR
+
+### 2.2 基础组件（Tier 1）
+
+首批 12 个原子组件：
+
+| 组件 | 变体 | 状态 | 无障碍 |
+|------|------|------|--------|
+| Button | Primary/Secondary/Tertiary/Ghost/Danger | Default/Hover/Active/Focus/Disabled/Loading | aria-label, role |
+| Input | Text/Password/Search/Number | Default/Focus/Error/Disabled | aria-invalid, aria-describedby |
+| Checkbox | Default/Indeterminate | Unchecked/Checked/Disabled | aria-checked |
+| Radio | Default | Unselected/Selected/Disabled | role="radiogroup" |
+| Switch | Default | Off/On/Disabled | role="switch" |
+| Select | Single/Multi | Open/Closed/Disabled | aria-expanded |
+| Badge | Dot/Count/Status | -- | aria-label |
+| Avatar | Image/Initial/Icon | Default/Fallback | alt text |
+| Icon | 200+ 图标 | -- | aria-hidden |
+| Tooltip | Top/Bottom/Left/Right | -- | role="tooltip" |
+| Tag | Default/Closable | -- | aria-label |
+| Divider | Horizontal/Vertical | -- | role="separator" |
+
+### 2.3 技术架构
+
+```
+@company/design-tokens     → Token JSON + CSS Variables
+@company/ui-react          → React 组件库
+@company/ui-icons          → SVG 图标库
+@company/ui-docs           → Storybook 文档站
+```
+
+关键技术决策：
+
+- **构建工具**：Rollup（Tree-shaking 友好）
+- **样式方案**：CSS Modules + CSS Variables（非 CSS-in-JS，减少运行时开销）
+- **测试**：Vitest + Testing Library + Chromatic（视觉回归）
+- **发布**：Changesets（自动版本管理 + Changelog）
+
+---
+
+## 第三阶段：扩展与文档（第 5-6 月）
+
+### 3.1 复合组件（Tier 2-3）
+
+在基础组件上构建：
+
+- **Tier 2**：FormField、Card、ListItem、MenuItem、Breadcrumb、Pagination、Tab
+- **Tier 3**：Modal、Drawer、DataTable、Form、Dropdown、DatePicker、Upload
+
+### 3.2 Figma 组件库
+
+与代码组件 1:1 对应：
+
+- 每个 Figma 组件使用 Variants 覆盖所有变体和状态
+- 组件属性面板（Component Properties）暴露关键配置
+- Auto Layout 约束间距，不允许手动拖拽
+- 发布为 Figma Team Library，所有设计师可引用
+
+### 3.3 文档站
+
+使用 Storybook 搭建文档站，每个组件包含：
+
+1. **概述**：组件用途、使用场景
+2. **Playground**：可交互的参数调节面板
+3. **变体展示**：所有变体的并排对比
+4. **Props API**：完整的参数文档
+5. **设计指南**：Do / Don't 示例
+6. **无障碍说明**：ARIA 属性和键盘操作
+7. **Figma 链接**：跳转到对应的 Figma 组件
+
+---
+
+## 第四阶段：试点接入（第 7-8 月）
+
+### 4.1 试点选择
+
+选择 2 个产品线作为试点：
+
+- **产品线 A**：最大的产品线，影响力最大
+- **产品线 C**：刚启动新版本，历史包袱最少
+
+### 4.2 接入策略
+
+采用渐进式替换而非一次性迁移：
+
+```
+阶段 1: 新页面强制使用设计系统组件
+阶段 2: 存量页面在功能迭代时逐步替换
+阶段 3: 专项清理遗留自建组件
+```
+
+### 4.3 接入过程中的问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|---------|
+| 组件 API 不满足需求 | 首批设计未覆盖所有场景 | 收集需求 -> 评审 -> 迭代发布 |
+| 升级破坏现有样式 | CSS 变量名冲突 | 添加命名空间前缀 |
+| 设计师不愿切换 | 习惯了自己的文件 | 手把手培训 + 模板页面 |
+| 开发觉得限制太多 | 组件定制能力不足 | 增加 `className` 和 `style` 透传 |
+| 产品线特殊需求 | 通用组件不能满足 | 区分通用组件和业务组件边界 |
+
+### 4.4 接入度量
+
+试点 2 个月后的数据：
+
+```
+产品线 A：
+- 组件复用率：18% -> 65%
+- 新页面开发速度：提升 30%
+- 设计走查问题数：减少 55%
+
+产品线 C：
+- 组件复用率：0% -> 78%（新项目）
+- 设计到开发交付时间：缩短 45%
+- UI 一致性评分：92 分
+```
+
+---
+
+## 第五阶段：全团队推广（第 9 月）
+
+### 5.1 推广策略
+
+不是发邮件通知，而是多管齐下：
+
+1. **内部发布会**：Demo Day 展示设计系统能力和试点成果
+2. **培训工作坊**：设计师 2 小时 + 前端 2 小时，分 4 批完成
+3. **迁移指南**：编写从自建组件到设计系统的迁移文档
+4. **Codemod 工具**：自动化替换部分常见组件（Button、Input）
+5. **度量看板**：实时显示各产品线的采用率
+6. **冠军制度**：每个产品线指定 1 名设计系统冠军
+
+### 5.2 治理机制
+
+- **贡献流程**：任何人可提交新组件 RFC，核心小组评审
+- **发布节奏**：每两周一次 Minor Release，紧急修复随时 Patch
+- **破坏性变更**：需提前一个版本标记 Deprecated，下一版本移除
+- **设计审计**：每月对各产品线抽查一致性评分
+
+### 5.3 最终成果
+
+| 指标 | 项目前 | 项目后 | 提升 |
+|------|--------|--------|------|
+| 组件复用率 | 15% | 82% | +67% |
+| 新页面开发周期 | 5 天 | 3 天 | -40% |
+| 设计走查问题数 | 每页 15 个 | 每页 3 个 | -80% |
+| UI 一致性评分 | 45/100 | 91/100 | +46 |
+| 设计师绘制时间 | 每页 8 小时 | 每页 3 小时 | -63% |
+| 品牌色修改耗时 | 2 周（8 个库） | 30 分钟（1 个 Token） | -99% |
+
+---
+
+## 踩过的坑
+
+### 坑 1：过早追求完美
+
+初期花了太多时间打磨视觉细节，应该先发布最小可用版本让团队用起来。
+
+**教训**：先有用，再好看。V1 覆盖 80% 场景即可发布。
+
+### 坑 2：忽略开发者体验
+
+Figma 组件做得很好，但 React 组件 API 设计不友好（Props 命名不直觉、类型定义不完整）。
+
+**教训**：API 设计与视觉设计同等重要，前端工程师必须深度参与。
+
+### 坑 3：没有度量就没有话语权
+
+前 4 个月没有建立度量指标，向管理层汇报只能说"感觉变好了"。
+
+**教训**：从第一天就建立可量化指标：复用率、一致性评分、开发速度。
+
+### 坑 4：低估了推广难度
+
+以为"做好了自然会有人用"，实际上需要持续推广和培训。
+
+**教训**：推广投入不低于开发投入。冠军制度和度量看板是关键。
+
+### 坑 5：通用组件 vs 业务组件边界不清
+
+试图把所有组件都放进设计系统，包括高度业务化的组件。
+
+**教训**：设计系统只包含通用组件（2+ 个产品线使用），业务组件由各产品线自行维护。
+
+---
+
+## 关键成功因素
+
+1. **管理层支持**：CTO 授权核心小组 50% 时间投入
+2. **渐进式策略**：不要求一步到位，允许渐进替换
+3. **双端同步**：Figma 组件与代码组件 1:1 对应
+4. **度量驱动**：用数据说话，每月发布采用率报告
+5. **社区运营**：内部 Slack 频道、月度分享会、贡献者表彰
+
+---
+
+## Agent Checklist
+
+以下为 AI Agent 在辅助设计系统搭建时的检查要点：
+
+- [ ] 先进行组件审计，量化现状（颜色/字号/间距/组件变体数量）
+- [ ] 建立 Design Token 体系后再开始画组件
+- [ ] Token 使用三层结构：Global -> Alias -> Component
+- [ ] 基础组件覆盖完整状态（Default/Hover/Active/Focus/Disabled/Loading/Error）
+- [ ] 每个组件包含无障碍支持（ARIA 属性、键盘导航）
+- [ ] Figma 组件与代码组件 1:1 对应
+- [ ] 文档包含 Playground、Props API、Do/Don't 示例
+- [ ] 采用渐进式接入策略（新页面强制 -> 存量逐步替换）
+- [ ] 建立度量指标：复用率、一致性评分、开发速度
+- [ ] 区分通用组件和业务组件的边界