Understand theme tokens

A shadcn theme maps semantic names such as background, foreground, primary, muted, destructive, border, and ring to CSS values.

Components consume the semantic tokens, so changing a token can update many surfaces consistently. Judge a theme as a system: foreground against background, text on primary, muted text readability, destructive actions, focus rings, and borders all need sufficient contrast.

Think in token pairs, not isolated colors. primary needs a readable primary-foreground; destructive needs its own foreground; popovers and cards need compatible surfaces and borders. A brand blue that works as a large background may fail as small text or a focus ring.

Semantic names also protect intent. Product code should request a muted surface or destructive action instead of knowing the raw brand palette. Change the token when the meaning changes everywhere; add a new semantic token when two meanings have genuinely diverged. One-off utility overrides make dark mode and future redesigns harder to reason about.

Radius, spacing, and typography participate in the same system even when represented differently. Review normal, hover, focus, active, disabled, selected, and error states rather than approving a static palette screenshot.

Create a restrained theme and place Button, Card, Input, selected control, disabled control, error message, and focus ring on one audit screen. Trace every visible value to a semantic token and test contrast plus forced-colors behavior.