Why Every Growing Product Needs a Design System
The moment a product has more than two developers and more than one page, design inconsistency starts creeping in. One developer uses gap-4 for spacing, another uses space-x-3. One button uses rounded corners, another has square ones. Colors drift between shades of blue that are almost but not quite the same. A design system solves this by establishing a shared language between design and code, enforced at the component level. Tailwind CSS, with the right architecture, is an excellent foundation for that system.
Design Tokens in tailwind.config
Everything starts with the config file. Design tokens — your brand colors, typography scale, spacing units, border radii, shadows — should all live in tailwind.config.ts under the theme.extend key. Never use arbitrary values like text-[#1a3b5d] in production component code. If a color is used more than once, it belongs in the config.
// tailwind.config.ts
import type { Config } from 'tailwindcss';
export default {
content: ['./src/**/*.{ts,tsx}'],
theme: {
extend: {
colors: {
brand: {
50: '#eff6ff',
500: '#3b82f6',
900: '#1e3a8a',
},
surface: {
DEFAULT: '#ffffff',
muted: '#f8fafc',
},
},
fontFamily: {
sans: ['var(--font-inter)', 'system-ui', 'sans-serif'],
mono: ['var(--font-mono)', 'monospace'],
},
},
},
} satisfies Config;
Component Variants with CVA
Class Variance Authority (CVA) is the library that makes Tailwind-based component variants maintainable. Without it, variant logic lives in inline ternary expressions that grow unreadable fast. With CVA, each component's variants are declared declaratively and TypeScript-typed automatically.
// components/ui/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
{
variants: {
variant: {
primary: 'bg-brand-500 text-white hover:bg-brand-600',
secondary: 'bg-surface-muted text-gray-900 hover:bg-gray-100',
ghost: 'hover:bg-gray-100 text-gray-700',
destructive: 'bg-red-500 text-white hover:bg-red-600',
},
size: {
sm: 'h-8 px-3',
md: 'h-10 px-4',
lg: 'h-12 px-6 text-base',
},
},
defaultVariants: { variant: 'primary', size: 'md' },
}
);
export interface ButtonProps
extends React.ButtonHTMLAttributes,
VariantProps {}
export function Button({ variant, size, className, ...props }: ButtonProps) {
return ;
}
shadcn/ui Integration
shadcn/ui is not a component library you install — it is a collection of copy-paste components built on Radix UI primitives and styled with Tailwind. This distinction matters: you own the code, you can modify it freely, and it never blocks you because a library version has not been updated.
Initialize it with npx shadcn@latest init and add components individually with npx shadcn@latest add button. The generated components drop into your components/ui directory and immediately use your design tokens from tailwind.config.ts. I use shadcn as the starting point for every new design system and customize from there.
Dark Mode Setup
Configure Tailwind for class-based dark mode — not media-query-based — so users can toggle it manually.
// tailwind.config.ts
export default {
darkMode: 'class',
// ...
};
Add dark: variants to your design tokens. In the theme config, map surface colors to CSS custom properties that change based on the .dark class on the <html> element. Next.js's next-themes library handles the class toggling and avoids the flash of wrong theme on initial load by injecting a blocking script in _document.tsx.
Responsive Typography Scale
Avoid ad-hoc font sizes. Define a fluid type scale in tailwind.config.ts using CSS clamp for viewport-responsive sizing, or use a set of named size steps (text-body, text-heading-sm, text-heading-lg) that map to specific responsive values. The @tailwindcss/typography plugin handles prose content elegantly for blog post bodies and documentation pages.
Plugin Creation for Custom Utilities
When you find yourself repeating the same group of utilities across many components, extract them into a Tailwind plugin. A scrollbar-hide utility, a text-balance utility for headings, or a grid layout shorthand are all good candidates. Plugins defined in tailwind.config.ts are available everywhere in the project with full IntelliSense support.
Storybook Integration and Monorepo Sharing
Storybook documents your component library interactively. Install the Tailwind addon and point it at your config file so components render with the correct styles. Each CVA variant should have its own Storybook story, making visual regressions obvious during code review.
In a monorepo, extract the design system into a shared package — packages/ui — that exports components and the Tailwind config. Applications in the monorepo extend the shared config and import components directly. This ensures every product in your company uses the same design language with zero duplication.
A well-built design system is an investment that pays compound returns. Every new component built on the system is faster to build, more consistent, and easier to maintain than one built from scratch. That is the real value of getting the foundation right.