Variant System

Variants are named configurations of a component that override a defined subset of the component's token bindings. A variant MUST declare the complete set of properties it overrides — partial variant declarations are a Transform warning. Variants MUST NOT alter the component structure: the prop set, slot definitions, and state machine are identical across all variants of a component.

What Variants Control

• Token bindings — a variant may remap any component-tier token to a different semantic token reference.
• Default prop values — a variant may declare different defaults for optional props.
• Initial state — a variant may declare a different initial state if multiple initial states are declared in the state machine.

What Variants Cannot Control

• Prop structure — a variant cannot add, remove, or change the type of a prop.
• Slot structure — a variant cannot add or remove slots or change slot type declarations.
• State machine — a variant cannot add states, remove states, or alter legal transitions.
• Composition rules — a variant cannot relax or tighten composition rules relative to the base component.

Variant Naming

Variants are named by the dimension they vary and the value they represent: size.sm, size.lg, intent.primary, intent.ghost, hierarchy.primary, hierarchy.secondary. Variant names MUST be stable across component versions within a major version. Renaming a variant is a breaking change.