design-system-documenter

Design System Documenter

Transform raw design tokens into developer-friendly documentation with usage examples, accessibility notes, and implementation guidelines.

Quick Start

Minimal example - document a token file:

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

Key principle: Documentation should answer "when do I use this?" not just "what is this?".

Core Mission

Bridge the gap between generated tokens and developer adoption by creating documentation that:

1. Explains when to use each token (not just what it is)
2. Shows real code examples for common scenarios
3. Highlights accessibility considerations
4. Prevents misuse with anti-pattern examples

When to Use

✅ Use when:

• Just generated design tokens and need docs
• Team struggles with "which token do I use?"
• Onboarding new developers to design system
• Creating a public design system site

❌ Do NOT use when:

• Need to generate tokens (use design-system-generator first)
• Need component code (use component-template-generator)
• Documenting non-design-system code (use docs-architect)

Documentation Structure

1. Token Reference Tables

For each token category, generate tables with:

Token	Value	Usage	Accessibility
--color-primary	#FF5252	CTAs, links, emphasis	✅ 4.5:1 on white
--color-border	#000000	All borders, dividers	—

2. Usage Guidelines

## 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);
}