Token Documentation Generator

When to Use

• Publishing token documentation on your design system site
• Onboarding new team members to the token system
• Creating a reference guide for designers and developers
• Documenting tokens for a Storybook or Mintlify site

The Prompt

Generate documentation for these design tokens. Target audience: designers and developers using the design system.

For each token (or token group), include:
1. **Name** — The full token name
2. **Value** — Resolved value (hex, px, rem, etc.)
3. **Description** — What it's for, in plain language
4. **Usage** — Where to use it, with a code example (CSS variable and Tailwind class if applicable)
5. **Do** — One correct usage example
6. **Don't** — One common mistake to avoid
7. **Aliases** — Any alternative names or deprecated names that point to this token

Group tokens by category (color, spacing, typography, elevation, etc.) and add a brief intro paragraph for each group explaining the design intent.

Output format: MDX (for use in documentation sites)

Here are the tokens:
[paste your token JSON or list]

Example Output

## Color Tokens

Color tokens define every color used in the UI. Always use semantic tokens
in your components. Never use primitive tokens (like `blue-500`) directly.

### Background

#### `color-bg-primary`
- **Value:** #FFFFFF (light) / #0F172A (dark)
- **Description:** The default page and card background.
- **Usage:**
  ```css
  background-color: var(--color-bg-primary);
  ```
- **Do:** Use for main content areas, cards, and modals.
- **Don't:** Don't use for interactive elements. Use `color-bg-interactive` instead.
- **Aliases:** Previously `bg-default` (deprecated in v2.0).

#### `color-bg-secondary`
- **Value:** #F8FAFC (light) / #1E293B (dark)
- **Description:** A subtle background for secondary surfaces.
- **Usage:**
  ```css
  background-color: var(--color-bg-secondary);
  ```
- **Do:** Use for sidebars, table row stripes, and code blocks.
- **Don't:** Don't use for hover states. Use `color-bg-interactive-hover` instead.

### Spacing

Spacing tokens use a 4px base grid. Use these for all padding, margin,
and gap values. Never use arbitrary pixel values.

#### `spacing-4`
- **Value:** 16px / 1rem
- **Description:** Standard component padding. The most commonly used spacing value.
- **Usage:**
  ```css
  padding: var(--spacing-4);
  ```
- **Do:** Use for card padding, form field spacing, and list item gaps.
- **Don't:** Don't use for page-level section spacing. Use `spacing-8` or larger.