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
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a claude-codeWhat 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.jsonfiles 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.jsonwith color contrast tables - Document our shadow and spacing tokens from
variables.cssincluding 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-code2Manually: put the files in place
~/.claude/skills/design-system-documenter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/design-system-documenter/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a codex2Manually: put the files in place
.agents/skills/design-system-documenter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a cursor2Manually: put the files in place
.cursor/skills/design-system-documenter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/design-system-documenter2Manually: put the files in place
.github/skills/design-system-documenter/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/design-system-documenterManually: put the files in place
.devin/skills/design-system-documenter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill design-system-documenter -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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