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

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