Design Systems That Don’t Rot: Tokens, Theming, and Component Governance

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

1. Request: describe use-case + accessibility needs
2. Proposal: API + states + tokens used
3. Build: include tests and docs
4. Review: UX + engineering + accessibility
5. 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)