Design System Documentation Template

Most systems need four: Primary (main action), Secondary (supporting action), Tertiary/Ghost (low-emphasis), and Destructive (delete/remove). Some add a Link variant (looks like a link, behaves like a button). Avoid creating variants for every color in your palette. If you need more than 5 variants, you are likely solving a hierarchy problem that should be addressed through layout, not button styling.

Document the design spec as "Draft" status so the team knows the intended behavior. Update to "Beta" when the first implementation ships and "Stable" after it has been used across 3+ features without breaking changes. This gives engineers a target to build toward and avoids implementing something that has not been thought through.

Use semantic versioning. Patch (1.0.1) for bug fixes and minor visual tweaks. Minor (1.1.0) for new variants or non-breaking additions. Major (2.0.0) for breaking changes that require consumer updates. Document breaking changes in a changelog. Provide a migration guide for major versions. Learn more about structured versioning in the [glossary entry on release management](/glossary/release-management).

Assign a component owner (one designer, one engineer) listed in the Component Overview. They update the doc when the component changes. Review documentation quarterly as part of a design system health check. Stale documentation is worse than no documentation because it teaches the wrong patterns.

Common stacks: Storybook + MDX for interactive code docs, Figma for visual specs, Notion or Confluence for usage guidelines. The best setup consolidates code examples and usage guidelines in one place. Storybook with the Docs addon achieves this for React/Vue/Angular component libraries. ---