Design Tokens Without the Ceremony

Design tokens have a reputation for being a big-company tool: JSON files, transformation pipelines, a dedicated team. All of that is useful at scale, but it scares small teams away from an idea that is genuinely simple. A token is a named decision. You can start using them this afternoon with plain CSS.

Step one: name the decisions

Look through your stylesheet for values that repeat. The brand colour, the card radius, the spacing between sections. Each of those is a decision someone made once and then copied. Give each one a name that describes its role and move it to the top of the file as a custom property.

:root {
  --primary: #4770ff;
  --surface: #f0f2f5;
  --radius-md: 8px;
}

Then replace the copies with var(--primary) and friends. The site looks exactly the same, but every decision now lives in one place.

Step two: one rule for names

The naming rule matters more than the tool. Name tokens by role, never by appearance. --primary survives a rebrand; --blue does not. A few rules that have served me well:

• Colours describe purpose: --title, --muted, --border, --surface.
• Sizes use a short scale: --radius-sm, --radius-md, --radius-lg.
• Components only read tokens. They never define raw values of their own.

Step three: themes for free

Once components only read tokens, a dark theme is just a second set of values under a different selector. No component needs to change, and nobody has to remember which of the forty greys was the card background.

“The best design system is the one your team actually uses. Start with a list of names, not a platform.”

Pettric Ebra

When the project grows, the same names can move into a JSON file and a pipeline. Until then, a well-named block of custom properties gets you most of the benefit.