Naming

Token names should describe the role of a value, not its current decoration. Prefer names that can survive a visual redesign.

Rules#

• Use semantic names when a value expresses purpose: color.accent is better than color.orange.
• Use scale names when a value belongs to an ordered system: space.s-m and step.2 describe position in a scale.
• Avoid one-off tokens unless they represent a reusable decision that will appear in more than one component or layout.
• Move from general to specific: category first, then role or scale position.
• Preserve generated CSS names when activation would otherwise break existing components.

Current convention#

Source tokens use dotted paths in tokens/core.tokens.json: color.accent, font.serif, space.s-m. Style Dictionary turns those paths into CSS custom properties such as --color-accent, --font-serif, and --space-s-m.

Negative type steps intentionally become double-hyphen CSS names: step.-1 generates --step--1, matching the manual CSS variables already used by the site.

What not to do#

Do not name a token after one page, one component experiment, or one literal colour unless the literal value is the decision. If a value can change while the purpose remains stable, name the purpose.