tailwind-design-system

Use class-variance-authority (CVA) to define base styles plus variant and size options, then merge classes with a cn utility built on clsx and tailwind-merge. This gives type-safe props like variant="destructive" and size="lg" on a forwardRef component.

Define HSL CSS variables for light and dark themes under :root and .dark selectors, map them to semantic colors in tailwind.config.ts, and toggle the dark class on the document root via a ThemeProvider that respects system preferences and localStorage.

Semantic tokens like primary or destructive reference CSS variables and adapt to themes, while raw colors like blue-500 are fixed values. Using semantic tokens enables runtime theming and consistent dark mode without changing component code.

Yes, the patterns pair Tailwind styling with Radix primitives such as Dialog, using data-state attributes to drive enter and exit animations via tailwindcss-animate. Radix handles accessibility behavior while Tailwind classes control appearance.

Avoid arbitrary values like w-[347px] when the value belongs in the design system; extend the theme configuration instead so spacing and colors stay consistent. Arbitrary values are acceptable only for true one-off layout exceptions.