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
```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 templatesreferences/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
Output Contract
This skill produces:
- React components with TypeScript types, props interfaces, and JSDoc
- State management hooks or context with typed actions and selectors
- Styling via CSS modules, Tailwind classes, or styled-components
- Unit tests for component rendering, interaction, and edge cases
- Accessibility attributes (ARIA labels, keyboard navigation, focus management)