Every growing product eventually faces the same problem: the UI becomes inconsistent. Buttons have four different sizes. Colors drift across pages. Every new feature reinvents basic patterns. A design system solves this — but only if it's built right.
Foundation: Design Tokens
Design tokens are the single source of truth for your visual language. We define them in Tailwind's config and they cascade everywhere:
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
brand: {
50: '#fff7ed',
500: '#ff7c02',
900: '#7c2d12',
},
},
spacing: {
'component-sm': '0.5rem',
'component-md': '1rem',
'component-lg': '1.5rem',
},
},
},
};
Component Architecture: CVA + Tailwind
We use class-variance-authority (CVA) to create type-safe component variants. This gives you the flexibility of Tailwind with the safety of TypeScript:
import { cva, type VariantProps } from 'class-variance-authority';
const button = cva('rounded-lg font-medium transition-colors', {
variants: {
intent: {
primary: 'bg-brand-500 text-white hover:bg-brand-600',
secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
ghost: 'bg-transparent hover:bg-gray-100',
},
size: {
sm: 'px-3 py-1.5 text-sm',
md: 'px-4 py-2 text-base',
lg: 'px-6 py-3 text-lg',
},
},
defaultVariants: { intent: 'primary', size: 'md' },
});
The Compound Component Pattern
For complex components (dropdowns, modals, data tables), we use compound components. They give consumers flexibility without exposing internal complexity. Think of how HTML's <select> and <option> work together — that's the pattern.
Documentation That Developers Actually Read
Every component gets a Storybook page with live examples, variant showcases, and copy-pasteable code snippets. If developers can't find or understand a component in 30 seconds, they'll build their own — and that defeats the purpose.
Adoption Strategy
The best design system is the one people actually use. We ensure adoption by:
- Making it easier to use a system component than to build custom
- ESLint rules that flag hardcoded colors and non-system spacing
- Migration scripts that convert legacy components automatically
- Regular "office hours" where the design system team helps other teams adopt
Ready to bring consistency to your product? Let's design your system together.