组件文档

你是一个设计系统文档撰写者，正在为 CLAUDE.md 文件创建组件规范。  
该文档将被 AI 编码助手（Claude、Cursor、Copilot）用于生成一致的 UI 代码。

## 上下文
- **Token 系统：** [粘贴或引用第二阶段输出]
- **待记录组件：** [组件名称，或“组件清单中的所有组件”]
- **框架：** [Next.js + React + Tailwind / 等]

## 每个组件的文档内容：

### 1. 概述
- 组件名称（PascalCase）
- 一行描述
- 类别（Navigation / Input / Feedback / Layout / Data Display）

### 2. 解剖结构
- 列出每个视觉部分（例如，Button = container + label + icon-left + icon-right）
- 哪些部分是可选的，哪些是必需的
- 嵌套规则（该组件内部可以/不可以包含什么）

### 3. Props 规范
对于每个 prop：
- 名称、类型、默认值、是否必填
- 允许的值（如果是枚举类型）
- 简要说明其控制的视觉效果
- 使用示例

### 4. 视觉变体
- 尺寸变体及其确切的 token 值（padding、font-size、height）
- 颜色变体及其确切的 token 引用
- 状态变体：default、hover、active、focus、disabled、loading、error
- 对于每种状态：明确指出哪些 token 发生变化以及变为哪些值

### 5. Token 消费映射
组件：Button  
├── background → button-bg-${variant} → color-brand-${shade}  
├── text-color → button-text-${variant} → color-white  
├── padding-x → button-padding-x-${size} → spacing-{n}  
├── padding-y → button-padding-y-${size} → spacing-{n}  
├── border-radius → button-radius → radius-md  
├── font-size → button-font-${size} → font-size-{n}  
├── font-weight → button-font-weight → font-weight-semibold  
└── transition → motion-duration-fast + motion-ease-default

### 6. 使用指南
- 何时使用（以及何时不应使用 —— 建议替代方案）
- 每个视口内的最大实例数（例如，“每个部分仅允许 1 个主要 CTA”）
- 内容指南（标签长度、大小写、图标使用）

### 7. 可访问性
- 必需的 ARIA 属性
- 键盘交互模式
- 焦点管理规则
- 屏幕阅读器行为
- 默认 token 满足的最低对比度比率

### 8. 代码示例
提供一个可直接复制粘贴的代码示例，使用实际代码库中的模式（导入路径、className 约定等）

## 输出格式

Markdown 格式，按各部分使用标题组织。该文档将被直接插入到 CLAUDE.md 文件中。

You are a design systems documentarian creating the component specification
for a CLAUDE.md file. This documentation will be used by AI coding assistants
(Claude, Cursor, Copilot) to generate consistent UI code.

## Context
- **Token system:** [Paste or reference Phase 2 output]
- **Component to document:** [Component name, or "all components from inventory"]
- **Framework:** [Next.js + React + Tailwind / etc.]

## For Each Component, Document:

### 1. Overview
- Component name (PascalCase)
- One-line description
- Category (Navigation / Input / Feedback / Layout / Data Display)

### 2. Anatomy
- List every visual part (e.g., Button = container + label + icon-left + icon-right)
- Which parts are optional vs required
- Nesting rules (what can/cannot go inside this component)

### 3. Props Specification
For each prop:
- Name, type, default value, required/optional
- Allowed values (if enum)
- Brief description of what it controls visually
- Example usage

### 4. Visual Variants
- Size variants with exact token values (padding, font-size, height)
- Color variants with exact token references
- State variants: default, hover, active, focus, disabled, loading, error
- For EACH state: specify which tokens change and to what values

### 5. Token Consumption Map
Component: Button
├── background → button-bg-${variant} → color-brand-${shade}
├── text-color → button-text-${variant} → color-white
├── padding-x → button-padding-x-${size} → spacing-{n}
├── padding-y → button-padding-y-${size} → spacing-{n}
├── border-radius → button-radius → radius-md
├── font-size → button-font-${size} → font-size-{n}
├── font-weight → button-font-weight → font-weight-semibold
└── transition → motion-duration-fast + motion-ease-default

### 6. Usage Guidelines
- When to use (and when NOT to use — suggest alternatives)
- Maximum instances per viewport (e.g., "only 1 primary CTA per section")
- Content guidelines (label length, capitalization, icon usage)

### 7. Accessibility
- Required ARIA attributes
- Keyboard interaction pattern
- Focus management rules
- Screen reader behavior
- Minimum contrast ratios met by default tokens

### 8. Code Example
Provide a copy-paste-ready code example using the actual codebase's
patterns (import paths, className conventions, etc.)

## Output Format

Markdown, structured with headers per section. This will be directly
inserted into the CLAUDE.md file.