Intent
Color roles are semantic, not component-specific. Components must use Layer 2 --hui-color-* aliases so an upstream design system can replace the palette without changing component CSS.
Roles
| Role | Token | Use |
|---|---|---|
| Text | --hui-color-text | Primary readable content and labels. |
| Muted text | --hui-color-text-muted | Supporting copy and less prominent metadata. |
| Background | --hui-color-background | Page/control background. |
| Raised background | --hui-color-background-raised | Cards, grouped surfaces, and elevated regions. |
| Link | --hui-color-link | Non-button links in their default state. |
| Link hover/active | --hui-color-link-hover, --hui-color-link-active | Pointer and pressed link states. |
| Border | --hui-color-border | Neutral borders and separators. |
| Backdrop | --hui-color-backdrop | Modal scrim; defaults to the foreground color at 50% alpha. |
| Focus ring | --hui-color-focus-ring | Keyboard focus indicator. Never remove focus without an equivalent. |
| Interactive | --hui-color-interactive | Primary controls and selected indicators. |
| Interactive hover/active | --hui-color-interactive-hover, --hui-color-interactive-active | Pointer and pressed control states. |
| Interactive disabled | --hui-color-interactive-disabled | Disabled control foreground or indicator. |
| Interactive contrast | --hui-color-interactive-contrast | Content placed on the interactive color. |
| Danger | --hui-color-danger | Invalid, destructive, or indeterminate messaging. |
| Disabled background | --hui-color-disabled-background | Disabled control surfaces. |
Accessibility rules
- Maintain readable contrast for text and meaningful UI graphics.
- Do not communicate state by color alone; preserve the component's state, text, or native semantics.
- Focus must remain visible for keyboard users.
- Use
--hui-color-dangeronly for error or warning meaning, not as a decorative accent.
Upstream mapping
The Layer 1 palette is in tokens/base.tokens.json under ds.color.* and is emitted as --ds-color-*. Layer 2 aliases include a fallback literal, for example --hui-color-text: var(--ds-color-foreground, #0b0f14).
Optional Themes And Derived Colors
The default palette is unchanged. Set data-hui-theme="light", "dark", or "system" on the document element to opt into theme-aware semantic aliases and native color-scheme. System mode uses light-dark() with a dark-preference fallback. Dark primitives live under ds.color-dark.*; consumers may override them at the same upstream integration boundary. --hui-color-interactive-soft mixes the interactive and surface roles in Oklab. --hui-color-interactive-translucent uses relative RGB alpha where supported, with a color-mix() fallback. Both aliases have matching Tailwind color utilities. data-hui-contrast="auto" optionally enables contrast-color() for the interactive foreground. Explicit contrast pairs remain the default, and palette overrides still require contrast testing; automatic black/white selection is not a general accessibility guarantee.