name: design-system-starter description: 使用设计令牌、组件架构、可访问性指南和文档模板创建和发展设计系统。确保跨产品的一致、可扩展和可访问的UI。 license: MIT metadata: version: 1.0.0 tags: [设计系统, ui, 组件, 设计令牌, 可访问性, 前端]

设计系统入门

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

快速开始

只需描述您的需求：

为我的React应用创建一个支持深色模式的设计系统

就这样。该技能提供令牌、组件和可访问性指南。

触发器

触发器	示例
创建设计系统	“为我的应用创建一个设计系统”
设计令牌	“为颜色和间距设置设计令牌”
组件架构	“使用原子设计设计组件结构”
可访问性	“确保我的组件符合WCAG 2.1标准”
深色模式	“实现支持深色模式的主题化”

快速参考

任务	输出
设计令牌	颜色、排版、间距、阴影的JSON
组件结构	原子设计层次结构（原子、分子、有机体）
主题化	CSS变量或ThemeProvider设置
可访问性	符合WCAG 2.1 AA标准的模式
文档	包含属性、示例、可访问性注释的组件文档

捆绑资源

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获取FormField、Card（复合组件模式）、带变体的Input、Modal等更多组合示例。

有机体（复杂组合）

由分子和原子构成的复杂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>标题</Card.Title>
  </Card.Header>
  <Card.Body>内容</Card.Body>
  <Card.Footer>操作</Card.Footer>
</Card>

// ❌ 坏：属性太多
<Card
  title="标题"
  content="内容"
  footerContent="操作"
  hasHeader={true}
  hasFooter={true}
/>

4. 多态组件 允许组件渲染为不同的HTML元素：

<Button as="a" href="/login">登录</Button>
<Button as="button" onClick={handleClick}>点击我</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">
  内容
</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对比度检查器

键盘导航

// ✅ 所有交互元素必须可键盘访问
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  点击我
</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. 采用阶段

创建迁移指南：帮助团队采用
提供代码修改工具：尽可能自动化迁移
运行工作坊：培训团队使用
收集反馈：基于实际使用迭代

4. 维护阶段

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

快速开始清单

创建新设计系统时：

[ ] 定义设计原则和价值
[ ] 建立设计令牌结构（颜色、排版、间距）
[ ] 创建原始调色板（50-950比例）
[ ] 定义语义颜色令牌（品牌、文本、背景、反馈）
[ ] 设置排版比例和字体家族
[ ] 建立间距比例（基于4px或8px）
[ ] 设计原子组件（按钮、输入、标签等）
[ ] 实现主题化系统（浅色/深色模式）
[ ] 确保WCAG 2.1 Level AA合规
[ ] 设置文档（Storybook或类似）
[ ] 为每个组件创建使用示例
[ ] 建立版本控制和发布策略
[ ] 为采用团队创建迁移指南