# 0003 Semantic tokens only in the Tailwind theme Status: Proposed · Area: design · Date: 2026-10-04 · Decided by: agent ## Context The Lumina Design System (tokens.json v5) defines primitives (indigo, saffron, slate, green, red, amber) and semantic roles (`surface`, `text-primary`, `action-primary`, `premium`, status shades). If primitives become utilities, components can bypass the roles and theming breaks. ## Decision - In island `styles/theme.css`, keep three layers: primitives (`--indigo-600`) and semantic variables (`--surface`, `--text-primary`) as plain `:root` custom properties, and utilities only in `@theme inline`, each mapping `--color-` to its semantic variable. - Put the scales in `@theme`: type (`--text-body-md`), radii (`--radius-md`), shadows (`--shadow-1` to `--shadow-3`), spacing, containers, and the `desktop` and `wide` breakpoints. - Name every semantic token exactly as the design system does. Remove Tailwind's default palette, fonts, type scale, radii, shadows, breakpoints, and containers (`--color-*: initial` and so on), so only Lumina tokens produce utilities. - A value the design system uses that has no token gets a semantic token first, with a comment saying so; raw hex values never appear in components. ## Alternatives - Primitives in `@theme` too: they become utilities (`bg-indigo-600`) and leak into components. - Semantic values written straight into `@theme`: a theme can't switch them under its own selector. ## Consequences - Utilities read as `bg-surface`, `text-text-primary`, `border-border-subtle`, `text-body-md`, `desktop:`; `bg-white`, `text-sm`, and `md:` don't exist. - A theme overrides only the semantic `:root` block under its own selector. Shadows built from roles (`--shadow-focus-ring`, `--shadow-focus-field`) sit in `@theme inline`, so they follow the theme. - Added beyond the design system: `--action-primary-pressed`, because the design system paints pressed states from primitives.