Back to Details

design-system-starter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design System Starter

设计系统入门模板

Build robust, scalable design systems that ensure visual consistency and exceptional user experiences.
构建稳健、可扩展的设计系统，确保视觉一致性与出色的用户体验。

Quick Start

快速开始

Just describe what you need:
Create a design system for my React app with dark mode support
That's it. The skill provides tokens, components, and accessibility guidelines.
只需描述你的需求：
Create a design system for my React app with dark mode support
就是这么简单。该工具会提供设计令牌、组件及无障碍指南。

Triggers

触发指令

TriggerExample
Create design system"Create a design system for my app"
Design tokens"Set up design tokens for colors and spacing"
Component architecture"Design component structure using atomic design"
Accessibility"Ensure WCAG 2.1 compliance for my components"
Dark mode"Implement theming with dark mode support"
触发指令示例
创建设计系统"为我的应用创建一个设计系统"
设计令牌配置"为颜色和间距设置设计令牌"
组件架构设计"使用原子设计方法设计组件结构"
无障碍优化"确保我的组件符合WCAG 2.1标准"
深色模式实现"支持深色模式的主题配置"

Quick Reference

快速参考

TaskOutput
Design tokensColor, typography, spacing, shadows JSON
Component structureAtomic design hierarchy (atoms, molecules, organisms)
ThemingCSS variables or ThemeProvider setup
AccessibilityWCAG 2.1 AA compliant patterns
DocumentationComponent docs with props, examples, a11y notes
任务输出内容
设计令牌颜色、排版、间距、阴影配置JSON
组件结构原子设计层级（原子、分子、有机体、模板、页面）
主题配置CSS变量或ThemeProvider设置
无障碍优化符合WCAG 2.1 AA标准的实现模式
文档输出包含属性、示例、无障碍说明的组件文档

Bundled Resources

内置资源

  • references/component-examples.md
    - Complete component implementations
  • templates/design-tokens-template.json
    - W3C design token format
  • templates/component-template.tsx
    - React component template
  • checklists/design-system-checklist.md
    - Design system audit checklist
  • references/component-examples.md
    - 完整的组件实现示例
  • templates/design-tokens-template.json
    - W3C标准设计令牌格式
  • templates/component-template.tsx
    - React组件模板
  • checklists/design-system-checklist.md
    - 设计系统审核清单

Design System Philosophy

设计系统理念

What is a Design System?

什么是设计系统？

A design system is more than a component library—it's a collection of:
  1. Design Tokens: Foundational design decisions (colors, spacing, typography)
  2. Components: Reusable UI building blocks
  3. Patterns: Common UX solutions and compositions
  4. Guidelines: Rules, principles, and best practices
  5. Documentation: How to use everything effectively
设计系统不仅仅是组件库——它是一套包含以下内容的集合：
  1. 设计令牌：基础设计决策（颜色、间距、排版）
  2. 组件：可复用的UI构建块
  3. 模式：通用UX解决方案与组合方式
  4. 指南：规则、原则与最佳实践
  5. 文档：如何有效使用所有内容

Core Principles

核心原则

1. Consistency Over Creativity
  • Predictable patterns reduce cognitive load
  • Users learn once, apply everywhere
  • Designers and developers speak the same language
2. Accessible by Default
  • WCAG 2.1 Level AA compliance minimum
  • Keyboard navigation built-in
  • Screen reader support from the start
3. Scalable and Maintainable
  • Design tokens enable global changes
  • Component composition reduces duplication
  • Versioning and deprecation strategies
4. Developer-Friendly
  • Clear API contracts
  • Comprehensive documentation
  • Easy to integrate and customize
1. 一致性优先于创意
  • 可预测的模式降低认知负荷
  • 用户只需学习一次，即可在全场景应用
  • 设计师与开发者使用统一的语言
2. 默认支持无障碍访问
  • 最低符合WCAG 2.1 AA级标准
  • 内置键盘导航支持
  • 从设计初期就考虑屏幕阅读器适配
3. 可扩展与可维护
  • 设计令牌支持全局样式变更
  • 组件组合减少代码重复
  • 版本管理与组件弃用策略
4. 对开发者友好
  • 清晰的API约定
  • 全面的文档说明
  • 易于集成与自定义

Design Tokens

设计令牌

Design tokens are the atomic design decisions that define your system's visual language.
设计令牌是定义系统视觉语言的原子级设计决策。

Token Categories

令牌分类

1. Color Tokens

1. 颜色令牌

Primitive Colors (Raw values):
json
{
  "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"
      }
    }
  }
}
Semantic Colors (Contextual meaning):
json
{
  "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}"
      }
    }
  }
}
Accessibility: Ensure color contrast ratios meet WCAG 2.1 Level AA:
  • Normal text: 4.5:1 minimum
  • Large text (18pt+ or 14pt+ bold): 3:1 minimum
  • UI components and graphics: 3:1 minimum
基础颜色（原始值）：
json
{
  "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"
      }
    }
  }
}
语义化颜色（上下文含义）：
json
{
  "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 Tokens

2. 排版令牌

json
{
  "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"
    }
  }
}
json
{
  "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. Spacing Tokens

3. 间距令牌

Scale: Use a consistent spacing scale (commonly 4px or 8px base)
json
{
  "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-Specific Spacing:
json
{
  "component": {
    "button": {
      "padding-x": "{spacing.4}",
      "padding-y": "{spacing.2}",
      "gap": "{spacing.2}"
    },
    "card": {
      "padding": "{spacing.6}",
      "gap": "{spacing.4}"
    }
  }
}
缩放规则：使用统一的间距缩放（通常以4px或8px为基础单位）
json
{
  "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
  }
}
组件专用间距：
json
{
  "component": {
    "button": {
      "padding-x": "{spacing.4}",
      "padding-y": "{spacing.2}",
      "gap": "{spacing.2}"
    },
    "card": {
      "padding": "{spacing.6}",
      "gap": "{spacing.4}"
    }
  }
}

4. Border Radius Tokens

4. 圆角令牌

json
{
  "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"
  }
}
json
{
  "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 Tokens

5. 阴影令牌

json
{
  "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)"
  }
}
json
{
  "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)"
  }
}

Component Architecture

组件架构

Atomic Design Methodology

原子设计方法论

Atoms → Molecules → Organisms → Templates → Pages
原子 → 分子 → 有机体 → 模板 → 页面

Atoms (Primitive Components)

原子（基础组件）

Basic building blocks that can't be broken down further.
Examples:
  • Button
  • Input
  • Label
  • Icon
  • Badge
  • Avatar
Button Component:
typescript
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
}
See 
references/component-examples.md
for complete Button implementation with variants, sizes, and styling patterns.
无法再拆分的基础构建块。
示例：
  • Button
  • Input
  • Label
  • Icon
  • Badge
  • Avatar
Button组件：
typescript
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
获取包含变体、尺寸和样式模式的完整Button实现。

Molecules (Simple Compositions)

分子（简单组合组件）

Groups of atoms that function together.
Examples:
  • SearchBar (Input + Button)
  • FormField (Label + Input + ErrorMessage)
  • Card (Container + Title + Content + Actions)
FormField Molecule:
typescript
interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}
See 
references/component-examples.md
for FormField, Card (compound component pattern), Input with variants, Modal, and more composition examples.
由多个原子组合而成的功能单元。
示例：
  • SearchBar（Input + Button）
  • FormField（Label + Input + ErrorMessage）
  • Card（容器 + 标题 + 内容 + 操作区）
FormField分子组件：
typescript
interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}
查看
references/component-examples.md
获取FormField、Card（复合组件模式）、带变体的Input、Modal等更多组合示例。

Organisms (Complex Compositions)

有机体（复杂组合组件）

Complex UI components made of molecules and atoms.
Examples:
  • Navigation Bar
  • Product Card Grid
  • User Profile Section
  • Modal Dialog
由分子和原子组成的复杂UI组件。
示例：
  • 导航栏
  • 产品卡片网格
  • 用户资料区域
  • 模态对话框

Templates (Page Layouts)

模板（页面布局）

Page-level structures that define content placement.
Examples:
  • Dashboard Layout (Sidebar + Header + Main Content)
  • Marketing Page Layout (Hero + Features + Footer)
  • Settings Page Layout (Tabs + Content Panels)
定义内容布局的页面级结构。
示例：
  • 仪表板布局（侧边栏 + 头部 + 主内容区）
  • 营销页面布局（Hero区 + 功能区 + 页脚）
  • 设置页面布局（标签页 + 内容面板）

Pages (Specific Instances)

页面（具体实例）

Actual pages with real content.
包含真实内容的实际页面。

Component API Design

组件API设计

Props Best Practices

属性最佳实践

1. Predictable Prop Names
typescript
// ✅ 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. Sensible Defaults
typescript
// ✅ 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. Composition Over Configuration
typescript
// ✅ 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. Polymorphic Components Allow components to render as different HTML elements:
typescript
<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>
See 
references/component-examples.md
for complete polymorphic component TypeScript patterns.
1. 可预测的属性命名
typescript
// ✅ 推荐：命名一致
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ 不推荐：命名不一致
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />
2. 合理的默认值
typescript
// ✅ 推荐：提供默认值
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. 组合优先于配置
typescript
// ✅ 推荐：支持组件组合
<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元素：
typescript
<Button as="a" href="/login">Login</Button>
<Button as="button" onClick={handleClick}>Click Me</Button>
查看
references/component-examples.md
获取完整的多态组件TypeScript实现模式。

Theming and Dark Mode

主题与深色模式

Theme Structure

主题结构

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>;
}
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>;
}

Dark Mode Implementation

深色模式实现

Approach 1: CSS Variables
css
:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #000000;
}

[data-theme="dark"] {
  --color-bg-primary: #1a1a1a;
  --color-text-primary: #ffffff;
}
Approach 2: Tailwind CSS Dark Mode
tsx
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Content
</div>
Approach 3: Styled Components ThemeProvider
typescript
const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>
方案1：CSS变量
css
:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #000000;
}

[data-theme="dark"] {
  --color-bg-primary: #1a1a1a;
  --color-text-primary: #ffffff;
}
方案2：Tailwind CSS深色模式
tsx
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Content
</div>
方案3：Styled Components ThemeProvider
typescript
const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>

Accessibility Guidelines

无障碍指南

WCAG 2.1 Level AA Compliance

WCAG 2.1 AA级合规要求

Color Contrast

颜色对比度

  • Normal text (< 18pt): 4.5:1 minimum
  • Large text (≥ 18pt or ≥ 14pt bold): 3:1 minimum
  • UI components: 3:1 minimum
Tools: Use contrast checkers like WebAIM Contrast Checker
  • 普通文本（<18pt）：最低4.5:1
  • 大文本（≥18pt或≥14pt加粗）：最低3:1
  • UI组件：最低3:1
工具：使用对比度检查工具，如WebAIM Contrast Checker

Keyboard Navigation

键盘导航

typescript
// ✅ 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>
typescript
// ✅ 所有交互元素必须支持键盘访问
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ 焦点管理
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

ARIA Attributes

ARIA属性

Essential ARIA patterns:
  • aria-label
    : Provide accessible names
  • aria-expanded
    : Communicate expanded/collapsed state
  • aria-controls
    : Associate controls with content
  • aria-live
    : Announce dynamic content changes
必备的ARIA模式：
  • aria-label
    ：提供无障碍名称
  • aria-expanded
    ：传达展开/折叠状态
  • aria-controls
    ：关联控件与内容
  • aria-live
    ：通知动态内容变更

Screen Reader Support

屏幕阅读器支持

  • Use semantic HTML elements (
    <button>
    , 
    <nav>
    , 
    <main>
    )
  • Avoid div/span soup for interactive elements
  • Provide meaningful labels for all controls
See 
references/component-examples.md
for complete accessibility examples including Skip Links, focus traps, and ARIA patterns.
  • 使用语义化HTML元素（
    <button>
    、
    <nav>
    、
    <main>
    ）
  • 避免使用div/span构建交互元素
  • 为所有控件提供有意义的标签
查看
references/component-examples.md
获取完整的无障碍示例，包括跳转链接、焦点陷阱和ARIA模式。

Documentation Standards

文档标准

Component Documentation Template

组件文档模板

Each component should document:
  • Purpose: What the component does
  • Usage: Import statement and basic example
  • Variants: Available visual styles
  • Props: Complete prop table with types, defaults, descriptions
  • Accessibility: Keyboard support, ARIA attributes, screen reader behavior
  • Examples: Common use cases with code
Use Storybook, Docusaurus, or similar tools for interactive documentation.
See 
templates/component-template.tsx
for the standard component structure.
每个组件应包含以下文档内容：
  • 用途：组件的功能说明
  • 使用方式：导入语句与基础示例
  • 变体：可用的视觉样式
  • 属性：完整的属性表格，包含类型、默认值和描述
  • 无障碍：键盘支持、ARIA属性、屏幕阅读器行为
  • 示例：常见使用场景与代码
使用Storybook、Docusaurus或类似工具创建交互式文档。
查看
templates/component-template.tsx
获取标准组件结构。

Design System Workflow

设计系统工作流

1. Design Phase

1. 设计阶段

  • Audit existing patterns: Identify inconsistencies
  • Define design tokens: Colors, typography, spacing
  • Create component inventory: List all needed components
  • Design in Figma: Create component library
  • 审核现有模式：识别不一致之处
  • 定义设计令牌：颜色、排版、间距
  • 创建组件清单：列出所有需要的组件
  • Figma设计：创建组件库

2. Development Phase

2. 开发阶段

  • Set up tooling: Storybook, TypeScript, testing
  • Implement tokens: CSS variables or theme config
  • Build atoms first: Start with primitives
  • Compose upward: Build molecules, organisms
  • Document as you go: Write docs alongside code
  • 搭建工具链：Storybook、TypeScript、测试工具
  • 实现设计令牌：CSS变量或主题配置
  • 先构建原子组件：从基础组件开始
  • 向上组合：构建分子、有机体组件
  • 边开发边文档：代码与文档同步编写

3. Adoption Phase

3. 落地阶段

  • Create migration guide: Help teams adopt
  • Provide codemods: Automate migrations when possible
  • Run workshops: Train teams on usage
  • Gather feedback: Iterate based on real usage
  • 创建迁移指南：帮助团队采用新设计系统
  • 提供代码迁移工具：尽可能自动化迁移
  • 开展培训工作坊：指导团队使用
  • 收集反馈：基于实际使用情况迭代优化

4. Maintenance Phase

4. 维护阶段

  • Version semantically: Major/minor/patch releases
  • Deprecation strategy: Phase out old components gracefully
  • Changelog: Document all changes
  • Monitor adoption: Track usage across products
  • 语义化版本管理：主版本/次版本/补丁版本发布
  • 组件弃用策略：逐步淘汰旧组件
  • 变更日志：记录所有变更内容
  • 监控落地情况：跟踪跨产品的使用情况

Quick Start Checklist

快速入门检查清单

When creating a new design system:
  • Define design principles and values
  • Establish design token structure (colors, typography, spacing)
  • Create primitive color palette (50-950 scale)
  • Define semantic color tokens (brand, text, background, feedback)
  • Set typography scale and font families
  • Establish spacing scale (4px or 8px base)
  • Design atomic components (Button, Input, Label, etc.)
  • Implement theming system (light/dark mode)
  • Ensure WCAG 2.1 Level AA compliance
  • Set up documentation (Storybook or similar)
  • Create usage examples for each component
  • Establish versioning and release strategy
  • Create migration guides for adopting teams
创建新设计系统时：
  • 定义设计原则与价值观
  • 建立设计令牌结构（颜色、排版、间距）
  • 创建基础调色板（50-950色阶）
  • 定义语义化颜色令牌（品牌、文本、背景、反馈）
  • 设置排版比例与字体族
  • 建立间距缩放规则（4px或8px为基础单位）
  • 设计原子组件（Button、Input、Label等）
  • 实现主题系统（浅色/深色模式）
  • 确保符合WCAG 2.1 AA级标准
  • 搭建文档系统（Storybook或类似工具）
  • 为每个组件创建使用示例
  • 建立版本管理与发布策略
  • 为落地团队创建迁移指南