design-system-documenter

设计系统文档生成器

将原始设计令牌转化为开发者易用的文档，并提供使用示例、无障碍说明和实现指南。

快速开始

最简示例——为令牌文件编写文档：

Input: Generated tokens.json or CSS variables file
Output: Complete documentation with:
- Token reference tables
- Usage examples in code
- Accessibility annotations
- Do/Don't examples

核心原则：文档应该回答“我该在什么时候使用它？”，而不只是“它是什么？”

核心使命

通过编写文档，弥合生成的令牌与开发者采用之间的差距：

1. 说明每个令牌的使用时机（而不只是它是什么）
2. 为常见场景提供真实代码示例
3. 突出无障碍注意事项
4. 通过反模式示例避免误用

适用场景

✅ 适用于：

• 刚生成设计令牌，需要编写文档
• 团队不知道“该用哪个令牌？”
• 为新开发者介绍设计系统
• 创建公开的设计系统网站

❌ 不适用于：

• 需要生成令牌（请先使用 design-system-generator）
• 需要组件代码（请使用 component-template-generator）
• 为非设计系统代码编写文档（请使用 docs-architect）

文档结构

1. 令牌参考表

为每个令牌类别生成表格：

令牌	值	用途	无障碍
--color-primary	#FF5252	CTA、链接、强调	✅ 在白色背景上为 4.5:1
--color-border	#000000	所有边框、分隔线	—

2. 使用指南

## Color Tokens

### Primary Colors
Use primary colors for:
- Call-to-action buttons
- Interactive links
- Important highlights

Do NOT use for:
- Body text
- Background fills (too saturated)
- Disabled states

### Code Example
```css
.button-primary {
  background: var(--color-primary);
  color: var(--color-text-on-primary);
  border: var(--border-width) solid var(--color-border);
}

### 3. Visual Examples

Include visual swatches and demonstrations:

```markdown
## Shadow Tokens

| Name | Preview | CSS Value |
|------|---------|-----------|
| shadow-sm | [2px offset visual] | `2px 2px 0 0 #000` |
| shadow-md | [4px offset visual] | `4px 4px 0 0 #000` |
| shadow-lg | [6px offset visual] | `6px 6px 0 0 #000` |

### Interaction States
- **Default**: `shadow-md`
- **Hover**: `shadow-lg` + translate(-2px, -2px)
- **Active**: `shadow-sm` + translate(2px, 2px)

4. 无障碍章节

## Accessibility

### Color Contrast
| Combination | Ratio | WCAG Level |
|-------------|-------|------------|
| Primary on White | 4.8:1 | ✅ AA |
| Primary on Cream | 4.2:1 | ⚠️ AA Large only |
| Text on Primary | 8.2:1 | ✅ AAA |

### Motion
All animations respect `prefers-reduced-motion`:
```css
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; }
}

### 5. Do/Don't Examples

```markdown
## Common Mistakes

### ❌ Don't: Use shadow-lg on small elements
Small elements with large shadows look unbalanced.

### ✅ Do: Scale shadow with element size
- Small buttons: shadow-sm
- Cards: shadow-md
- Modals: shadow-lg

### ❌ Don't: Mix border styles
Inconsistent borders break visual rhythm.

### ✅ Do: Use consistent border tokens
Always use `--border-width` (3px) for neobrutalist consistency.

输出格式

Markdown（默认）

适用于文档网站的完整 .md 文件：

• 兼容 Docusaurus/VitePress
• 包含用于导航的 frontmatter
• 带语法高亮的代码块

MDX（React 文档）

与 Markdown 相同，另包括：

• 交互式颜色样本
• 实时代码示例
• 令牌预览组件

Storybook

文档故事：

• 令牌展示页面
• 交互式控件
• 设计令牌插件集成

文档工作流

1. design-system-generator → tokens.json / tokens.css
2. design-system-documenter → tokens-docs.md
3. Review and customize
4. Publish to docs site

模板：令牌文档页面

---
title: Design Tokens
description: Complete reference for [Project] design tokens
---

# Design Tokens

Generated from [trend-name] design trend.

## Quick Reference

| Category | Tokens | Description |
|----------|--------|-------------|
| Colors | 12 | Primary, neutral, semantic |
| Typography | 8 | Fonts, sizes, weights |
| Spacing | 15 | 0-24 scale |
| Shadows | 5 | Size and state variants |

## Colors

### Primary Palette
[Token table with hex, usage, accessibility]

### Neutral Palette
[Token table]

### Semantic Colors
[Token table for success, warning, error, info]

## Typography

### Font Families
[Token table with font stacks and usage]

### Font Sizes
[Scale table with px/rem values]

## Spacing

### Spacing Scale
[0-24 scale with rem values]

## Shadows

### Shadow Variants
[Visual examples with code]

## Usage Examples

### Button Component
[Complete code example using tokens]

### Card Component
[Complete code example using tokens]

## Accessibility

### Contrast Ratios
[All color combinations with WCAG levels]

### Motion Preferences
[Reduced motion handling]

## Migration Guide

### From Arbitrary Values
[Before/after examples]

另请参阅

参考资料

• references/documentation-templates.md - Docusaurus、VitePress、Storybook、README 模板
• references/design-system-references.md - 全新：真实世界的设计系统参考
  • 企业级：Elastic UI、Red Hat PatternFly、Morningstar
  • 无障碍优先：Ariakit、Radix UI
  • 现代风格：HeroUI、shadcn/ui、Neobrutalism.dev
  • 与框架无关：Web Awesome、Shoelace
  • 从 Awwwards 的获奖网站汲取灵感
  • Framer 模板类别（2900+ 商业类、1700+ 创意类）

相关技能

• design-system-generator - 先生成令牌（24 种趋势、31 种风格）
• component-template-generator - 根据令牌创建组件代码