blog single

Design tokens that survive a redesign

Design system color and type specimens on screen

Published on:

March 13, 2025

TAG:

UI/UX DESIGN

BY:

Edgeless Team

Read Time:

5 MIN READ

post detail

A design token is a named decision: this blue, this spacing step, this font size. The idea is simple, and most teams adopt it. The problems start with naming. A token called blue 500 survives exactly until the brand changes the blue, and then every component that uses it becomes a small research project.

Name the role

Tokens should describe how a value is used, not what it looks like. Surface, border, text primary, text muted, action, action hover. Those names stay true when the colors change. A palette can sit underneath as raw values, but components should reference the role.

The same applies to spacing and type. A token called space 4 is less useful than one called space inline or space section. Naming by role makes the design intent readable in code, and it lets a designer change the rhythm of a page without hunting through components.

Keep a raw palette for values that never change, such as brand colors.
Add a semantic layer for roles such as surface, text and action.
Add a component layer only where a component needs a specific override.
Use one naming convention across colors, spacing, radius and type.
Document the purpose of each token next to its value.
Version the tokens when a meaning changes, not just when a value does.

Themes are the real test

If the product may support a dark theme, a high contrast mode or a partner brand, the token structure will be tested. A semantic layer makes a theme a set of value overrides. A palette only structure makes a theme a rewrite of every component.

Build the second theme early, even if it ships later. The exercise exposes tokens that encode two decisions at once, such as a token used for both a border and text. Splitting those tokens is much cheaper before the component count grows.

Designers comparing light and dark theme components — A second theme is the cheapest audit of a token system. Anything that cannot be themed is usually two tokens wearing one name.

Tokens and components

Components should consume semantic tokens, not raw values. A button uses action and action text. A card uses surface, border and text primary. When a component needs a value that no token provides, that is a signal to add a token or question the design, not to hard code a hex value.

Keep the component layer thin. A token for every part of every component creates a system nobody can learn. Most components can be built from a small set of semantic tokens plus layout properties that do not need tokens at all.

Governance without a committee

Decide who can add a token and what evidence is required. A reasonable rule is that a new token needs two components that share the same decision and no existing token that fits. That rule keeps the set small and prevents one off values from becoming permanent.

Review the token set each quarter. Look for tokens used once, tokens with the same value and tokens whose names no longer match their use. Removing a token is a breaking change, so plan it with the same care as a code change and communicate it before the release.

Type and spacing scales

Type needs a scale with clear steps and a rule for each step. Display, heading, subheading, body, caption and label cover most products. Name by role and set size, line height and weight together, because a size without its line height is only half a decision.

Spacing needs fewer options than most teams expect. A base unit with a small set of multiples covers nearly every layout. The important part is consistency at the section level, where an inconsistent rhythm is most visible. A token for section spacing prevents the slow drift that happens when each page is built by a different person.

Radius, border width and shadow deserve tokens too. They are small decisions that appear in hundreds of places, and they are the first to drift when a new component is built in a hurry. A shadow token with a purpose name, such as raised or overlay, is easier to use than a raw blur and spread value.

Tokens in code

Tokens should live in one source and be generated into the formats each platform needs. A JSON file or a theme file can feed CSS variables, a mobile theme and a design tool. Hand maintaining three copies guarantees they will disagree within a month.

Use the platform's variable system for runtime theming and keep the raw values out of components. In CSS, that means custom properties on a root selector and semantic names in the component styles. In a native app, it means the platform's color and typography system with the same names.

Add a check to the build that fails when a component uses a raw color or font size instead of a token. The check does not need to be perfect. Catching the obvious cases keeps the system from eroding one shortcut at a time.

Getting teams to use it

Documentation matters less than the path of least resistance. If using a token is harder than typing a hex value, people will type the hex value. Provide snippets, editor completions and a component library that already uses the right tokens, so the correct choice is also the fastest one.

Show the system in a living page, not a static document. A page that renders every token in its real context is easier to trust and stays accurate because it reads from the same source. Static screenshots are out of date the week they are published.

Train new team members on the naming rules, not on the full list. If they understand that names describe roles, they can find the right token without memorising a catalogue. The rules are what make the system usable at scale.

Deprecate tokens with a date rather than deleting them quietly. Mark the old name, point to the replacement and keep it working for a release or two. Quiet removal breaks code somewhere else in the system and teaches the team to avoid the next cleanup.

Migrating without a freeze

A token migration can run alongside feature work. Map old values to new tokens, update components in batches and keep a visual regression check on the main templates. The check catches the cases where a value was doing two jobs and the split changed one of them.

Do the highest traffic screens first. They carry the most risk and give the fastest feedback. Leave internal tools and rarely used settings for later, but put them on the plan so they do not become permanent exceptions.

A token is a decision with a name. If the name describes the appearance, the decision will not survive the next rebrand.
Edgeless Team

The payoff goes beyond a faster rebrand. A consistent token set makes accessibility work cheaper, because contrast can be checked once per role instead of once per component. It also makes design reviews shorter, because the question changes from which blue to whether this is a surface or an action.

We build token systems and component libraries that hold up across themes, brands and redesigns, with documentation your team can maintain.

Explore UI and UX design

Start with the semantic layer and one component. Prove that a theme change updates the component without touching its code. Once that works, the rest of the system has a pattern to follow.

Design Systems

Frontend

Design tokens that survive a redesign

Let's Talk About Your Project