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:

• Explains when to use each token (not just what it is)

• Shows real code examples for common scenarios

• Highlights accessibility considerations

• 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

.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 Section

## 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.

Output Formats

Markdown (Default)

Complete .md
 file for docs sites:

- Docusaurus/VitePress compatible

- Includes frontmatter for navigation

- Code blocks with syntax highlighting

MDX (React docs)

Same as Markdown plus:

- Interactive color swatches

- Live code examples

- Token preview components

Storybook

Documentation stories:

- Token showcase pages

- Interactive controls

- Design token addon integration

Documentation Workflow

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

Template: Token Documentation Page

---
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]

See Also

References

- references/documentation-templates.md
 - Docusaurus, VitePress, Storybook, README templates

- references/design-system-references.md
 - NEW: Real-world design system references

- Enterprise: Elastic UI, Red Hat PatternFly, Morningstar

- Accessibility-first: Ariakit, Radix UI

- Modern: HeroUI, shadcn/ui, Neobrutalism.dev

- Framework-agnostic: Web Awesome, Shoelace

- Award-winning sites from Awwwards for inspiration

- Framer template categories (2900+ business, 1700+ creative)

Related Skills

- design-system-generator - Generate tokens first (24 trends, 31 styles)

- component-template-generator - Create component code from tokens