design-system-architecture

设计系统架构

构建可扩展设计系统的全面指南，涵盖合理的令牌架构、组件 API 和文档策略。

何时使用此技能

• 从零开始创建新的设计系统
• 演进现有组件库
• 定义令牌架构
• 建立组件 API 模式
• 设置设计系统文档

令牌架构

三层令牌系统

┌─────────────────────────────────────┐
│       Component Tokens              │  → button-primary-bg
│     (Specific to components)        │
├─────────────────────────────────────┤
│       Semantic Tokens               │  → color-action-primary
│     (Purpose-based naming)          │
├─────────────────────────────────────┤
│       Primitive Tokens              │  → blue-500
│     (Raw values)                    │
└─────────────────────────────────────┘

令牌类别

/* Primitive Tokens */
--color-blue-500: #3b82f6;
--spacing-4: 1rem;
--font-size-base: 16px;
--radius-md: 8px;

/* Semantic Tokens */
--color-action-primary: var(--color-blue-500);
--color-text-primary: var(--color-gray-900);
--spacing-component-gap: var(--spacing-4);

/* Component Tokens */
--button-bg: var(--color-action-primary);
--button-padding-x: var(--spacing-4);
--card-radius: var(--radius-md);

主题支持

// tokens/themes.ts
export const lightTheme = {
  'color-bg-primary': 'var(--color-white)',
  'color-text-primary': 'var(--color-gray-900)',
  'color-border': 'var(--color-gray-200)',
}

export const darkTheme = {
  'color-bg-primary': 'var(--color-gray-900)',
  'color-text-primary': 'var(--color-gray-100)',
  'color-border': 'var(--color-gray-700)',
}

组件 API 模式

属性 API 设计

// ✅ Good: Clear, typed, with sensible defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
  isDisabled?: boolean;
  leftIcon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}

// ✅ With defaults
const Button = ({
  variant = 'primary',
  size = 'md',
  isLoading = false,
  isDisabled = false,
  ...props
}: ButtonProps) => { ... }

复合组件模式

// Compound components for complex UIs
const Tabs = ({ children, defaultValue }) => { ... }
Tabs.List = ({ children }) => { ... }
Tabs.Tab = ({ value, children }) => { ... }
Tabs.Panel = ({ value, children }) => { ... }

// Usage
<Tabs defaultValue="tab1">
  <Tabs.List>
    <Tabs.Tab value="tab1">First</Tabs.Tab>
    <Tabs.Tab value="tab2">Second</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="tab1">Content 1</Tabs.Panel>
  <Tabs.Panel value="tab2">Content 2</Tabs.Panel>
</Tabs>

多态组件

// Component that can render as different elements
interface BoxProps<C extends React.ElementType> {
  as?: C;
  children?: React.ReactNode;
}

type PolymorphicProps<C extends React.ElementType> =
  BoxProps<C> & Omit<React.ComponentPropsWithoutRef<C>, keyof BoxProps<C>>;

const Box = <C extends React.ElementType = 'div'>({
  as,
  ...props
}: PolymorphicProps<C>) => {
  const Component = as || 'div';
  return <Component {...props} />;
};

// Usage
<Box as="section" className="...">Content</Box>
<Box as="button" onClick={...}>Click me</Box>

组件类别（原子设计）

原子（基础组件）

• Button、Input、Label、Icon
• Typography（Text、Heading）
• Box、Flex、Grid（布局基础组件）

分子（组合组件）

• FormField（Label + Input + Error）
• SearchInput（Input + Icon + Button）
• Card（Box + 内边距 + 边框）

有机体（功能模块）

• Header（Logo + Nav + UserMenu）
• DataTable（Table + Pagination + Filters）
• Modal（Overlay + Card + Actions）

文档策略

组件文档

# Button

Buttons trigger actions or navigate users.

## Usage

\`\`\`jsx
import { Button } from '@/components/ui'

<Button variant="primary" size="md">
  Click me
</Button>
\`\`\`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Size preset |

## Examples

### Variants
[Interactive examples]

### With Icons
[Interactive examples]

## Accessibility

- Uses `<button>` element by default
- Supports keyboard activation
- Loading state announced to screen readers

最佳实践

设计原则

1. 组合优于配置：采用小巧、可组合的组件
2. 合理的默认值：开箱即用
3. 默认具备可访问性：无障碍体验不可或缺
4. 类型安全的 API：TypeScript 可引导使用方式
5. 最小化 API 范围：仅公开所需内容

维护

• 对不兼容的变更采用语义化版本控制
• 移除功能前发出弃用警告
• 为主版本提供迁移指南
• 自动化视觉回归测试

资源

• Radix UI 基础组件
• Chakra UI 组件模式
• 设计令牌社区组