22 lines
1.9 KiB
Markdown
22 lines
1.9 KiB
Markdown
# 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-<role>` 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.
|