tailwind-design-system

Use class-variance-authority (CVA) to define base styles plus variant and size options, then merge classes with a cn() utility combining clsx and tailwind-merge. Forward refs and extend VariantProps so consumers get type-safe props like variant="destructive" and size="lg".

Set darkMode: 'class' in tailwind.config.ts, define HSL CSS variables for semantic colors on :root and .dark selectors, and toggle the class on the document root. A ThemeProvider with localStorage persistence and prefers-color-scheme detection handles system, light, and dark modes.

Semantic tokens like primary or destructive map to CSS variables and express purpose, while utilities like blue-500 hardcode specific colors. Semantic tokens enable runtime theming and dark mode without changing component code, whereas hardcoded utilities require edits across the codebase.

Yes, the patterns target React and Next.js, including client components with 'use client' for the ThemeProvider. Form components integrate with React Hook Form and Zod resolvers, passing validation errors to Input components with aria-invalid and role="alert" messaging.

Arbitrary values bypass the design token system and break consistency, so extend the theme configuration instead. Nesting @apply hurts readability and duplicates utility logic; composing classes with CVA and cn() keeps variants explicit and type-safe.