Theme System

--background is the deepest layer — the page itself. --foreground is the color of all text by default.

Text must be readable on the page. White text on dark background = high contrast. This pair never changes because readability is non-negotiable.

--card is the actual rendered surface color per theme — solid white in light mode, subtle dark in dark mode. Just use bg-card. The variable handles the rest. --card-foreground is the text on cards.

Variables define the actual color, not a base to apply opacity to. This means components never need dark: prefixes — the variable changes when the theme class changes.

--popover is the background for floating elements. Currently matches --card. --popover-foreground is text on popovers.

Floating elements may need a different background than cards (e.g., darker in dark mode for more contrast). Separate variable allows this without affecting cards.

--secondary is a muted surface color for secondary actions. Less prominent than primary. --secondary-foreground is text on secondary surfaces.

Not every button should be primary. Secondary provides a toned-down alternative for less important actions (Cancel, Skip, etc.).

--accent is for decorative highlights — code syntax, category pills, subtle emphasis. Not for interactive elements. --accent-foreground is text on accent surfaces.

Separating accent from primary means decorative colors can change independently of interactive colors. A theme could use rose for accent but blue for primary.

--ring is the color for focus rings and active state indicators. Set to foreground color for maximum visibility.

Focus rings must be visible on any background. Using the foreground color ensures contrast. ring-accent is for decorative rings, ring is for accessibility.

--muted is stone-800 — slightly lighter than the page background. --muted-foreground is gray — dimmer than default text.

Not everything should be equally prominent. Muted creates visual hierarchy — secondary info (dates, labels, code blocks) recedes while primary content stands out.

--destructive is red — universally understood as danger. --destructive-foreground is near-white — text on red.

Red = danger is a universal convention. Changing it per theme would confuse users. If the theme is blue, destructive actions should still be red — not blue.

--border and --input define the color for borders and form controls. Use border-border or border-input.

Borders should be barely visible — they create structure without drawing attention. White at 10% opacity is subtle but visible on dark backgrounds.