Design tokens: how to store and scale brand style in code
Two-level or three-level architecture: the choice depends on the product scale
The classic schema primitive → semantic → component is not always good. For a team with one product and one theme, the third level is often excessive — it adds an abstraction layer that nobody reads, and maintaining it requires twice as many files.
| Criterion | 2 level (primitive → component) | 3 level (primitive → semantic → component) |
|---|---|---|
| Product with one theme, no rebranding | Suitable | Excessive |
| Support for light/dark, multi-brand | Does not work without rewriting components | Required — as in Material Design 3, where theme switching occurs through semantic substitution without changing component logic |
| Team of up to 5 developers | Sufficient, below entry threshold | Overhead at the start |
| Product line across multiple platforms | Quickly runs into duplication | Justified, the semantic layer untangles the platforms |
The rule is simple: if there is a theme, rebrand, or multibrand in the roadmap — take three levels at once; the transition from two to three levels retroactively is painful and requires manual migration of all links.
Synchronization between Figma and code: where the process actually breaks down
Here, the top of the search results is usually limited to the phrase 'set up synchronization via a plugin,' but the problem is not in the setup, but in its fragility. Tokens Studio remains the only plugin with full bidirectional synchronization with a Git repository, and even there, discrepancies occur regularly — due to branch conflicts, manual edits in the code 'around' the tokens, and different merge orders.
A telling case is the Figma Dev Mode 2.0 incident in October 2024 year: automatic removal of prefixes from token names caused collisions and desynchronization in 12 production components. The lesson is simple — any automatic name transformation must be tested on a copy of the production set before updating the plugin, rather than trusting the tool's default settings.
- A designer renames a token locally in Figma without pushing to the repository — code and design silently diverge.
- A developer hardcodes a value that is 'one pixel more precise' than in the token — a shadow duplicate appears.
- Plugin update changes the export format — the Style Dictionary transformation pipeline breaks.
All three issues are solved not by the tool, but by the process: CI check that blocks merge if the token value in code does not match the source in Git, and a ban on direct edits of tokens in Figma without a pull request.
Governance: why token systems collapse after launch
Francesco Improtta precisely formulates the core of the problem: token systems degrade not due to tools, but due to the lack of a governance process. Without a component layer owner, without an approval workflow, and without a deprecation strategy, the system collapses within months — developers start creating local variables 'because it's too slow via tokens,' and duplication grows unnoticed.
- Appoint a token owner — not a designer 'on a part-time basis,' but a role with the authority to reject a new token if a suitable one already exists for the task.
- Enter approval workflow: a new token goes through review just like code — with a mandatory response to the question 'why do existing semantic tokens not fit'.
- Document deprecation strategy: a token is marked as deprecated, lives for at least one release cycle with a warning in the code, and then is deleted — without this step, the list of tokens only grows.
- Conduct quarterly audits: how many tokens are actually used in components, how many — dead weight.
A good system versus a bad one: how to measure this, not feel it.
The difference between a working and a broken system is not in the beauty of documentation, but in specific numbers. Knapsack in the 2023 study showed: teams with a consistent naming convention solve design-to-code handoff problems 38% faster than teams without standards — this is a measurable, not an abstract effect.
| Metric | Good system | Bad implementation |
|---|---|---|
| Share of hardcoded values in component code | Close to zero, there is a lint rule | Grows over time, nobody tracks it |
| Token naming | By role: color-action-primary | By appearance: primary-500 — breaks during rebranding |
| Figma/code synchronization | Automatic, with CI check | Manual, 'once per sprint' |
| System owner | Assigned, there is an approval process | No one, anyone adds tokens as they wish |
It is worth remembering a architectural mistake that is barely noticeable at the start: naming a token by appearance instead of role. primary-500 works while the product has one brand and one theme. During rebranding or launching a second brand, such a name requires rewriting all references, because the token's meaning is tightly bound to a specific shade, not to a function.
Token bloat: how component tokens turn into hundreds of positions
Tetrisly ran into a telling problem — 500+ tokens just for one Button component, if you multiply all states, variants, and themes. At this point, the abstraction loses meaning: searching for the right token takes longer than writing the value directly, and the very idea of reuse falls apart.
You can avoid this only by consciously limiting combinatorics, rather than automatically generating a token for every parameter intersection:
- Separate states (hover, disabled) via modifiers on top of the base semantic token, rather than creating a separate token for each combination.
- Treat component tokens as a limit — if there are more than 20-30 per component, that's a signal to reconsider the architecture, not to expand the list.
- Use inheritance through the semantic layer: the theme changes the value at the semantic-token level, the component layer should not know about the theme at all.
When tokens are not needed at all
This is the conclusion that rarely appears in articles about setup, and for no good reason. If the product is a landing page with a single theme, without plans for rebranding, without multiple platforms, and without a team of designers that changes — tokens will add overhead that will never pay off. Three levels of abstraction, a pipeline for transformation through Style Dictionary, synchronization with Git — this is infrastructure justified only where the style changes more than once a year, or is used simultaneously in multiple products.
The storage format should also be chosen based on actual needs, not trends: the W3C Design Tokens Community Group standardizes the JSON format, but most systems on the market use it only partially — and that is normal if the internal team has agreed upon a unified convention and follows it without exception. A standard is needed where tokens will be transferred between tools from different vendors; for a closed internal system, discipline is more important than compliance with the specification.
Two-level or three-level architecture: the choice depends on the product scale
The classic schema primitive → semantic → component is not always good. For a team with one product and one theme, the third level is often excessive — it adds an abstraction layer that nobody reads, and maintaining it requires twice as many files.
| Criterion | 2 level (primitive → component) | 3 level (primitive → semantic → component) |
|---|---|---|
| Product with one theme, no rebranding | Suitable | Excessive |
| Support for light/dark, multi-brand | Does not work without rewriting components | Required — as in Material Design 3, where theme switching occurs through semantic substitution without changing component logic |
| Team of up to 5 developers | Sufficient, below entry threshold | Overhead at the start |
| Product line across multiple platforms | Quickly runs into duplication | Justified, the semantic layer untangles the platforms |
The rule is simple: if there is a theme, rebrand, or multibrand in the roadmap — take three levels at once; the transition from two to three levels retroactively is painful and requires manual migration of all links.
Synchronization between Figma and code: where the process actually breaks down
Here, the top of the search results is usually limited to the phrase 'set up synchronization via a plugin,' but the problem is not in the setup, but in its fragility. Tokens Studio remains the only plugin with full bidirectional synchronization with a Git repository, and even there, discrepancies occur regularly — due to branch conflicts, manual edits in the code 'around' the tokens, and different merge orders.
A telling case is the Figma Dev Mode 2.0 incident in October 2024 year: automatic removal of prefixes from token names caused collisions and desynchronization in 12 production components. The lesson is simple — any automatic name transformation must be tested on a copy of the production set before updating the plugin, rather than trusting the tool's default settings.
- A designer renames a token locally in Figma without pushing to the repository — code and design silently diverge.
- A developer hardcodes a value that is 'one pixel more precise' than in the token — a shadow duplicate appears.
- Plugin update changes the export format — the Style Dictionary transformation pipeline breaks.
All three issues are solved not by the tool, but by the process: CI check that blocks merge if the token value in code does not match the source in Git, and a ban on direct edits of tokens in Figma without a pull request.
Governance: why token systems collapse after launch
Francesco Improtta precisely formulates the core of the problem: token systems degrade not due to tools, but due to the lack of a governance process. Without a component layer owner, without an approval workflow, and without a deprecation strategy, the system collapses within months — developers start creating local variables 'because it's too slow via tokens,' and duplication grows unnoticed.
- Appoint a token owner — not a designer 'on a part-time basis,' but a role with the authority to reject a new token if a suitable one already exists for the task.
- Enter approval workflow: a new token goes through review just like code — with a mandatory response to the question 'why do existing semantic tokens not fit'.
- Document deprecation strategy: a token is marked as deprecated, lives for at least one release cycle with a warning in the code, and then is deleted — without this step, the list of tokens only grows.
- Conduct quarterly audits: how many tokens are actually used in components, how many — dead weight.
A good system versus a bad one: how to measure this, not feel it.
The difference between a working and a broken system is not in the beauty of documentation, but in specific numbers. Knapsack in the 2023 study showed: teams with a consistent naming convention solve design-to-code handoff problems 38% faster than teams without standards — this is a measurable, not an abstract effect.
| Metric | Good system | Bad implementation |
|---|---|---|
| Share of hardcoded values in component code | Close to zero, there is a lint rule | Grows over time, nobody tracks it |
| Token naming | By role: color-action-primary | By appearance: primary-500 — breaks during rebranding |
| Figma/code synchronization | Automatic, with CI check | Manual, 'once per sprint' |
| System owner | Assigned, there is an approval process | No one, anyone adds tokens as they wish |
It is worth remembering a architectural mistake that is barely noticeable at the start: naming a token by appearance instead of role. primary-500 works while the product has one brand and one theme. During rebranding or launching a second brand, such a name requires rewriting all references, because the token's meaning is tightly bound to a specific shade, not to a function.
Token bloat: how component tokens turn into hundreds of positions
Tetrisly ran into a telling problem — 500+ tokens just for one Button component, if you multiply all states, variants, and themes. At this point, the abstraction loses meaning: searching for the right token takes longer than writing the value directly, and the very idea of reuse falls apart.
You can avoid this only by consciously limiting combinatorics, rather than automatically generating a token for every parameter intersection:
- Separate states (hover, disabled) via modifiers on top of the base semantic token, rather than creating a separate token for each combination.
- Treat component tokens as a limit — if there are more than 20-30 per component, that's a signal to reconsider the architecture, not to expand the list.
- Use inheritance through the semantic layer: the theme changes the value at the semantic-token level, the component layer should not know about the theme at all.
When tokens are not needed at all
This is the conclusion that rarely appears in articles about setup, and for no good reason. If the product is a landing page with a single theme, without plans for rebranding, without multiple platforms, and without a team of designers that changes — tokens will add overhead that will never pay off. Three levels of abstraction, a pipeline for transformation through Style Dictionary, synchronization with Git — this is infrastructure justified only where the style changes more than once a year, or is used simultaneously in multiple products.
The storage format should also be chosen based on actual needs, not trends: the W3C Design Tokens Community Group standardizes the JSON format, but most systems on the market use it only partially — and that is normal if the internal team has agreed upon a unified convention and follows it without exception. A standard is needed where tokens will be transferred between tools from different vendors; for a closed internal system, discipline is more important than compliance with the specification.
Recent articles
MegaFon, BMW, VTB and more 240+ companies. See how it looks in the showcase reel:
Our branding agency is approached to order:
Branding agency services
