Role name
The string identifier for a role within a RoleSchemaInterface.roles[]. Every other engine surface (emitted CSS variables, contrast-pair foreground / background references, intent overrides) reaches a role by this exact string.
Shape
| Field | Type | Range |
|---|---|---|
name | string | non-empty, unique within roles[] |
What it does
- Becomes the suffix of the emitted CSS custom property:
--iridis-{name}: #rrggbb. - Is the value
contrastPairs[].foregroundandcontrastPairs[].backgroundreference. - Is the key downstream consumers (
derive:variant,expand:family, plugin emitters) use to look up the resolved record fromstate.roles[name].
What it means
A role name is semantic, not visual. accent, surface, text, link are role names because they say what the color is for. #7c3aed or violet are colors, not roles. Two schemas can both declare a role named accent and the engine will treat them as the same logical slot; the values they map to may differ, but the contract is identical.
How to author
- Use lowercase kebab-case (
text-subtle,syntax-keyword). Hyphens map cleanly into CSS variables. - Keep names short and stable. Renaming a role is a breaking change for every CSS consumer that read
--iridis-{old-name}. - Avoid encoding intent into the name (
primary-button-color) when anintentfield is available; names should describe the slot, intents describe the family.
Related
- Role schemas overview: full authoring guide.
- Role intent: orthogonal ontology hook attached to each role.