设计系统启动器
概览
这个技能提供了全面的指导，用于构建健壮、可扩展的设计系统，确保视觉一致性，提高开发速度，并创造卓越的用户体验。无论是从头开始还是演进现有系统，这个框架帮助团队有意图地设计和扩展。
何时使用这个技能：
- 从零开始创建新的设计系统
- 演进或重构现有设计系统
- 建立设计令牌标准
- 定义组件架构
- 创建设计文档
- 确保可访问性合规性（WCAG 2.1）
- 实施主题和暗色模式
捆绑资源：
references/component-examples.md- 完整的组件实现templates/design-tokens-template.json- W3C设计令牌格式templates/component-template.tsx- React组件模板checklists/design-system-checklist.md- 设计系统审核清单
设计系统哲学
什么是设计系统？
设计系统不仅仅是组件库——它是以下内容的集合：
- 设计令牌：基本设计决策（颜色、间距、排版）
- 组件：可重用的UI构建块
- 模式：常见的UX解决方案和组合
- 指南：规则、原则和最佳实践
- 文档：如何有效使用所有内容
核心原则
1. 一致性优于创造力
- 可预测的模式减少认知负荷
- 用户一次学习，到处应用
- 设计师和开发者使用相同的语言
2. 默认可访问性
- WCAG 2.1 Level AA合规性最低
- 内置键盘导航
- 从一开始就支持屏幕阅读器
3. 可扩展和可维护
- 设计令牌启用全局更改
- 组件组合减少重复
- 版本控制和弃用策略
4. 开发者友好
- 清晰的API契约
- 全面文档
- 易于集成和定制
设计令牌
设计令牌是定义您系统视觉语言的原子设计决策。
令牌类别
1. 颜色令牌
原始颜色（原始值）：
{
"color": {
"primitive": {
"blue": {
"50": "#eff6ff",
"100": "#dbeafe",
"200": "#bfdbfe",
"300": "#93c5fd",
"400": "#60a5fa",
"500": "#3b82f6",
"600": "#2563eb",
"700": "#1d4ed8",
"800": "#1e40af",
"900": "#1e3a8a",
"950": "#172554"
}
}
}
}
语义颜色（上下文含义）：
{
"color": {
"semantic": {
"brand": {
"primary": "{color.primitive.blue.600}",
"primary-hover": "{color.primitive.blue.700}",
"primary-active": "{color.primitive.blue.800}"
},
"text": {
"primary": "{color.primitive.gray.900}",
"secondary": "{color.primitive.gray.600}",
"tertiary": "{color.primitive.gray.500}",
"disabled": "{color.primitive.gray.400}",
"inverse": "{color.primitive.white}"
},
"background": {
"primary": "{color.primitive.white}",
"secondary": "{color.primitive.gray.50}",
"tertiary": "{color.primitive.gray.100}"
},
"feedback": {
"success": "{color.primitive.green.600}",
"warning": "{color.primitive.yellow.600}",
"error": "{color.primitive.red.600}",
"info": "{color.primitive.blue.600}"
}
}
}
}
可访问性：确保颜色对比度符合WCAG 2.1 Level AA：
- 正常文本：4.5:1最低
- 大号文本（18pt+或14pt+粗体）：3:1最低
- UI组件和图形：3:1最低
2. 排版令牌
{
"typography": {
"fontFamily": {
"sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
"serif": "'Georgia', 'Times New Roman', serif",
"mono": "'Fira Code', 'Courier New', monospace"
},
"fontSize": {
"xs": "0.75rem", // 12px
"sm": "0.875rem", // 14px
"base": "1rem", // 16px
"lg": "1.125rem", // 18px
"xl": "1.25rem", // 20px
"2xl": "1.5rem", // 24px
"3xl": "1.875rem", // 30px
"4xl": "2.25rem", // 36px
"5xl": "3rem" // 48px
},
"fontWeight": {
"normal": 400,
"medium": 500,
"semibold": 600,
"bold": 700
},
"lineHeight": {
"tight": 1.25,
"normal": 1.5,
"relaxed": 1.75,
"loose": 2
},
"letterSpacing": {
"tight": "-0.025em",
"normal": "0",
"wide": "0.025em"
}
}
}
3. 间距令牌
比例：使用一致的间距比例（通常为4px或8px基础）
{
"spacing": {
"0": "0",
"1": "0.25rem", // 4px
"2": "0.5rem", // 8px
"3": "0.75rem", // 12px
"4": "1rem", // 16px
"5": "1.25rem", // 20px
"6": "1.5rem", // 24px
"8": "2rem", // 32px
"10": "2.5rem", // 40px
"12": "3rem", // 48px
"16": "4rem", // 64px
"20": "5rem", // 80px
"24": "6rem" // 96px
}
}
组件特定间距：
{
"component": {
"button": {
"padding-x": "{spacing.4}",
"padding-y": "{spacing.2}",
"gap": "{spacing.2}"
},
"card": {
"padding": "{spacing.6}",
"gap": "{spacing.4}"
}
}
}
4. 边框半径令牌
{
"borderRadius": {
"none": "0",
"sm": "0.125rem", // 2px
"base": "0.25rem", // 4px
"md": "0.375rem", // 6px
"lg": "0.5rem", // 8px
"xl": "0.75rem", // 12px
"2xl": "1rem", // 16px
"full": "9999px"
}
}
5. 阴影令牌
{
"shadow": {
"xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
"sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)",
"base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
"md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
"lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
"xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
}
}
组件架构
原子设计方法论
原子 → 分子 → 有机体 → 模板 → 页面
原子（原始组件）
基本构建块，不能再进一步分解。
示例：
- 按钮
- 输入
- 标签
- 图标
- 徽章
- 头像
按钮组件：
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
loading?: boolean;
icon?: React.ReactNode;
children: React.ReactNode;
}
查看references/component-examples.md以获得完整的按钮实现，包括变体、大小和样式模式。
分子（简单组合）
一组原子，共同发挥作用。
示例：
- 搜索栏（输入+按钮）
- 表单字段（标签+输入+错误消息）
- 卡片（容器+标题+内容+操作）
表单字段分子：
interface FormFieldProps {
label: string;
name: string;
error?: string;
hint?: string;
required?: boolean;
children: React.ReactNode;
}
查看references/component-examples.md以获得表单字段、卡片（复合组件模式）、输入变体、模态框等组合示例。
有机体（复杂组合）
由分子和原子组成的复杂UI组件。
示例：
- 导航栏
- 产品卡片网格
- 用户个人资料部分
- 模态对话框
模板（页面布局）
定义内容放置的页面级结构。
示例：
- 仪表板布局（侧边栏+标题栏+主要内容）
- 营销页面布局（英雄+功能+页脚）
- 设置页面布局（标签+内容面板）
页面（特定实例）
实际页面，包含真实内容。
组件API设计
道具最佳实践
1. 可预测的道具名称
// ✅ 好：一致的命名
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />
// ❌ 坏：不一致
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />
2. 合理的默认值
// ✅ 好：提供默认值
interface ButtonProps {
variant?: 'primary' | 'secondary'; // 默认：primary
size?: 'sm' | 'md' | 'lg'; // 默认：md
}
// ❌ 坏：全部必需
interface ButtonProps {
variant: 'primary' | 'secondary';
size: 'sm' | 'md' | 'lg';
color: string;
padding: string;
}
3. 组合优于配置
// ✅ 好：可组合
<Card>
<Card.Header>
<Card.Title>Title</Card.Title>
</Card.Header>
<Card.Body>Content</Card.Body>
<Card.Footer>Actions</Card.Footer>
</Card>
// ❌ 坏：太多道具
<Card
title="Title"
content="Content"
footerContent="Actions"
hasHeader={true}
hasFooter={true}
/>
4. 多态组件 允许组件作为不同的HTML元素渲染：
<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>
查看references/component-examples.md以获得完整的多态组件TypeScript模式。
主题和暗色模式
主题结构
interface Theme {
colors: {
brand: {
primary: string;
secondary: string;
};
text: {
primary: string;
secondary: string;
};
background: {
primary: string;
secondary: string;
};
feedback: {
success: string;
warning: string;
error: string;
info: string;
};
};
typography: {
fontFamily: {
sans: string;
mono: string;
};
fontSize: Record<string, string>;
};
spacing: Record<string, string>;
borderRadius: Record<string, string>;
shadow: Record<string, string>;
}
暗色模式实现
方法1：CSS变量
:root {
--color-bg-primary: #ffffff;
--color-text-primary: #000000;
}
[data-theme="dark"] {
--color-bg-primary: #1a1a1a;
--color-text-primary: #ffffff;
}
方法2：Tailwind CSS暗色模式
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
Content
</div>
方法3：Styled Components ThemeProvider
const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };
<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
<App />
</ThemeProvider>
可访问性指南
WCAG 2.1 Level AA合规性
颜色对比度
- 正常文本（< 18pt）：4.5:1最低
- 大号文本（≥ 18pt或≥ 14pt粗体）：3:1最低
- UI组件：3:1最低
工具：使用对比度检查器，如WebAIM Contrast Checker
键盘导航
// ✅ 所有交互元素必须可通过键盘访问
<button
onClick={handleClick}
onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
Click me
</button>
// ✅ 焦点管理
<Modal>
<FocusTrap>
{/* 模态框内容 */}
</FocusTrap>
</Modal>
ARIA属性
基本ARIA模式：
aria-label：提供可访问名称aria-expanded：传达展开/折叠状态aria-controls：关联控件与内容aria-live：宣布动态内容变化
屏幕阅读器支持
- 使用语义HTML元素（
<button>,<nav>,<main>） - 避免为交互元素使用div/span汤
- 为所有控件提供有意义的标签
查看references/component-examples.md以获得包括跳过链接、焦点陷阱和ARIA模式在内的完整可访问性示例。
文档标准
组件文档模板
每个组件应记录：
- 目的：组件的作用
- 用法：导入语句和基本示例
- 变体：可用的视觉样式
- 道具：完整的道具表，包括类型、默认值、描述
- 可访问性：键盘支持、ARIA属性、屏幕阅读器行为
- 示例：常见用例及代码
使用Storybook、Docusaurus或类似工具进行交互式文档。
查看templates/component-template.tsx以获得标准组件结构。
设计系统工作流程
1. 设计阶段
- 审核现有模式：识别不一致性
- 定义设计令牌：颜色、排版、间距
- 创建组件清单：列出所有需要的组件
- 在Figma中设计：创建组件库
2. 开发阶段
- 设置工具：Storybook、TypeScript、测试
- 实施令牌：CSS变量或主题配置
- 首先构建原子：从原语开始
- 向上组合：构建分子、有机体
- 边做边记录：编写文档
3. 采用阶段
- 创建迁移指南：帮助团队采用
- 提供codemods：尽可能自动化迁移
- 举办研讨会：培训团队使用
- 收集反馈：根据实际使用进行迭代
4. 维护阶段
- 语义化版本控制：主要/次要/补丁版本
- 弃用策略：逐步淘汰旧组件
- 更改日志：记录所有更改
- 监控采用情况：跟踪产品中的使用情况
与代理集成
快速UI设计器
- 使用设计令牌创建一致的界面
- 引用组件库进行快速原型设计
- 自动应用可访问性指南
前端UI开发人员
- 根据设计系统模式实现组件
- 确保与现有设计语言保持一致
- 验证颜色对比度和可访问性
代码质量审查员
- 检查组件是否遵循设计系统标准
- 验证设计令牌的适当使用
- 确保满足可访问性要求
快速开始清单
创建新设计系统时：
- [ ] 定义设计原则和价值观
- [ ] 建立设计令牌结构（颜色、排版、间距）
- [ ] 创建原始色彩调色板（50-950规模）
- [ ] 定义语义色彩令牌（品牌、文本、背景、反馈）
- [ ] 设置排版规模和字体系列
- [ ] 建立间距比例（4px或8px基础）
- [ ] 设计原子组件（按钮、输入、标签等）
- [ ] 实施主题系统（浅色/暗色模式）
- [ ] 确保WCAG 2.1 Level AA合规性
- [ ] 设置文档（Storybook或类似）
- [ ] 为每个组件创建使用示例
- [ ] 建立版本控制和发布策略
- [ ] 为采用团队创建迁移指南
技能版本：1.0.0 最后更新：2025-10-31 维护者：AI代理中心团队