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 に対応
• ナビゲーション用のフロントマターを含む
• シンタックスハイライト付きのコードブロック

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 - トークンからコンポーネントコードを作成します