Glossaries & tokens

A glossary is the shared vocabulary your contracts draw on. Rather than scattering raw values across components, you define them once — as colour, spacing, type and motion entries — and reference them everywhere. Glossaries are what let a contract describe a component without ever hard-coding a hex colour or a pixel measurement.

Glossaries as vocabulary

Every value a contract needs lives in a glossary entry, and every clause points at one of those entries by name. This gives you one place to define a value and one place to change it.

The benefit compounds across a product:

A value is defined once and reused by every contract that references it.
A change to an entry flows through every clause automatically — there is nothing to find and replace.
Surfaces that use a value not matching its entry are flagged as drift during an audit.

Glossaries live within a design system, so each design system carries its own coherent vocabulary.

Division-scale presets

Dimensional and type scales are generated from a single base using division-scale presets. You pick a base — 6, 8 or 10 — and parlance derives a consistent set of steps from it.

This keeps spacing and type mathematically related rather than arbitrary. Choosing a base of 8, for example, produces a scale built around eights, so every step relates cleanly to the others and to the rest of the system. The same approach generates both your dimensional (spacing) scale and your type scale, so the two stay in proportion.

Generating colour ramps

For colour, parlance generates full 50–950 ramps in the OKLCH colour space. From a base colour, it produces an evenly stepped ramp — from the lightest tint at 50 through to the darkest shade at 950 — with perceptually uniform steps.

Because the ramps are built with accessibility in mind, contrast is evaluated against WCAG 2.2 as the ramp is generated. Working in OKLCH means lightness behaves predictably, so the steps read as an even progression and contrast relationships hold across the ramp.

Semantic roles and the Theme editor

Raw ramps are powerful, but contracts reference semantic roles — names that describe intent, such as a surface, a foreground or an accent — rather than a specific step on a ramp. Semantic roles are where light and dark become first-class.

In the Theme editor you map each semantic role to a value for light and a value for dark. Both modes are defined together; neither is an afterthought. As you assign roles, parlance shows live contrast for the pairings that matter — foreground against background, for instance — and reports the result against WCAG 2.2 at both AA and AAA, in light and in dark.

This means an accessible result is something you design in, not something you discover later. A role that fails contrast in dark mode is visible the moment you set it. See accessibility for how these checks carry through into audits.

How clauses reference glossary values

The whole system comes together at the clause. When you add a clause to a contract, you choose a glossary entry for its value rather than typing a literal:

A colour clause points at a semantic role, which resolves to the correct value in light and dark.
A spacing clause points at a step on your division-scale dimensional scale.
A type clause points at a type entry from your type scale.
A motion clause points at a motion entry such as a duration or easing.

Because the reference is to the entry and not a copied value, the contract stays correct when the glossary changes — and any surface that disagrees with the referenced entry is reported as drift. This is what lets a contract serve as the single source of truth audited across design, code, live and native surfaces.

Next steps

UI contracts — how clauses reference these values.
Accessibility — contrast, AA/AAA and equal light and dark.
Quickstart — set up a glossary and generate your first ramp.