Naming Conventions
Semantic Naming
The --{element}-{qualifier} pattern for purpose-driven tokens.
Pattern
--{element}-{qualifier}
Semantic tokens describe what a value is for, not what it looks like. The element identifies the category; the qualifier narrows it to a specific role or intensity.
Elements
| Element | Purpose | Examples |
|---|---|---|
surface | Page and component backgrounds | --surface-background |
text | Text and icon colors | --text-primary, --text-secondary |
border | Borders and dividers | --border-default, --border-subtle |
type | Typography properties | --type-family-text, --type-size-heading-02 |
space | Spacing values | --space-sm, --space-md |
radius | Border radius values | --radius-sm, --radius-md |
size | Dimension values | --size-4, --size-8 |
action | Interactive element colors | --action-primary, --action-destructive |
Qualifiers
Qualifiers use role-based names that describe intensity or purpose:
| Qualifier type | Values | Used with |
|---|---|---|
| Hierarchy | primary, secondary, tertiary | text, action |
| Intensity | default, subtle, strong | border, surface |
| Role | background, overlay, accent | surface |
| Scale | sm, md, lg or numeric (4, 8, 16) | space, radius, size |
| Named | text, mono, heading-02, small | type |
Full Examples
--surface-background /* main page background */
--text-primary /* default body text */
--text-secondary /* de-emphasised text */
--border-default /* standard border */
--border-subtle /* lighter divider */
--type-family-text /* body font stack */
--type-family-mono /* code font stack */
--type-size-heading-02 /* second-level heading size */
--space-md /* medium spacing unit */
--radius-md /* medium corner radius */
--action-primary /* primary interactive color */Relationship to Primitives
Semantic tokens alias primitive tokens. The semantic name stays stable across themes; the underlying primitive value changes:
/* Light theme */
--text-primary: var(--colors-neutral-950);
/* Dark theme */
--text-primary: var(--colors-neutral-50);Components always consume semantic tokens, never primitives directly.