Design systems in production
What I learned shipping a token-driven design system that designers and engineers both actually use.
A design system only earns its keep when it survives contact with production code. Here is what worked when bridging Figma tokens and shadcn-style components on a real portfolio.
Start with constraints, not components
Before adding another button variant, define the non-negotiables:
- Color roles that map to CSS variables, not hex values in components
- Typography scales that work in both marketing pages and dense tools
- Radius and spacing presets that survive theme switching
The goal is not a component catalog. It is a shared language that reduces decision fatigue.
Make the happy path the default path
Engineers will reach for className="text-sm text-muted-foreground" hundreds of times. If that pattern is already encoded in your primitives, you win by default.
- Document tokens in a live design-system route
- Mirror every primitive with a demo
- Ship theme customization only after base tokens are stable
Measure adoption, not completeness
Track what matters:
- How often teams import shared primitives vs. one-off styles
- Time to implement a new page section
- Bug count tied to inconsistent spacing or color usage
When adoption stalls, the fix is usually documentation and examples, not more components.
Published as part of the portfolio design-system work — explore the live docs at .