Creating a Design System with Tailwind CSS v4 and shadcn/ui

Start With Tokens

Tokens make the system flexible. Use variables for background, foreground, border, primary, muted, destructive, radius, and shadow. Then components can adapt to light and dark themes without duplicating classes everywhere.

Tailwind works well for this because utility classes can reference those variables while still keeping markup readable.

Choose Radius And Shadow Rules Early

Inconsistent radius and shadow are easy to notice. Decide what cards, buttons, panels, and modals should use. Keep repeated item cards restrained and avoid stacking cards inside cards.

A cleaner system usually feels more premium than one with heavy shadows and exaggerated corners.

Build Component States Into The Preview

A button page should show size, variant, disabled, icon-only, and loading states. A table page should show sorting, empty rows, and status indicators. This makes the library useful for real product work.

Document Integration Assumptions

Every copyable component should make dependencies clear: React, TypeScript, Tailwind, icons, Radix primitives, or local utilities. This reduces confusion and support requests.