Semantic Tokens

Semantic tokens assign purpose to primitive values. They are the primary reference layer for component tokens and the mechanism through which IDL achieves theme-ability. A semantic token does not hold a raw value — it maps a named purpose to a primitive token. When the theme changes, semantic token mappings are updated; component tokens, which reference only semantic tokens, are unchanged.

Semantic Token Naming

Semantic token names encode their purpose in their structure: category.role.variant. For example: color.text.primary, color.background.interactive, color.border.subtle. The category (color, spacing, radius) matches the primitive token category. The role (text, background, border) specifies the interface concern. The variant (primary, secondary, subtle, interactive) specifies the contextual use.

Theming via Semantic Tokens

A theme is a complete remapping of semantic tokens to different primitive values. A dark theme maps color.background.surface to a dark-family primitive instead of a light-family primitive. Because all components reference semantic tokens and never primitive tokens directly, the theme change propagates to all components without any component-level modification. The compiler validates theme completeness at Transform.

Required Semantic Token Coverage

A conformant IDL system MUST declare semantic tokens for all categories used in component declarations. A component that references a semantic token not declared in the active system token set is a Transform error. Semantic token sets for alternate themes MUST cover the same set of semantic token names as the default theme — missing tokens in an alternate theme are a Transform error.