wealth/docs/decisions/0003-semantic-tokens-only-i...

1.9 KiB

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.