Theme Documentation and Design Tokens
You'll learn how to document and organize your theme variables so your entire team can use them consistently and maintain them effortlessly.
Why Documentation Matters
You've built a beautiful system of custom properties for colors, spacing, and typography. But if no one knows what --color-brand-300 means or when to use --space-lg vs --space-xl, your carefully crafted tokens become a guessing game. Design tokens are your theme's vocabulary—and like any language, they need a clear dictionary.
Establishing Naming Conventions
Consistent naming creates predictability. Your team shouldn't wonder whether it's --color-primary-dark or --primary-color-darker. Common patterns:
- Category-first:
--color-brand-500,--space-md,--font-heading-xl - Semantic naming:
--color-text-primary,--color-surface-elevated - Scale clarity: Use numbers (100-900) or T-shirt sizes (xs, sm, md, lg, xl)
Pick one pattern and stick with it across your entire system.
Documentation Practices
Create a living reference that shows:
- Token name and its CSS variable
- Actual value (hex codes, pixel values)
- Usage guidelines: "Use
--color-brand-primaryfor primary CTAs and key actions" - Visual examples: Show the color swatch or spacing demonstration
- Relationships: "In dark mode, this becomes
--color-brand-primary-dark"
Many teams maintain this in Storybook, a dedicated style guide page, or even comments in their CSS:
/* --color-brand-primary: #3B82F6
* Use for primary buttons, links, and focus states
* Dark mode variant: --color-brand-primary-dark
*/
:root {
--color-brand-primary: #3B82F6;
}
Key Takeaway: Well-documented design tokens with clear naming conventions transform your theme from a collection of variables into a maintainable design system that any team member can confidently use.