Tokens in Figma: Configure once and never manually change colors

Open any Figma file from a year ago. Count how many shades of gray there are. Seven? Twelve? Now, compare it to what's described in the guidelines -- there are three.

It's not designer laziness. This is the normal behavior of a system in which colors live as hex values rather than as variables. Each new layout adds "almost the same blue," "a little darker on the hover," "form background - need another." After six months in the library of styles is a mess, in production three different primary, and the change of brand color turns into a project for a sprint.

Tokens solve this once and for all – if configured correctly. If set up hastily, they add a layer of abstraction and nothing else. The difference between “works” and “formality for the sake of a tick” is in architecture and discipline, not in the fact of using Variables.

---

## What is a token and what it is not

A design token is a named variable that stores a solution, not a value. color.background.surface is a surface background solution. What’s inside now is #FFFFFF, a detail of implementation. Tomorrow it could be #FAFAFA, and no layout will have to be opened manually.

What the token is not:

• It’s not “figma style with a clear name.” Style is a static reference to value, a token is a variable that can be rebounded.
• This is not a way to “fix the palette.” Order is an effect, not a goal. Purpose is the only source of truth between design and code.
• It's not a one-day task. The minimum working system of tokens is set up in a couple of days, normal - in a couple of weeks of iterations.

### Signs That You Really Need Tokens

• There’s more than one designer on the team, and someone has already asked “what kind of gray to take for the separator.”.
• Redesign, rebranding or support for a dark theme is being prepared.
• Developers draw colors from layouts with their eyes, not from variable code.
• Marketing asks for “the same product, but in the brand color of the partner” – and you know it’s two weeks of work.

If you have two points, it's time. If not, you may have enough styles, and that’s fine.

---

## Three layers of tokens: why one level is a trap

The most common mistake is to name the variables blue-500, blue-600, gray-100 and assume that it is a system. It's not a system, it's a renamed palette. When you change your brand, you control everything again: the button component still knows that it is blue-500.

The working architecture is three layers.

### Primitive (or Core)

Raw values. blue-500 = #2D7FF9, gray-900 = #111315, space-4 = 4px. At this level, there is no meaning, only color and number. The components never look here.

### Semantic (or Alias)

Solutions. color.action.primary = blue-500, color.text.default = gray-900, color.border.subtle = gray-200. Here lives the meaning: “action button”, “main text”, “weak border”. The components look here and only here.

### Component (optional)

Specialized tokens: button.primary.background, card.shadow. It is necessary if the component has its own exceptions that do not fit into the semantic layer. If you have 200 component tokens, you’re doing something wrong, most likely the semantics are underdefined.

Why three, not one? When a brand changes, you touch primitive. When the interface logic changes (“let’s not be yellow, but orange”), touch semantic. The components don't move at all. That's what "configured once" is.

### Anti-patterns at launch

• Name semantic tokens by color: color.blue.primary. In a year, the brand will be green and the name will remain.
• Skip primitive and immediately do semantic over hex. Any repainting with your hands again.
• Make component tokens for everything “for the future.” The more layers, the higher the price of change.
• Install a separate token for each unique shade from the layout, instead of first asking “is it really different?”.

## Workflow: How tokens fit into a designer’s day

The tokens don't live in the documentation, but when you pull the component onto the canvas. If you need to open Notion and search for a name for the right color, the system won’t take off. Therefore, the whole point of setting is to make the semantic name closer and more convenient than hex from the palette.

### From an empty file to the first screen

1. Open Variables and make sure the primitive and semantic collections are connected. If not, it's a library problem, not yours, escalate to the owner of the system.
2. Any rectangle, text, icon – get color only through semantic. color.surface.default, color.text.muted, color.border.subtle. No manual hexes, not even a “temporary look.”.
3. I didn't find a suitable semantic token - it's a signal. Either there is a token, but it is called differently (search), or it is not enough (set the task to the owner of the system, temporarily use the nearest in meaning with a comment in the layer).
4. Before the layout commit, go through the layers and make sure there are no local styles left. In Figma, this can be seen by the variable indicator of the Fill / Stroke property.

### Topics and modes: where it pays off

Modes in Figma is where three-layer architecture turns into magic. Light, Dark, High contrast, partner brand are all modes of the same semantic collection, where values refer to different primitive. One click - the layout is repainted completely, without editing components.

What's important to remember:

• Modes switch only what is pegged to tokens. Any manual fill will remain as it was – and this will be seen in the first demo of the dark theme.
• The regime is not a place for exceptions. If you need another radius in the dark card, it’s not a topic, it’s a different component.
• Not the fruits of regimes "just in case." Light and dark are mandatory, everything else is when there is a real scenario.

---

## Diagnosis: How to understand that the system is alive

Tokens are easy to turn into a formality. On the outside, it's all through variables, on the inside, it's the same three primarys and the habit of "let me add another shade of gray." Once in a couple of sprints, it makes sense to run a short audit.

### Token health checklist

• In the semantic layer, there are no names in which the color is sewn (primary-blue, red-error).
• Any primitive has at least one link from semantic. If not, it is either dead or used directly.
• The components in the library do not contain raw hex. At all.
• The number of semantic tokens does not double every quarter. Growth is normal, doubling is a symptom.
• The dark theme is assembled by mode switching rather than a separate copy file.
• Each new token has an author and a reason for its appearance. "I don't remember who started" is a red flag.

### Symptoms that something has gone wrong

• The layout has two visually identical grays, but these are different tokens. Therefore, the semantic layer is described by implementation, not by meaning.
• Designers put personal tokens in their files because “there’s nothing in the shared library.” The system is behind the product.
• The developers keep asking "what color was meant here." So names are incomprehensible without a designer-translator.
• Changing the brand color still requires changes in the components. Architecture is broken somewhere - almost always in semantic.

---

## Typical errors in layouts

### Linking to primitive directly

The most frequent. You take a button, you fill blue-500, because "this is our primary." After six months, the primary turns purple and the button remains blue. The rule is simple: the component sees only semantic. If you really want primitive, stop and ask what semantic name you are missing.

### Token for every sneeze

There is a new screen with a slightly different background - starts color.surface.onboarding.step2. After a year, there are hundreds of such tokens, and no one remembers how surface.card.alt differs from surface.elevated.secondary. Before introducing a new semantic token, ask the question: is this really a new solution or a variation of an existing one?

### Semantic as a palette

Name of the species color.semantic.blue1, color.semantic.blue2. Formally, the layer is, in fact, renamed primitive. Semantic describes the role: where it is applied and why. action.primary, text.inverse, border.focus - yes. accent3 - No.

### Ignoring states

Hover, pressed, disabled, focus is part of semantics, not a darker eye. action.primary.hover, action.primary.disabled must exist as separate tokens, otherwise any component will begin to store the logic of dimming.

---

## Questions for design review

When you look at someone else’s layout (or yours every other day), go through the list. It's faster than figuring it out in a month.

• Are all the fills and wraps tied to variables? Are token indicators visible in the inspector?
• Is it just semantic tokens, or is it primitive?
• Are there tokens specifically designed for this layout? If so, why couldn’t they be reused?
• Does the layout switch to dark mode without visual artifacts?
• Do the token names match those used by the frontend? If not, where is the source of truth?

---

## Segment summary

Tokens work when they are closer than hex, and when the semantic layer describes meaning rather than color. Everything else is hygiene: regular audit, checklist review, willingness to say no to a new token more often than yes. Next, let’s see how this process fits in with the code and where AI tools really help, and where only add noise.

## Tokens and code: where the source of truth lives

The most common conflict in the team is where the “real” tokens are: in Figma or in code. While everything is based on manual synchronization, the two systems diverge during the sprint: the designer renamed surface.muted, the developer did not recognize, the old color remained on the market for another month. The solution is not who is most important, but that one format be the source and the other the consumer.

In practice, this means exporting from Figma Variables to JSON (via a plugin or through Tokens Studio), storing that JSON in a repository, and assembling CSS variables / Tailwind-config / iOS and Android tokens through Style Dictionary or analog. The designer is still working at Figma, but the commit to the repository is the moment when the token “becomes real.”.

### What should lie in the repository

• Raw JSON with primitives and semantic layer, divided into files (primitives.json, semantic.light.json, semantic.dark.json).
• Config assemblies and generated artifacts (CSS, JS, native formats) - but it is better to put the generated separately and not to rule hands.
• Short README: how to add a token, who is the reviewer, how to run the assembly locally.

If not, tokens live in three places at once: Figma, the designer’s head, someone’s comments in Slack.

## AI and MCP: where it helps and where it hinders

The AI tools around Figma – Make, MCP server, screen component plugins – work just as well as your tokens. If the semantic layer is clean, the MCP server gives the model names like action.primary and surface.raised, and the generated code appears to be written by a human. If the layout sticks out hex's, at the output you get a component with hard-cut #3B82F6 - and the whole meaning of the system evaporates.

### Working scenario with MCP

• Connect Figma MCP to your agent (Claude Code, Cursor).
• You're asking for a frame component. The agent pulls variable names, not pixels.
• In the generated code, check whether variable design systems are used or raw values have arrived. If raw is a signal that the token is not tied in the layout.

That is, the AI-pipeline also becomes a hygiene detector: everything that is poorly named in Figma appears in diff PR.

### What not to do

• Ask AI to “invent the missing tokens.” He'll come up with -- and he'll run a color.surface.softAlt2 that nobody wants.
• Generate a dark theme through AI on top of light. Topics are decisions about contrast and hierarchy, not channel inversions.
• Trust auto-mapping “hex → nearest token” without a review. The nearest color is correct in meaning.

## Team scenarios

### New designer on the team

A good sign of the system is that a person comes in and every other day already makes screens without the question “what blue is there?” If the first two weeks are spent on “tell me which token for what” – the semantic layer is not self-sufficient. It is not treated by onboarding, but by names.

### Redesign with rebranding

Changes primary, neutral, accents. If the architecture is intact, edits are only made in primitives and partly in semantic mapping. The components don't touch. If you had to climb into the components – somewhere in the system raw values, and the redesign was a great reason to find them.

### Parallel work of two teams

Two food teams in the same library are the main stress test. Agree in advance: new semantic tokens are started only by the owner of the design system on request through issue. Otherwise, in a month there will be two text.subtle with different meanings and mutual resentment.

## How to explain the decision to the team

Design systems often fail not at the assembly stage, but at the stage of conversation with the product and developers. “We’re remaking tokens” sounds like “the designer is shifting something again.” Explain better through the cost of change.

• How much does the primary change take now and how much will it take after.
• How many "wrong gray" bugs closed in a quarter.
• How long does it take to answer “what color is there” in each ticket.

The numbers don’t have to be accurate – it’s important to show that it’s about saving, not aesthetics.

### Issues for joint review and development

• The names of the tokens in Figma and in the code are the same in meaning and in writing?
• Are there places in the code where the color is still hard-cut? Why didn't you get a token?
• What happens when a designer adds a new semantic token: how does it get into the build?
• Who reviews PR with changes to tokens: only front, only design or both?

## Segment summary

Tokens become a real system when they have one source of truth and a clear path to code. AI and MCP amplify what is already well-organized and mercilessly highlight what is wrong. And the conversation with the team isn't about the beauty of names, it's about the cost of change -- it's the only language in which a design system sounds convincing.

## The final checklist: “We have normal tokens”

Run the library through this list before you consider the system alive. If at least three points are not closed, tokens still exist only in the author’s head.

### Primitives

• The palette of primitives does not grow from layout to layout: new shades do not appear for months.
• The names are neutral: blue.500, not brand.main or ocean.deep.
• Duplicates with a difference of 1-2 brightness units are cleaned.
• No component directly refers to primitive.

### Semantic

• Each token has a semantic name: what it is, not how it looks.
• States (hover, pressed, disabled) are described as separate tokens, not as “take the main and dark”.
• The text on the surfaces passes the contrast without manual editing in the layout.
• The dark theme is a separate mapping, not “inverted and let’s go.”.

### Code connection

• The names in Figma and in the code are the same in spelling, rather than “roughly similar.”.
• There is automatic export (Tokens Studio, Style Dictionary, plugin – anything but manual CSV).
• There are zero hardcode color codes in new components. The old ones are marked as debt.
• PR with changing tokens undergoes a review of both design and front.

### Process

• It is clear who launches a new semantic token and through which channel.
• It is clear how and when outdated ones are removed.
• Changes in primitives and semantics do not roll into PR.
• The library has a version, and the teams know which one they're sitting on.

## Anti-Patterns That Break Everything

### "We'll start bye, then we'll figure it out."

In the library there are tokens color.temp.newButton, surface.figmaTestV2, text.fromLanding. After six months, they are used in the sale, you can not remove, it is scary to rename them. Better an inconvenient rejection of a review than convenient garbage in the system.

### Semantics, which describes the appearance

color.lightGrayBg, text.darkBlue, border.thinGray are not semantics, they are primitives under the guise of semantics. When changing the topic or rebranding such names lie. The name should answer “why”, not “how it looks”.

### One token, many meanings

text.primary is used for headers, buttons, and input icons. When the designer needs to change the color of the icons, he will not be able to, because at the same time the headlines will go. If the token begins to mean “all dark,” it’s time to split it.

### Designer himself platform

One person runs a library, holds the rules in his head, and rules the tokens by mood. As long as he's on the team, everything works. The system collapses over a quarter. Rules should live in a document, not in Slack correspondence.

### Documentation as a museum

A page in Notion describing the tokens, last updated “when we did the redesign.” The team has not checked for a long time, there is another truth in the layouts. Documentation is either automatically synchronized from the library, or it is more honest to delete.

## Questions for design system review

These questions should be asked once a quarter – yourself, the team, and the development. If there is no clear answer, the system has accumulated debt.

• How many semantic tokens are in the library? If the number rose in a quarter for no apparent reason, what was added and why?
• Which tokens are not used in any component? Why are they still alive?
• Where are the latest hardcodes of color left in the product and who is responsible for cleaning them?
• What happens if the primary changes tomorrow? How many files and components do you have to open with your hands?
• Can a new designer assemble a screen without question to an older one—only by library and principles?
• How does a dark theme learn about a new semantic token: automatically or manually?
• When was the last time the design and front looked at the token list together? If long ago it was not a process, it was an accident.

## Practical outcome

Tokens are not a fashion layer on top of a layout or a way to bring beauty to a library. It's an agreement that there's one source of color truth in a product, and any change goes through it. Primitives store a palette, semantic describes meaning, code picks up names one by one, and the team understands who adds a new one and how.

Once done, this work returns time on each redesign, each new developer and each “let’s tweak the main one a bit.” Unmade - turns any color editing into a small project for a week. The choice is essentially between “set up tokens now” and “manually adjust colors always.”.