Principles

Semantic tokens over raw values

Components ask for a role, not a colour. bg-primary means "the strongest fill", and theme.css decides that is Radix gray-12 in light mode. That is what lets dark mode, and anyone else's palette, work without touching component code.

Inherit type, don't own it

The site sets its typeface on body. Components set sizes and weights (text-sm, font-medium) and nothing else, so they look native wherever they're dropped. The one exception is Kbd, which uses font-mono because a keycap should read as a key.

Subtract, don't adapt

On small screens I remove things rather than translate them. A tooltip that explains a shortcut has nothing to offer a phone, so it goes. What remains still gets touch treatment: 16px inputs so iOS doesn't zoom, taller menu items below md, and touch-target on isolated small controls.

The source is the documentation

This registry copies source, so the source has to explain itself. button.tsx says why hit-area expansion is opt-in; switch.tsx says why the track uses foreground and background instead of --input; theme.css says why destructive skips Radix step 9. These pages summarise those comments; when they disagree, the code is right and this page is stale.

Honest about gaps

Some components still carry stock shadcn classes I haven't reconciled, such as dark: opacity tweaks and two different focus ring weights. I'd rather list those than hide them.