Color Semantics

Color in IDL is semantic, not literal. Raw hex values are not permissible in component declarations or component-tier token definitions. Every color reference in a component MUST resolve to a named semantic color token. This constraint enables theme-ability, platform-appropriate color translation, and contrast-mode adaptation without modifying component declarations.

Color Token Tiers

Color tokens follow the three-tier hierarchy: Primitive tokens declare raw color values (e.g., color.blue.500 = #3B82F6). Semantic tokens assign purpose to primitive colors (e.g., color.text.interactive → color.blue.500). Component tokens scope semantic colors to a specific component (e.g., button.text.default → color.text.interactive). Components reference only component-tier color tokens.

Required Semantic Color Categories

• color.background.* — surface and container backgrounds.
• color.text.* — foreground text and icon colors.
• color.border.* — stroke and divider colors.
• color.interactive.* — interactive element states (default, hover, pressed, disabled).
• color.status.* — feedback states (success, warning, error, info).
• color.overlay.* — scrim, backdrop, and shadow colors.

Theme-Ability

Because components reference only semantic tokens, themes are implemented by re-mapping semantic tokens to different primitive values — the component declarations are unchanged. A dark theme remaps color.background.surface from a light primitive to a dark primitive. Every component that references that semantic token adopts the new value at compile time without modification.