Case study · Design system · Part 1: Taxonomy

One name for every token.

Our design tokens lived in three places: Figma, CSS and JSON. Each had its own naming rules and was maintained by hand, so they slowly drifted apart. I defined a single naming grammar. Now every token has one logical name, and the Figma path, the CSS property and the JSON key all follow from it mechanically.

Role: Senior UX/UI Designer
Company: Bit2win · enterprise B2B SaaS
Timeline: September 2026 · migration ongoing
Scope: 438 Figma variables · 3 sources of truth
Tools: Figma variables, CSS, JSON

Three sources of truth, three grammars

The same token existed in Figma, in the CSS files and in the JSON exported for code. Each source spelled it differently, and nothing kept them in sync except people.

CSSkebab-case--color-background-accent-primary-hover

Figmapath with “/”COLOR/Accent/Primary accent/Hover/background

JSONkeys with “.”COLOR.Accent.Primary accent.Hover.background

What the drift looked like

Wrong valueThe link colour pointed to brand-500 in CSS and to secondary-600 in Figma. Designers and developers were shipping different blues.
Typocolore-border-selected lived on as a real token name. Developers read these names and generate code from them.
MissingTwo surface tokens existed in Figma but had no counterpart in code.
HabitsState in the middle of the name, mixed upper and lower case, palette names inside semantic tokens, and components inventing their own tokens even when they didn’t need them.

The decision: a grammar with five axes

Instead of fixing names one by one, I proposed a grammar. Every token is described by the same five segments, always in the same order. Once the grammar exists, naming stops being a matter of taste and becomes something a reviewer can check.

tier.category.role.property.state

Tiersemanticcore · semantic · component

Categorycolorcolor · typography · spacing · border · elevation · motion

Roleprimaryprimary · secondary · neutral · destructive · alert

Propertybackgroundbackground · text · border · foreground

Statehoverdefault · hover · active · focus · disabled · selected

In code the tier is usually implied by the file a token lives in, so the semantic token above reads --color-primary-background-hover.

Fig. 1 · The classification

Classified like a species. Each axis narrows the choice, from the broadest to the most specific. One path from top to bottom gives exactly one name, and the same path always gives the same name.

Seven problems, seven rules

Each rule in the grammar exists because of a problem we actually had. This is the part I’d point to in a review: not the names themselves, but the reason behind each one.

ProblemRuleWhat it changes

The state sat in the middle of the name

…accent-primary-hover in CSS, …/Hover/background in Figma.

Rule

The state is always the last segment, and appears once.

All states of one element sort together, and a developer can find the hover variant without guessing.

Mixed case everywhere

COLOR, Accent, SIZING & SPACING.

Rule

Every segment is lowercase. No exceptions.

Names translate to code without manual fixes. All 438 Figma variables have already been converted.

Palette names inside semantic tokens

A semantic token called brand tied a role back to a raw colour.

Rule

Semantic roles describe meaning: primary, not brand; destructive, not negative-500.

If the primary colour moves to another palette, no semantic name has to change.

Every component made its own tokens

The system grew without anyone deciding it should.

Rule

A component token exists only when the component diverges from the semantic value.

The system stays small. Each component token now signals a deliberate exception.

One variable, two jobs

The same variable was used for a fill and for a stroke.

Rule

One name per property: …background… and …border… are separate tokens, even if they alias the same value.

Fill and stroke can change independently later without a rename.

Three sources maintained by hand

Figma, CSS and JSON each needed their own update.

Rule

One logical name. The three formats are derived from it mechanically.

Figma’s code syntax is set to var(--token), so Dev Mode shows the exact CSS name.

Renaming could break every component

Deleting a variable and creating a new one detaches every instance that used it.

Rule

Rename, never recreate. The variable keeps its ID.

The migration runs on a live library without breaking a single component.

One name, three formats

The translation is a rule, not a judgement call. Anyone on the team can produce the CSS or JSON name from the Figma path, and a script could do it too.

Fig. 2 · Before and after

The fix wasn’t correcting three files. It was to stop editing three files. The name is decided once; only the separators change between formats.

Format	Rule	Example
Figma variable	Segments separated by “/”	`color/interactive/primary/background/hover`
CSS custom property	Kebab-case with a “--” prefix	`--color-interactive-primary-background-hover`
JSON (Tokens Studio)	Segments separated by “.”	`color.interactive.primary.background.hover`

Tokens live in their own files (core-tokens.css, semantic-tokens.css, component-tokens.css), never inside the components. Component classes stay as they are. The class says what to style; the token says with which value.

Three tiers, one chain of references

Fig. 3 · What lives in core

Core is the raw material. Every value the product can use lives here exactly once, organised as scales. A core token doesn’t know about buttons or errors; it only knows it is the 600 of the brand blue, or the small radius. Meaning is added one level up.

Fig. 4 · From core to semantic

The core palette has no opinions; the semantic layer does. Each semantic token points to exactly one core value, and several roles can share the same one, like both disabled backgrounds. To restyle a role you change where it points, never its name.

Fig. 5 · Three tiers in practice

Read it right to left. The button in hover uses the semantic colour as it is, so it points straight to the semantic token. The selected badge needs a softer colour, so it earns a component token. Every component token is a deliberate exception.

No new token

Primary button, hover

It uses exactly the semantic colour, so it references the semantic token directly.

.button--primary:hover {
  background: var(--color-interactive-primary-background-hover);
}

Component token

Badge, selected

It needs a softer colour than the semantic default. It diverges, so it earns its own token.

.badge[data-state="selected"] {
  background: var(--badge-background-selected);
}

Before and after: the checkbox

The checkbox was the first component we migrated. Its six variables show almost every problem in one place.

Fig. 6 · Anatomy of the checkbox

Every visible part, one token. Fill and border used to share a single variable; now each has its own name. Radius and border width are scale values, so they live in core.

#	Before		After (Figma path)	Tier
1	`color/accent/secondary/default/default` (fill)	→	`color/secondary/background/default`	semantic
1b	same variable, used as stroke	→	`color/secondary/border/default`	semantic
2	`color/accent/secondary/default/icon`	→	`color/secondary/foreground/default`	semantic
3	`color/accent/disable state/disabled/disabled`	→	`color/secondary/background/disabled`	semantic
4	`color/surface/default`	→	`color/neutral/background/default`	semantic
5	`borders & radius/radius-extrasmall`	→	`core/border/radius/extrasmall`	core (was semantic)
6	`sizing & spacing/border size/border-size-medium`	→	`core/border/size/medium`	core

Rows 1 and 1bOne variable used for two properties becomes two names.

Row 3“Disable state” isn’t a role, and “disabled” appeared twice.

Row 4The role was missing. It becomes neutral.

Row 5A scale value sat in the wrong tier and moves to core.

Where it stands

3 → 1

sources of truth for design and code

438

Figma variables converted to the new grammar

30+

components migrating, one audit at a time

DoneGrammar agreed with the team.
DoneCSS translation defined: separate token files and code syntax in Figma.
DoneAll 438 variables in the main library converted to lowercase.
DoneThe interactive colour category already follows the new grammar in JSON.
In progressComponent-by-component migration, driven by audits (checkbox, badge, tab, accordion…). Each audit lists which tokens still break the grammar.

Still open, on purpose

Whether an 8px “panel” box pattern is its own level, or belongs case by case in the component tier.
Whether surfaces with no padding need a fifth pattern level.
Confirming the neutral role and the fill/stroke split for the checkbox.

What I took from it

A design system doesn’t break in its components. It breaks in its names, long before anyone notices.

Other work

Senior UX/UI Designer · Enterprise data tablesFilters you can read at a glanceRead the case study Senior UX/UI Designer · Financial servicesChoosing who looks after your moneyRead the case study