Naming & tokens

The naming system is the contract that lets a designer in Figma and an engineer in CSS mean the same thing when they say “subtle border”. Tokens outlive components. Renames are expensive. This page fixes the three tiers, the single grammar every name follows, and the lint rules that keep the tiers honest.

The three tiers

Every token belongs to exactly one tier. A token may only reference a token at the tier directly above it – component asks semantic, semantic asks primitive, primitive holds a literal value. No skipping, no reaching back.

The dependency direction is fixed and one-way:

/* component  →  semantic  →  primitive */
--es-button-primary-bg:   var(--es-color-action-primary-default);
--es-color-action-primary-default: var(--es-color-teal-600);
--es-color-teal-600:      #06A0A9;

Mode swaps and re-skins happen in the middle layer. The button doesn’t know. The hex doesn’t move.

Token shape

Every name follows the same five-segment grammar, regardless of tier:

--es-<category>-<role>[-<variant>][-<state>]

Read left to right – category is the largest scope, state the smallest. Optional segments drop out when they aren’t needed. Never insert filler (“default”, “base”, “rest”).

Hyphens, not camelCase, because CSS custom properties are case-sensitive and editorial scanning treats hyphens as word breaks. The --es- prefix is non-negotiable – it’s how lint distinguishes our tokens from anyone else’s. The W3C DTCG type system underneath the CSS gives every token a declared $type (color, dimension, duration, cubicBezier, fontFamily, shadow), which is what lets the build emit CSS, JSON, iOS, and Android in lockstep.

Reserved vocabulary

A handful of words have one – and only one – meaning in this system. Casing across other systems is wild (“active” can mean pressed, selected, or current page); ours is locked.

A small but important rule: never use light or dark as a colour intent. Those words are reserved for mode (light mode, dark mode). A token called --es-color-bg-light is ambiguous in a system that ships both modes – it could mean “the light variant” or “the colour for light mode”. Use subtle / default / strong for weight, and surface-page / raised / sunken / muted for elevation.

Tier crossings

Three crossings are allowed. Two are forbidden. The lint rule below enforces both lists.

—es-button-primary-bg: var(—es-color-action-primary-default);

—es-color-action-primary-default: var(—es-color-teal-600);

—es-card-padding-lg: var(—es-space-6);

—es-button-primary-bg: var(—es-color-teal-600);

—es-field-border-focus: var(—es-button-primary-bg);

—es-color-action-primary-default: var(—es-button-primary-bg);

Lint rules

Three checks ride in CI. They turn the rules above from a doc into a contract – mechanical, regex-driven, fast.

1 – Token shape (Stylelint)

Every custom property must match the --es- prefix and the segment grammar. Stylelint’s built-in custom-property-pattern rule does the work; the regex below is what ships.

{
  "custom-property-pattern": [
    "^--es-[a-z]+(-[a-z0-9]+){1,4}$",
    {
      "message": "Token names follow --es-<category>-<role>[-<variant>][-<state>] (kebab-case, lowercase, --es- prefix)."
    }
  ]
}

Catches: --esButtonBg, --es_color_teal_600, --button-primary-bg (no prefix), --es-Color-Teal-600 (mixed case).

2 – Tier discipline (custom rule)

A token’s allowed referents depend on its tier. The custom rule classifies each token by its category prefix and walks the var() references in its value.

// scripts/lint-tier-discipline.js
const TIERS = {
  primitive: /^--es-(color-(teal|navy|mustard|orange|red|lavender|sage|sky|stone)-\d+|space-\d|radius-(none|xs|sm|md|lg|xl|pill|full)|duration-\w+|easing-\w+)$/,
  semantic:  /^--es-(color-(surface|text|border|action|feedback|editorial)-|spacing-(inline|stack|inset|section)-|radius-(control|card|surface|action|media|circular)$|elevation-|motion-)/,
  component: /^--es-(button|field|card|dialog|toast|nav|tab|chip|table|input)-/,
};

// Rule: a component token may not reference a primitive
//       when a matching semantic token exists.
//       A semantic token may never reference a component token.

Catches: --es-button-primary-bg: var(--es-color-teal-600) (skips semantic); --es-color-text-primary: var(--es-button-primary-bg) (semantic depends on component).

3 – Reserved vocabulary check

The state segment is drawn from a closed list. Any other word in that position fails the build.

// scripts/lint-reserved-vocab.js
const STATES = new Set([
  'hover', 'pressed', 'focus', 'selected', 'current',
  'disabled', 'readonly', 'error', 'loading',
]);

const FORBIDDEN_INTENT_WORDS = new Set([
  'light', 'dark',           // reserved for mode
  'active', 'inactive',       // ambiguous – use selected / current / disabled
  'normal', 'base', 'rest',   // filler – the absence of a state is the default
  'tiny', 'huge', 'jumbo',    // not in the size scale
]);

const REQUIRED_SIZE_VOCAB = new Set(['xs', 'sm', 'md', 'lg', 'xl']);

Catches: --es-button-primary-bg-active (use pressed or selected), --es-color-bg-light (reserved for mode), --es-card-padding-tiny (use xs).

Renaming and deprecation

Token names are public API. Semver applies.

The deprecation lane in CSS is just an alias plus a comment:

/* @deprecated since 1.4 – use --es-color-text-primary. Removal at 2.0. */
--es-text-ink: var(--es-color-text-primary);

Every deprecation lands in the changelog with the version it appeared in, the version it’ll be removed in, and the replacement token. No silent removals, ever.

Usage rules

tokens/color.tokens.json
   ↓ build
tokens/color.css
   ↓ consume
src/components/**/*.css

/* @deprecated since 1.4 – use --es-color-text-primary */
--es-text-ink: var(--es-color-text-primary);

Glossary

A short, alphabetised list of every reserved word and what it means in this system.