TL;DR

Tailwind v4 design tokens are CSS variables: keep the values that change between light and dark in :root and .dark, then map them to utilities with @theme inline, so bg-surface or text-muted-foreground follow the theme with no dark: prefix. A complete set names roles instead of colors: surfaces in the order they stack, text levels, tones split into a solid fill and a readable text color, plus radius, elevation, z-index and motion scales. Check every text and surface pair for 4.5:1 contrast in both themes with a script, because a color that passes on white often fails on a dark popover.

Tailwind CSS v4 moved configuration out of tailwind.config.js and into CSS, and many guides stop at the first step: put a few brand colors in @theme and call them tokens. A component library needs more than a palette.…