Overview
Design tokens
The complete token reference: 181 Figma variables and 13 text styles, and the mechanical rule that turns a Figma variable name into a CSS custom property.
The naming convention
One rule covers every token. Take the Figma variable path and replace each
/ with -. Collection prefixes are added only where the Figma
name would otherwise be ambiguous on its own.
| Figma collection | Figma variable | CSS custom property |
|---|---|---|
color-primitives | blue/300 | --color-blue-300 |
color-primitives | status/Orange | --color-status-orange |
text-primatives | fontSize/14 | --font-size-14 |
text-primatives | fontWeight/bold | --font-weight-bold |
spacing | spacing/16 | --spacing-16 |
spacing | radius/3 | --radius-3 |
semantics | button/primary/background | --button-primary-background |
semantics | input/error-caption | --input-error-caption |
Semantic tokens keep their path unprefixed because the path already reads as a
sentence: --table-cell-hover needs no --semantic- in front
of it. Primitives take a collection prefix because --blue-300 alone
invites exactly the layer violation the system is trying to prevent.
Known naming problems
Three names in the Figma file are misspelled or misleading. The CSS ships the corrected spelling as canonical and keeps the old one as a deprecated alias, so nothing breaks while they are fixed at source.
| Figma name | Problem | How the CSS handles it |
|---|---|---|
succes/text, succes/background, succes/border | “success” is missing an s | Canonical --success-*; --succes-* aliases to it. Rename in Figma, then delete the aliases. |
text-primatives | “primitives” is misspelled — collection name only, so no token is affected | No CSS impact. Rename the collection when convenient. |
yellow/100 = #7d3d02 | A dark brown sitting in the yellow ramp where a 100 step should be the lightest tint | Kept as-is so values match Figma, but it is the warning banner’s text colour, not a tint. Consider renaming to yellow/900 or brown/500. |
Toolip (component) | Component name is missing a t | Documented as “Tooltip”. Rename the Figma component. |
Prending Approval (Data Pill variant) | “Pending” is misspelled | Documented as “Pending approval”. |
Nuetral (Banner Alert variant) | “Neutral” is misspelled | Documented and classed as --neutral. |
Gaps in the semantic layer
Building the component CSS surfaced 21 roles with no semantic token. Each one is a place where a component could only be styled by reaching straight into a primitive — the exact layer violation the system forbids everywhere else.
Rather than leave those violations in the stylesheet, tokens.css defines
the missing aliases in a clearly marked proposed additions block, and every
component rule points at them. The values are the primitives the components were already
using, so adding these to Figma changes nothing visually — it just makes
the layering true. The result is that components.css contains zero
references to the primitive layer.
| Proposed token | Value | Why it is needed |
|---|---|---|
warning/text, warning/background, warning/border | yellow-100 / yellow-200 / yellow-300 | Error and success each have all three. Warning has none, so the Banner Alert’s warning variant had no semantic route at all. The most important gap on this list. |
neutral/background, neutral/border | gray-100 / gray-300 | The Banner Alert’s neutral variant. |
text/secondary | gray-500 | Secondary text outside a form field — page subheadings, the pagination ellipsis. input/caption exists but only makes sense inside an input. |
data-pill/* (5 tokens) | blue-100, brand, gray-100, gray-400, gray-500 | The Data Pill component has no semantic tokens whatsoever. |
dropzone/background, dropzone/border, dropzone/active-background | gray-100 / gray-400 / blue-100 | File Upload. |
suite-header/background, suite-header/text | blue-500 / white | The suite header is the only surface in the system built on blue/500. |
footer/text | gray-500 | Footer. |
tooltip/border | gray-300 | Tooltip’s optional stroke variant. tooltip/background and tooltip/text already exist — the border was simply missed. |
scrollbar/thumb-hover | gray-400 | Scrollbar. Track and thumb exist; the hover state does not. |
section-list/todo | gray-400 | Form Section List’s not-started state. |
submenu/background | gray-100 | Side Menu nested list fill. |
on-brand/text | white | Text on a brand-filled surface — the Skip Link, the customer-logo backing. |
Every value above is what the design already uses, so there is no visual change to review and no regression risk. What you gain is that a future re-theme — a brand colour change, a dark mode, a white-label deployment — becomes an edit to the semantics collection rather than a hunt through component styles. That is the entire reason the semantic layer exists, and right now it has 21 holes in it.
Primitives — color
27 raw values. Never consume these directly in component CSS.
| Token | Value | Aliased by |
|---|---|---|
--color-white | #ffffff | --button-primary-text, --input-background, --container-background, and 8 more |
--color-black | #111111 | --input-text, --container-text, --table-cell-text, --status-text-dark |
--color-blue-100 | #e1eaf8 | --button-secondary-hover-background, --menu-active |
--color-blue-200 | #44a3db | --focus-ring, --link-hover, --icon-accent-1 |
--color-blue-300 | #0076b6 | --primary-brand-color — the root of most of the system |
--color-blue-400 | #005c8e | --button-primary-hover-background |
--color-blue-500 | #253272 | --link-default |
--color-gray-100 | #f5f5f5 | --table-header-background, --input-disabled-background |
--color-gray-200 | #eeeeee | --disabled-background, --table-cell-border, --menu-hover, --scrollbar-track |
--color-gray-300 | #cccccc | --container-border, --tab-border, --menu-border, --pagination-border, --scrollbar-thumb, --tile-background |
--color-gray-400 | #888c8c | --disabled-text, --input-border |
--color-gray-500 | #5e5e5e | --input-caption, --divider-color, --tooltip-background, --toggle-off-background, --breadcrumb-separator |
--color-green-100 | #f8fdef | --success-background |
--color-green-500 | #285d35 | --success-text, --success-border |
--color-yellow-100 | #7d3d02 | Warning banner text (see naming problems above) |
--color-yellow-200 | #fff8d8 | Warning banner background |
--color-yellow-300 | #fbb829 | Warning banner border |
--color-yellow-400 | #ffe545 | Unaliased |
--color-red-100 | #ffe8e6 | --error-background, --input-error-background |
--color-red-500 | #b31200 | --error-text, --input-required, --input-error-caption |
The seven status/* primitives form a separate ramp used only by the
Status Pill. They are listed on the
Color page.
Primitives — type
One family, a 17-step size ramp, five line heights, two weights.
| Token | Value | Used by |
|---|---|---|
--font-family-primary | Lato | Everything |
--font-size-12 … --font-size-92 | 12, 14, 16, 18, 20, 24, 28, 32, 36, 42, 48, 54, 60, 68, 76, 84, 92 | Only 12 / 14 / 16 / 20 / 24 are used by shipped type styles; the rest are display sizes held in reserve |
--line-height-14 … --line-height-28 | 14, 16, 20, 24, 28 | Paired with sizes in the composite type tokens |
--font-weight-regular | 400 | Body, paragraph, captions, table text |
--font-weight-bold | 700 | Labels, headings, table headers |
Seventeen sizes exist in text-primatives; the 13 text styles use five
of them. The unused eleven (28px and up) are the display end of a formula documented
on the Figma typography page. Treat them as available but unblessed — introducing one
means adding a text style, not styling a one-off.
Primitives — spacing, radius, border
A 4pt grid, with 1 / 2 / 6 / 10 available for optical corrections and hairlines.
| Group | Steps | Guidance |
|---|---|---|
--spacing-* | 1, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48 | Prefer multiples of 4. --spacing-8 is the default gap between a label and its control. |
--radius-* | 2, 3, 4, 5, 8, 10, 12, 14, 20 | --radius-3 is the default control radius. --radius-20 is for pills only. |
--border-width-* | 1, 2, 3 | 1 = resting borders. 2 = focus rings and error borders. 3 = the active indicator on tabs, side menu and section lists. |
Composite type tokens
Each group maps to one Figma text style. Full specimens are on the Typography page.
| Type style | Size / line height / weight | Token group |
|---|---|---|
| Page Title | 24 / 28 / 700 | --type-page-title-* |
| Section Heading | 20 / 28 / 700 | --type-section-heading-* |
| Subheading | 16 / 20 / 400 | --type-subheading-* |
| Body | 14 / 16 / 400 | --type-body-* |
| Paragraph | 14 / 20 / 400 | --type-paragraph-* |
| Label | 14 / 16 / 700 | --type-label-* |
| Captions | 12 / 14 / 400 | --type-caption-* |
| Bulleted / Numbered List | 14 / 24 / 400 | --type-list-* |