Skip to main content
skill CX Codex

design-system-documenter — Claude Code skill: setup & features

design-system-documenter converts raw token files into developer documentation featuring reference tables, implementation code, and WCAG contrast checks.

MIT 165 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a claude-code
Open on GitHub

What design-system-documenter does

The skill reads token data from tokens.json or CSS variable declarations. It categorizes colors, font definitions, spacing values, and shadows into distinct sections. For every entry, it outputs clean reference tables displaying values, explicit usage contexts, and accessibility contrast scores.

Generated documents include practical CSS snippets, anti-pattern guides, and prefers-reduced-motion blocks. You can export the output as standard Markdown for static site generators like VitePress and Docusaurus, as MDX with live components, or as Storybook documentation stories.

This tool cannot invent design tokens on its own. Without an existing token or stylesheet file in the workspace, it fails to produce meaningful guides.

What it helps with

  • convert raw tokens.json files into structured documentation
  • audit color contrast against WCAG AA and AAA thresholds
  • outline Do and Don't usage rules to prevent CSS misuse
  • export design token guides for Docusaurus, VitePress, or Storybook

Example prompts for the agent

  • Generate Markdown docs from our tokens.json with color contrast tables
  • Document our shadow and spacing tokens from variables.css including Do and Don't examples
  • Create an MDX token specification page with usage code for buttons and cards

How to install design-system-documenter

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill design-system-documenter -a claude-code

2Manually: put the files in place

~/.claude/skills/design-system-documenter/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-system-documenter/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about design-system-documenter

How do I install design-system-documenter in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill design-system-documenter -a claude-code.

What does design-system-documenter do?

It inspects token files or CSS variables to generate complete styleguide docs with reference tables, usage rules, and accessibility notes.

Can this skill create design tokens from scratch?

No, it only writes documentation for tokens that already exist. To generate tokens first, run the design-system-generator skill.

Source text

SKILL.md · MIT
---
name: design-system-documenter
description: Creates comprehensive documentation for design systems - token tables, usage guidelines, component examples, and accessibility notes. Use after generating tokens to create developer-friendly
  docs.
allowed-tools: Read,Write,Glob
metadata:
  category: Documentation
  pairs-with:
  - skill: design-system-generator
    reason: Document tokens after generation
  - skill: docs-architect
    reason: Integrate into broader documentation
  tags:
  - design-system
  - documentation
  - tokens
  - styleguide
---

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

```markdown
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

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

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

```markdown
---
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

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Design →

From the same set180

The whole set →
values-behavioral-interview The values-behavioral-interview skill for Claude Code helps prepare structured stories for values and behavioral interviews, including failures and follow-up questions. CX Codex +1 174installs interview-loop-strategist interview-loop-strategist builds an end-to-end interview preparation roadmap for senior ML and AI engineering roles at Anthropic and peer teams. It structures timelines, mock sessions, and project narratives. CX Codex +1 173installs interview-simulator interview-simulator — a skill for designing mock interview sessions with voice, whiteboard review, proctoring, and adaptive difficulty. Use it to plan the platform and session flow. CX Codex +1 169installs code-architecture code-architecture is a Claude Code skill for organizing code within a single application. It covers clean and hexagonal architecture, feature-based folders, dependency inversion, and module boundaries. CX Codex +1 169installs win31-audio-design win31-audio-design — a skill that builds Windows 3.1-style UI audio: 8-bit sounds, Web Audio API code, and haptic coordination for web and mobile apps. CX Codex +1 165installs human-centered-design-fundamentals The human-centered-design-fundamentals skill helps assess how people understand actions and system state in an interface. Use it to investigate user errors and make products easier to understand. CX Codex +1 161installs llm-router llm-router picks a model and provider for each task by complexity, budget, and quality needs. Cheap work goes to Haiku, hard problems to Sonnet or Opus. CX Codex +1 160installs systems-thinking systems-thinking is a Claude Code skill that maps stocks, flows, and feedback loops in complex systems. It kicks in for persistent problems or unintended effects of a policy or intervention. CX Codex +1 160installs

Project sponsors

Companies that keep this analytics open