design-system-starter

设计系统起步套件

构建稳健、可扩展的设计系统，确保视觉一致性与卓越的用户体验。

---

快速开始

只需描述你的需求：

Create a design system for my React app with dark mode support

就这么简单。该技能提供令牌、组件和无障碍指南。

---

触发方式

触发方式	示例
创建设计系统	"为我的应用创建设计系统"
设计令牌	"为颜色和间距设置设计令牌"
组件架构	"使用原子化设计设计组件结构"
无障碍	"确保我的组件符合 WCAG 2.1"
深色模式	"实现支持深色模式的主题方案"

---

快速参考

任务	输出
设计令牌	颜色、字体、间距、阴影 JSON
组件结构	原子化设计层级（原子、分子、有机体）
主题化	CSS 变量或 ThemeProvider 设置
无障碍	符合 WCAG 2.1 AA 的模式
文档	包含 props、示例、无障碍说明的组件文档

---

捆绑资源

• references/component-examples.md - 完整的组件实现
• templates/design-tokens-template.json - W3C 设计令牌格式
• templates/component-template.tsx - React 组件模板
• checklists/design-system-checklist.md - 设计系统审查清单

---

设计系统理念

什么是设计系统？

设计系统不仅仅是一个组件库——它是以下内容的集合：

1. 设计令牌：基础设计决策（颜色、间距、字体）
2. 组件：可复用的 UI 构建块
3. 模式：常见的 UX 解决方案与组合
4. 指南：规则、原则和最佳实践
5. 文档：如何有效使用一切内容

核心原则

1. 一致性优先于创造性

• 可预测的模式降低认知负担
• 用户一次学习，处处适用
• 设计师和开发者使用同一种语言

2. 默认无障碍

• 最低符合 WCAG 2.1 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 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。

分子（简单组合）

协同工作的原子组合。

示例：

• SearchBar（输入框 + 按钮）
• FormField（标签 + 输入框 + 错误信息）
• Card（容器 + 标题 + 内容 + 操作）

FormField 分子：

interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}

FormField、Card（复合组件模式）、带变体的 Input、Modal 以及更多组合示例请参见 references/component-examples.md。

Organisms（复杂组合）

由 molecules 和 atoms 组成的复杂 UI 组件。

示例：

• 导航栏
• 产品卡片网格
• 用户资料区块
• 模态对话框

Templates（页面布局）

定义内容放置的页面级结构。

示例：

• 仪表盘布局（侧边栏 + 页头 + 主内容区）
• 营销页布局（Hero + 功能特性 + 页脚）
• 设置页布局（标签页 + 内容面板）

Pages（具体实例）

包含真实内容的具体页面。

---

组件 API 设计

Props 最佳实践

1. 可预测的 Prop 命名

// ✅ Good: Consistent naming
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ Bad: Inconsistent
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />

2. 合理的默认值

// ✅ Good: Provides defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary';  // Default: primary
  size?: 'sm' | 'md' | 'lg';          // Default: md
}

// ❌ Bad: Everything required
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  color: string;
  padding: string;
}

3. 组合优于配置

// ✅ Good: Composable
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// ❌ Bad: Too many props
<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>

完整的多态组件 TypeScript 模式见 references/component-examples.md。

---

主题与深色模式

主题结构

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 AA 级标准

颜色对比度

• 常规文本（< 18pt）：最低 4.5:1
• 大号文本（≥ 18pt 或 ≥ 14pt 粗体）：最低 3:1
• UI 组件：最低 3:1

工具：使用 WebAIM Contrast Checker 等对比度检查工具

键盘导航

// ✅ All interactive elements must be keyboard accessible
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ Focus management
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

ARIA 属性

必备的 ARIA 模式：

• aria-label：提供无障碍名称
• aria-expanded：传达展开/折叠状态
• aria-controls：将控件与内容关联
• aria-live：播报动态内容变化

屏幕阅读器支持

• 使用语义化 HTML 元素（<button>、<nav>、<main>）
• 交互元素避免滥用 div/span
• 为所有控件提供有意义的标签

完整的无障碍示例（包括 Skip Links、焦点陷阱和 ARIA 模式）见 references/component-examples.md。

---

文档规范

组件文档模板

每个组件都应记录：

• 用途：组件的作用
• 用法：导入语句和基本示例
• 变体：可用的视觉样式
• Props：完整的 prop 表格，包含类型、默认值、描述
• 无障碍：键盘支持、ARIA 属性、屏幕阅读器行为
• 示例：常见用例及代码

使用 Storybook、Docusaurus 或类似工具编写交互式文档。

标准组件结构见 templates/component-template.tsx。

---

设计系统工作流

1. 设计阶段

• 审查现有模式：识别不一致之处
• 定义设计令牌：颜色、字体排版、间距
• 创建组件清单：列出所有需要的组件
• 在 Figma 中设计：创建组件库

2. 开发阶段

• 搭建工具链：Storybook、TypeScript、测试
• 实现令牌：CSS 变量或主题配置
• 先构建 atoms：从基础元素开始
• 逐层向上组合：构建 molecules、organisms
• 边做边写文档：代码与文档同步编写

3. 推广阶段

• 创建迁移指南：帮助团队采用
• 提供 codemod：尽可能自动化迁移
• 开展工作坊：培训团队使用
• 收集反馈：根据实际使用情况迭代

4. 维护阶段

• 语义化版本：主版本/次版本/补丁版本发布
• 弃用策略：优雅地淘汰旧组件
• 变更日志：记录所有变更
• 监控采用情况：跟踪各产品中的使用情况

---

快速开始检查清单

创建新设计系统时：

• 定义设计原则和价值观
• 建立设计令牌结构（颜色、字体排版、间距）
• 创建原始色板（50-950 色阶）
• 定义语义化颜色令牌（品牌、文本、背景、反馈）
• 设置字体排版比例和字体系列
• 建立间距比例（以 4px 或 8px 为基准）
• 设计原子组件（Button、Input、Label 等）
• 实现主题系统（浅色/深色模式）
• 确保符合 WCAG 2.1 AA 级标准
• 搭建文档（Storybook 或类似工具）
• 为每个组件创建用法示例
• 建立版本管理和发布策略
• 为采用团队创建迁移指南