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:

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:

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

@media (prefers-reduced-motion: reduce) {

• { animation-duration: 0.01ms !important; }

}

5. Do/Don't Examples

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

Design System References

Real-world design systems from Component Gallery (95 systems, 2680 examples). Use for documentation best practices and pattern references.

Featured Design Systems

Enterprise-Grade

Accessibility-First

Modern/Tailwind-Native

Framework-Agnostic

Documentation Patterns

Elastic UI Documentation Structure

Best for: Enterprise systems, data-heavy components

Overview
├── Getting Started
├── Installation
├── Theming
└── Accessibility

Components
├── Layout
│   ├── Grid
│   ├── Flex
│   └── Spacer
├── Display
│   ├── Avatar
│   ├── Badge
│   └── Card
├── Forms
│   ├── Button
│   ├── Input
│   └── Select
└── Data Display
    ├── Table
    ├── List
    └── Tree

Patterns
├── Dashboard Layouts
├── Form Patterns
└── Data Loading

Utilities
├── Colors
├── Sizing
└── Animation

shadcn/ui Documentation Structure

Best for: Modern component libraries, developer-focused

Introduction
├── Installation
├── Configuration
├── Dark Mode
└── Typography

Components (alphabetical)
├── Accordion
├── Alert
├── Avatar
├── Badge
...
└── Tooltip

Themes
├── Default
├── New York
└── Creating Themes

Examples
├── Dashboard
├── Cards
├── Authentication
└── Forms

Award-Winning Sites for Reference

From Awwwards UI Design category (crawled 2026-01-31):

What Award-Winners Do Well

Typography

• Custom fonts or striking pairings
• Generous line-height for readability
• Scale contrast between headlines and body

Animation

• Scroll-driven reveals (not random movement)
• Micro-interactions on hover/focus
• Page transitions that feel intentional

Color

• Limited palettes (3-5 colors max)
• Strategic use of accent color
• Consistent application across states

Framer Template Categories

Template marketplace data for understanding market segments:

Popular Template Patterns

Business Templates

• Hero with CTA and social proof
• Feature grid (3-4 columns)
• Testimonial carousel
• Pricing table
• FAQ accordion
• Newsletter signup footer

Creative Templates

• Full-screen hero with video/animation
• Project grid (masonry or bento)
• About with team photos
• Process/timeline visualization
• Contact form

Documentation Best Practices

From Elastic UI

Do:

• Show component in all states (default, hover, focus, disabled, error)
• Include "When to use" and "When not to use" sections
• Provide copy-paste code snippets
• Document all props with types and defaults
• Show responsive behavior

Avoid:

• Documenting internal implementation details
• Showing every possible prop combination
• Using placeholder text that doesn't represent real usage

From shadcn/ui

Do:

• Lead with a visual example
• Show installation command prominently
• Include multiple usage examples
• Document customization via className/variants
• Link to related components

Avoid:

• Hiding the code behind tabs initially
• Over-explaining obvious props
• Documenting CSS classes instead of semantic usage

From Ariakit

Do:

• Lead with accessibility requirements
• Show keyboard navigation patterns
• Document ARIA attributes and their effects
• Include screen reader testing notes
• Provide focus management examples

Avoid:

• Assuming visual-only usage
• Ignoring reduced-motion preferences
• Using color alone to convey state

Component Gallery Statistics

Reference counts when documenting coverage:

Use these stats to:

• Prioritize documentation (high-count = common need)
• Reference established patterns (link to similar implementations)
• Identify gaps (low-count = opportunity for innovation)

Documentation Deliverables Checklist

When documenting a design system:

Tokens Documentation

• [ ] Color palette with hex values and usage
• [ ] Typography scale with font stacks
• [ ] Spacing scale with rem/px values
• [ ] Shadow definitions
• [ ] Border radius values
• [ ] Animation timing/easing
• [ ] Breakpoint definitions

Component Documentation

• [ ] Visual preview of all variants
• [ ] Props table with types
• [ ] Usage examples (code + preview)
• [ ] Accessibility notes
• [ ] Keyboard navigation
• [ ] Mobile considerations
• [ ] Related components

Pattern Documentation

• [ ] When to use pattern
• [ ] Layout requirements
• [ ] Component composition
• [ ] Responsive behavior
• [ ] Edge cases

Getting Started

• [ ] Installation (npm/yarn/pnpm)
• [ ] Configuration (tailwind.config, etc.)
• [ ] First component example
• [ ] Theming setup
• [ ] Dark mode setup

Documentation Templates

Docusaurus/VitePress Template

````markdown --- sidebar_position: 1 title: Design Tokens description: Complete design token reference for [Project Name] ---

import ColorSwatch from '@site/src/components/ColorSwatch';

Design Tokens

This page documents all design tokens generated from the [trend-name] design trend.

Installation

CSS Variables

@import 'path/to/tokens.css';

Tailwind

// tailwind.config.js
import tokens from './tokens/tailwind.config';
export default {
  theme: { extend: tokens.theme.extend }
};

Color Tokens

Primary Colors

[Continue for all color tokens...]

Typography Tokens

Font Families

Font Scale

Spacing Tokens

Spacing Scale

Shadow Tokens

Shadow Scale

Interactive Shadows

Border Tokens

Accessibility

Contrast Ratios

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

````

Storybook Template

// design-tokens.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';

const meta: Meta = {
  title: 'Design System/Tokens',
  parameters: {
    docs: {
      description: {
        component: 'Complete design token reference',
      },
    },
  },
};

export default meta;

export const Colors: StoryObj = {
  render: () => (
    <div className="token-grid">
      {Object.entries(colorTokens).map(([name, value]) => (
        <div key={name} className="token-item">
          <div
            className="color-swatch"
            style={{ backgroundColor: value }}
          />
          <code>{name}</code>
          <span>{value}</span>
        </div>
      ))}
    </div>
  ),
};

export const Typography: StoryObj = {
  render: () => (
    <div className="type-scale">
      {fontSizes.map(({ name, value }) => (
        <p key={name} style={{ fontSize: value }}>
          {name}: The quick brown fox
        </p>
      ))}
    </div>
  ),
};

export const Shadows: StoryObj = {
  render: () => (
    <div className="shadow-grid">
      {shadows.map(({ name, value }) => (
        <div key={name} className="shadow-item" style={{ boxShadow: value }}>
          {name}
        </div>
      ))}
    </div>
  ),
};

README Template

````markdown

[Project] Design System

Design tokens generated from [trend-name] design trend.

Quick Start

npm install @project/tokens

CSS

@import '@project/tokens/css';

.my-component {
  color: var(--color-primary);
  font-family: var(--font-body);
  padding: var(--spacing-4);
}

Tailwind

// tailwind.config.js
const tokens = require('@project/tokens/tailwind');

module.exports = {
  theme: {
    extend: tokens.theme.extend,
  },
};

JavaScript/TypeScript

import { colors, typography } from '@project/tokens';

const styles = {
  color: colors.primary,
  fontFamily: typography.body,
};

Token Categories

• Colors: 12 semantic color tokens
• Typography: 2 font families, 8 size scales
• Spacing: 15-point spacing scale
• Shadows: 5 elevation levels
• Borders: Width, color, and radius tokens

Documentation

Full documentation: [link to docs site]

License

MIT ````