design-system

/design-system

如果你看到不熟悉的占位符，或需要确认已连接哪些工具，请参阅 CONNECTORS.md。

管理你的设计系统：审计一致性、记录组件，或设计新的模式。

用法

/design-system audit                    # Full system audit
/design-system document [component]     # Document a component
/design-system extend [pattern]         # Design a new component or pattern

设计系统的组成部分

设计令牌

定义视觉语言的原子值：

• 颜色（品牌色、语义色、中性色）
• 字体排版（字阶、字重、行高）
• 间距（间距阶梯、组件内边距）
• 边框（圆角、宽度）
• 阴影（层级高度）
• 动效（时长、缓动函数）

组件

可复用的 UI 元素，定义包括：

• 变体（主要、次要、幽灵）
• 状态（默认、悬停、激活、禁用、加载中、错误）
• 尺寸（sm、md、lg）
• 行为（交互、动画）
• 无障碍（ARIA、键盘操作）

模式

结合组件的常见 UI 解决方案：

• 表单（输入组、校验、提交）
• 导航（侧边栏、标签页、面包屑）
• 数据展示（表格、卡片、列表）
• 反馈（轻提示、模态框、行内消息）

原则

1. 一致性优先于创意：设计系统的存在是为了让团队不必重复造轮子
2. 约束内的灵活性：组件应可组合，而非僵化
3. 记录一切：没有文档记录的东西，等同于不存在
4. 版本化并迁移：破坏性变更需要提供迁移路径

输出：审计

## Design System Audit

### Summary
**Components reviewed:** [X] | **Issues found:** [X] | **Score:** [X/100]

### Naming Consistency
| Issue | Components | Recommendation |
|-------|------------|----------------|
| [Inconsistent naming] | [List] | [Standard to adopt] |

### Token Coverage
| Category | Defined | Hardcoded Values Found |
|----------|---------|----------------------|
| Colors | [X] | [X] instances of hardcoded hex |
| Spacing | [X] | [X] instances of arbitrary values |
| Typography | [X] | [X] instances of custom fonts/sizes |

### Component Completeness
| Component | States | Variants | Docs | Score |
|-----------|--------|----------|------|-------|
| Button | ✅ | ✅ | ⚠️ | 8/10 |
| Input | ✅ | ⚠️ | ❌ | 5/10 |

### Priority Actions
1. [Most impactful improvement]
2. [Second priority]
3. [Third priority]

输出：文档

## Component: [Name]

### Description
[What this component is and when to use it]

### Variants
| Variant | Use When |
|---------|----------|
| [Primary] | [Main actions] |
| [Secondary] | [Supporting actions] |

### Props / Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

### States
| State | Visual | Behavior |
|-------|--------|----------|
| Default | [description] | — |
| Hover | [description] | [interaction] |
| Active | [description] | [interaction] |
| Disabled | [description] | Non-interactive |
| Loading | [description] | [animation] |

### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Tab, Enter, Escape behavior]
- **Screen reader**: [Announced as...]

### Do's and Don'ts
| ✅ Do | ❌ Don't |
|------|---------|
| [Best practice] | [Anti-pattern] |

### Code Example
[Framework-appropriate code snippet]

输出：扩展

## New Component: [Name]

### Problem
[What user need or gap this component addresses]

### Existing Patterns
| Related Component | Similarity | Why It's Not Enough |
|-------------------|-----------|---------------------|
| [Component] | [What's shared] | [What's missing] |

### Proposed Design

#### API / Props
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

#### Variants
| Variant | Use When | Visual |
|---------|----------|--------|
| [Variant] | [Scenario] | [Description] |

#### States
| State | Behavior | Notes |
|-------|----------|-------|
| Default | [Description] | — |
| Hover | [Description] | [Interaction] |
| Disabled | [Description] | Non-interactive |
| Loading | [Description] | [Animation] |

#### Tokens Used
- Colors: [Which tokens]
- Spacing: [Which tokens]
- Typography: [Which tokens]

### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Expected interactions]
- **Screen reader**: [Announced as...]

### Open Questions
- [Decision that needs design review]
- [Edge case to resolve]

如果有可用的连接器

如果已连接 ~~设计工具：

• 直接在 Figma 中审计组件，检查命名、变体和令牌使用情况
• 提取组件属性和图层结构用于文档编写

如果已连接 ~~知识库：

• 搜索现有的组件文档和使用指南
• 将更新后的文档发布到你的 Wiki

提示

1. 从审计开始：在决定去向何处之前，先了解自己所处的位置。
2. 边做边记录：在设计组件的同时记录文档会更容易。
3. 优先保证覆盖率，而非追求完美：记录了 80% 的组件，胜过完美记录 10 个组件。