Tailwind Design System
Tailwind is a tool, not a design system. Here's how I structure tokens, components, and constraints to build consistent UIs across large teams.
Tailwind Is Not a Design System
It's a vocabulary. A design system is the grammar. Without constraints, Tailwind gives every developer the freedom to make different decisions — and they will.
The Token Layer
Everything starts in tailwind.config.ts. Define your colors, spacing scale, typography, and border radii as named tokens. Never use raw values like text-[#3B82F6] in components — those are design debt.
Semantic Tokens Over Palette Tokens
Don't expose blue-500 to components. Expose brand-primary, text-muted, surface-elevated. When you rebrand or support dark mode, you change tokens — not components.
Component Patterns
I use class-variance-authority (CVA) for variant management. It keeps the variant logic in one place and makes TypeScript autocomplete actually useful for UI components.
Dark Mode Done Right
The class strategy, not media. Store the user's preference in localStorage, apply the class on the html element before first paint to avoid flash. Write both modes simultaneously — don't bolt dark mode on later.
Documenting the System
Storybook for components, a tokens page in Notion for designers. The bridge between them is a design token sync tool — Tokens Studio for Figma exports directly to your config file. It's the closest thing to a single source of truth I've found.
