| name | design-system-documentation |
| description | Use when documenting a design system for cross-team use. Covers the documentation structure (Storybook, Notion, dedicated docs site), what to document, who reads it, and the maintenance cost.
|
Design System Documentation
A design system without documentation is a private joke between designers and the original engineers.
What to document
- Foundations — colors, type, spacing, motion (tokens)
- Components — every primitive + composition with usage examples
- Patterns — common screen patterns (login, dashboard, settings)
- Voice — copy guidelines, terminology
- Accessibility — baseline requirements + per-component notes
- Brand assets — logo, illustrations, photography rules
- Migration guides — old patterns → new patterns
Where to host
| Tool | Strengths | Cost |
|---|
| Storybook | Live component examples | Free, self-hosted |
| Zeroheight | Designer-friendly, Figma sync | $$/mo |
| Notion | Easy for non-designers | Free-$$ |
| Custom docs site | Full control | Dev time |
| Inside Figma (with prototypes) | Single source of truth | Free in Figma |
For most SaaS, Storybook + Notion is a great combination: Storybook for live components, Notion for narrative.
Per-component doc template
For each component:
- What it is (1 sentence)
- When to use it
- When NOT to use it
- Variants + props
- Live example
- Code snippet
- Accessibility notes
- Related components
Update cadence
- Major release → docs updated synchronously
- Minor release → docs within 1 sprint
- Component-level changes → docs updated in same PR
Don't merge code without doc updates.
Common mistakes
- Docs that drift from code (out of date within 6 months)
- Component docs without "when NOT to use"
- Docs that show variants but not patterns
- Storybook with 200 components but no narrative
- Documentation behind an SSO that blocks contractors
Where this fits in X3 Compass
X3 Compass is single-developer right now — doc-as-code in the repo (BRAND.md, design-skills repo). At team scale, would migrate to Storybook + Notion.
