| name | token-docs |
| description | Generates design token documentation with visual swatches and code examples. Use when documenting token values, creating token reference guides, or building searchable design system documentation. |
Design Token Documentation Generator
Overview
Generate comprehensive documentation for design tokens including visual swatches, usage guidelines, code examples, and cross-reference tables. Create living documentation that stays in sync with token values.
When to Use
- Documenting a new token system
- Creating a design system style guide
- Generating token reference for developers
- Building visual documentation pages
Quick Reference: Documentation Sections
| Section | Content | Audience |
|---|
| Overview | System philosophy, naming conventions | All |
| Color Tokens | Swatches, contrast info, usage | Designers, Devs |
| Typography | Font stacks, scale, line heights | Designers, Devs |
| Spacing | Scale visualization, use cases | Devs |
| Shadows | Visual examples, elevation guide | Designers, Devs |
| Radius | Corner examples, component mapping | Devs |
| Breakpoints | Device targets, media queries | Devs |
The Process
- Gather token data: Import from CSS, JSON, or JS files
- Structure sections: Organize by category
- Add visuals: Swatches, scales, examples
- Write guidelines: When and how to use each token
- Include code: Copy-paste examples for each format
- Cross-reference: Link related tokens and components
Documentation Templates
Color Token Documentation
# Color Tokens
Our color system uses OKLCH for perceptual uniformity, ensuring consistent
visual steps across the entire scale.
## Naming Convention
`--color-{name}-{step}`
- **name**: Color category (primary, gray, success, etc.)
- **step**: Lightness value (50-950, lower = lighter)
## Primary
Our brand color, used for primary actions and key UI elements.
| Token | Value | Preview | Use Case |
|-------|-------|---------|----------|
| `--color-primary-50` | oklch(97% 0.01 250) |  | Subtle backgrounds |
| `--color-primary-100` | oklch(93% 0.02 250) |  | Hover states (light) |
| `--color-primary-500` | oklch(55% 0.15 250) |  | **Primary brand color** |
| `--color-primary-600` | oklch(45% 0.15 250) |  | Hover states (dark) |
| `--color-primary-900` | oklch(20% 0.10 250) |  | Text on light backgrounds |
### Accessibility
| Combination | Ratio | WCAG |
|-------------|-------|------|
| primary-900 on white | 9.4:1 | AAA |
| primary-500 on white | 4.5:1 | AA |
| white on primary-500 | 4.5:1 | AA |
| white on primary-600 | 5.8:1 | AA |
### Usage
```css
/* Primary actions */
.btn-primary {
background-color: var(--color-primary-500);
color: white;
}
.btn-primary:hover {
background-color: var(--color-primary-600);
}
/* Accent text */
.link {
color: var(--color-primary-600);
}
Do / Don't
✅ Do:
- Use primary-500 for main CTAs
- Use primary-600 for hover states
- Use primary-50/100 for selected backgrounds
❌ Don't:
- Use primary-500 for large text blocks
- Mix primary colors from different scales
- Use low-contrast combinations (primary-300 on white)
Gray (Neutral)
Neutral colors for text, backgrounds, borders, and UI elements.
| Token | Value | Use Case |
|---|
--color-gray-50 | #f9fafb | Page backgrounds |
--color-gray-100 | #f3f4f6 | Card backgrounds, hover states |
--color-gray-200 | #e5e7eb | Borders, dividers |
--color-gray-300 | #d1d5db | Input borders, disabled |
--color-gray-400 | #9ca3af | Placeholder text |
--color-gray-500 | #6b7280 | Muted text, icons |
--color-gray-600 | #4b5563 | Secondary text |
--color-gray-700 | #374151 | Body text |
--color-gray-800 | #1f2937 | Headings |
--color-gray-900 | #111827 | Primary text |
--color-gray-950 | #030712 | Darkest, rarely used |
Semantic Colors
| Category | Token | Value | Use |
|---|
| Success | --color-success-500 | #22c55e | Success messages, confirmations |
| Warning | --color-warning-500 | #f59e0b | Warnings, caution states |
| Error | --color-error-500 | #ef4444 | Errors, destructive actions |
| Info | --color-info-500 | #3b82f6 | Informational messages |
Each semantic color has a full scale (50-900) for backgrounds, text, and borders.
---
### Typography Token Documentation
```markdown
# Typography Tokens
Our type scale uses a 1.2 (Minor Third) ratio for harmonious sizing.
Line heights are calculated based on font size for optimal readability.
## Font Families
| Token | Value | Use |
|-------|-------|-----|
| `--font-sans` | 'Inter', system-ui, sans-serif | Body text, UI |
| `--font-mono` | 'JetBrains Mono', monospace | Code, technical |
| `--font-serif` | 'Merriweather', Georgia, serif | Editorial (optional) |
## Font Sizes
| Token | Size | Line Height | Use |
|-------|------|-------------|-----|
| `--text-xs` | 12px | 1.7 | Captions, labels |
| `--text-sm` | 14px | 1.7 | Helper text, meta |
| `--text-base` | 16px | 1.6 | Body text |
| `--text-lg` | 18px | 1.55 | Lead paragraphs |
| `--text-xl` | 20px | 1.5 | H4, card titles |
| `--text-2xl` | 24px | 1.4 | H3 |
| `--text-3xl` | 30px | 1.35 | H2 |
| `--text-4xl` | 36px | 1.3 | H1 |
| `--text-5xl` | 48px | 1.2 | Display |
| `--text-6xl` | 60px | 1.1 | Hero |
## Font Weights
| Token | Value | Use |
|-------|-------|-----|
| `--font-normal` | 400 | Body text |
| `--font-medium` | 500 | UI labels, buttons |
| `--font-semibold` | 600 | Subheadings |
| `--font-bold` | 700 | Headings, emphasis |
## Usage Examples
```css
/* Heading */
h1 {
font-family: var(--font-sans);
font-size: var(--text-4xl);
font-weight: var(--font-bold);
line-height: var(--leading-tight);
color: var(--color-gray-900);
}
/* Body */
p {
font-family: var(--font-sans);
font-size: var(--text-base);
font-weight: var(--font-normal);
line-height: var(--leading-normal);
color: var(--color-gray-700);
}
/* Code */
code {
font-family: var(--font-mono);
font-size: var(--text-sm);
background: var(--color-gray-100);
padding: 0.125em 0.25em;
border-radius: var(--radius-sm);
}
Type Scale Visualization
--text-6xl 60px ████████████████████████████████████
--text-5xl 48px ████████████████████████████
--text-4xl 36px █████████████████████
--text-3xl 30px ██████████████████
--text-2xl 24px ██████████████
--text-xl 20px ████████████
--text-lg 18px ███████████
--text-base 16px ██████████ (base)
--text-sm 14px ████████
--text-xs 12px ███████
---
### Spacing Token Documentation
```markdown
# Spacing Tokens
Our spacing scale uses a base of 4px with a 2x ratio for predictable increments.
## Scale
| Token | Value | Pixels | Use |
|-------|-------|--------|-----|
| `--spacing-px` | 1px | 1 | Borders, fine adjustments |
| `--spacing-0.5` | 0.125rem | 2 | Tight inline spacing |
| `--spacing-1` | 0.25rem | 4 | Icon gaps, compact UI |
| `--spacing-2` | 0.5rem | 8 | Button padding, list gaps |
| `--spacing-3` | 0.75rem | 12 | Card padding (sm) |
| `--spacing-4` | 1rem | 16 | Standard padding |
| `--spacing-5` | 1.25rem | 20 | Section gaps |
| `--spacing-6` | 1.5rem | 24 | Card padding (md) |
| `--spacing-8` | 2rem | 32 | Section padding |
| `--spacing-10` | 2.5rem | 40 | Large gaps |
| `--spacing-12` | 3rem | 48 | Section margins |
| `--spacing-16` | 4rem | 64 | Page sections |
| `--spacing-20` | 5rem | 80 | Hero spacing |
| `--spacing-24` | 6rem | 96 | Major sections |
## Named Aliases
For semantic usage, we provide named aliases:
| Alias | Maps To | Use |
|-------|---------|-----|
| `--spacing-xs` | --spacing-1 | Tight gaps |
| `--spacing-sm` | --spacing-2 | Small padding |
| `--spacing-md` | --spacing-4 | Default padding |
| `--spacing-lg` | --spacing-6 | Generous padding |
| `--spacing-xl` | --spacing-8 | Section spacing |
| `--spacing-2xl` | --spacing-12 | Large sections |
## Visualization
--spacing-1 ████ 4px
--spacing-2 ████████ 8px
--spacing-3 ████████████ 12px
--spacing-4 ████████████████ 16px (base)
--spacing-6 ████████████████████████ 24px
--spacing-8 ████████████████████████████████ 32px
--spacing-12 ████████████████████████████████████████████████ 48px
## Common Patterns
```css
/* Card */
.card {
padding: var(--spacing-6); /* 24px */
gap: var(--spacing-4); /* 16px between items */
}
/* Button */
.btn {
padding: var(--spacing-2) var(--spacing-4); /* 8px 16px */
gap: var(--spacing-2); /* 8px icon gap */
}
/* Stack */
.stack {
gap: var(--spacing-4); /* 16px between items */
}
/* Section */
.section {
padding: var(--spacing-16) 0; /* 64px vertical */
margin-bottom: var(--spacing-12); /* 48px between sections */
}
---
### Shadow Token Documentation
```markdown
# Shadow Tokens
Our elevation system uses layered shadows for realistic depth.
## Scale
| Token | Value | Use |
|-------|-------|-----|
| `--shadow-none` | none | Flat elements |
| `--shadow-xs` | 0 1px 2px 0 rgb(0 0 0 / 0.05) | Subtle lift |
| `--shadow-sm` | 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1) | Cards, buttons |
| `--shadow-md` | 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1) | Dropdowns |
| `--shadow-lg` | 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1) | Modals |
| `--shadow-xl` | 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1) | Popovers |
| `--shadow-2xl` | 0 25px 50px -12px rgb(0 0 0 / 0.25) | Dialogs |
## Visual Reference
┌─────────────────┐
│ shadow-none │ Flat
└─────────────────┘
┌─────────────────┐
│ shadow-xs │ ░ Barely raised
└─────────────────┘
┌─────────────────┐
│ shadow-sm │ ▒ Slight depth
└─────────────────┘
┌─────────────────┐
│ shadow-md │ ▓ Clear separation
└─────────────────┘
┌─────────────────┐
│ shadow-lg │ █ Floating
└─────────────────┘
## Component Mapping
| Component | Default Shadow | Hover Shadow |
|-----------|----------------|--------------|
| Card | sm | md |
| Button | none or xs | sm |
| Dropdown menu | md | - |
| Modal | lg | - |
| Tooltip | md | - |
| Toast | lg | - |
Auto-Generation Script
generate-docs.ts:
import fs from 'fs';
import path from 'path';
interface Token {
value: string;
type: string;
description?: string;
}
interface TokenGroup {
[key: string]: Token | TokenGroup;
}
function generateColorDocs(colors: TokenGroup): string {
let md = '# Color Tokens\n\n';
for (const [name, scale] of Object.entries(colors)) {
md += `## ${capitalize(name)}\n\n`;
md += '| Token | Value | Preview |\n';
md += '|-------|-------|--------|\n';
for (const [step, token] of Object.entries(scale as TokenGroup)) {
if (typeof token === 'object' && 'value' in token) {
md += `| \`--color-${name}-${step}\` | ${token.value} |  |\n`;
}
}
md += '\n';
}
return md;
}
function generateSpacingDocs(spacing: TokenGroup): string {
let md = '# Spacing Tokens\n\n';
md += '| Token | Value | Pixels |\n';
md += '|-------|-------|--------|\n';
for (const [name, token] of Object.entries(spacing)) {
if (typeof token === 'object' && 'value' in token) {
const px = parseFloat(token.value) * 16;
md += `| \`--spacing-${name}\` | ${token.value} | ${px}px |\n`;
}
}
return md;
}
function capitalize(s: string): string {
return s.charAt(0).toUpperCase() + s.slice(1);
}
const tokens = JSON.parse(fs.readFileSync('./tokens.json', 'utf-8'));
const colorDocs = generateColorDocs(tokens.color);
const spacingDocs = generateSpacingDocs(tokens.spacing);
fs.writeFileSync('./docs/colors.md', colorDocs);
fs.writeFileSync('./docs/spacing.md', spacingDocs);
console.log('Documentation generated!');
Best Practices
- Keep docs near code: Store docs alongside token files
- Auto-generate when possible: Reduce manual updates
- Include visuals: Swatches, scales, examples
- Show do/don't: Guide correct usage
- Add code examples: Copy-paste ready snippets
- Cross-reference: Link to components that use tokens
- Version control: Track changes with token updates
