eq-design-system

Use a `.dark` class on the root element with `@custom-variant dark (&:is(.dark *))`, not a media query, so an in-app toggle can override the OS setting. Declare every themed token in both `:root` and `.dark`, set `color-scheme` in both blocks, and apply the class via a blocking inline script before first paint.

Run the audit script first for a census, then land a complete token file before converting anything. Convert by token rather than by file — sweep every literal that shares one meaning in a single commit — and ratchet the finding count with a baseline so it can only decrease.

In Tailwind v4 a custom property in `:root` generates no utility class by itself. The token needs a `--color-*` alias inside `@theme inline`; without it the class lands in the DOM but emits no CSS rule and fails silently.

Yes, the semantic token names are the shadcn/ui names verbatim, so generated components render correctly unedited. Renaming a token breaks every generated primitive silently, since the class and rule remain but the variable resolves to nothing.

For a web-only product, CSS custom properties as the single source avoid a build step with no second consumer. Adopt DTCG when a second consumer appears — a native app, Figma variable round-tripping, or a published component library; the four-layer shape maps onto it additively.

Swapping the brand ramp changes surfaces while foregrounds stay fixed, so pairs like `--primary-foreground` on `--primary` can drop below the 4.5:1 WCAG floor. The audit derives every `-foreground` pair and checks it in both themes, failing on any ratio under its floor.