Why design systems decay
They rot when:
- Teams ship “just this once” variants
- Tokens aren’t enforced
- No ownership or release process exists
- Components lack usage guidance
A durable system is 90% process, 10% components.
Start with tokens (not components)
Define tokens for:
- Color: semantic names like
--color-bg, --color-text, --color-accent
- Spacing:
--space-1 ... --space-6
- Typography: font sizes, line heights, weights
- Radius, shadow, border
:root { --color-bg: #ffffff; --color-text: #111111; --space-4: 1rem;}[data-theme="dark"] { --color-bg: #0b0b0c; --color-text: #f2f2f2;}
Theming: design for more than light/dark
Include:
- High contrast mode considerations
- Brand themes (if multi-tenant)
- Component states: hover, active, disabled, focus, error
Component governance (so people actually use it)
- Define component ownership (who approves changes).
- Version changes (even internally) with a changelog.
- Provide “do/don’t” usage examples in documentation.
A practical contribution workflow
- Request: describe use-case + accessibility needs
- Proposal: API + states + tokens used
- Build: include tests and docs
- Review: UX + engineering + accessibility
- Release: version + migration notes
Design system health checklist
- Tokens power spacing/color/typography consistently
- Components cover empty/loading/error states
- Docs show correct usage + anti-patterns
- Release process exists (even lightweight)
