Expertise · Token platform and multi-platform

Design token: the foundation that determines the entire system.

Understanding tokens means knowing why changing a color at the root updates the entire digital product, and why skipping this step leaves the system as just a collection of disconnected components.

Quick summary

A design token is a named design decision saved as data, rather than typing raw values scattered everywhere. Every interface component references the token, so changing the value at the root updates the entire interface accordingly. Without the token layer, you only have a set of discrete components and must manually fix hundreds of places whenever the brand changes.

Quick comparison
You should choose this direction when
  • from two or more digital products, needs light and dark or multiple brands
  • want to change one place, the entire interface updates accordingly
Not needed when.
  • only have one static page, rarely changing, created by one person

A design token is a named design decision saved as data. For example, instead of typing #1A1A2E In every place that requires a primary background color, you name it color.background.primary And use that name throughout the entire system. This is not a technical trick but an architectural decision: whoever controls the token controls the entire product appearance.

Three levels of tokens and reasons for stratification

A healthy token system has three layers, each with its own reason for change:

  • Raw token (global or primitive): Contains raw values, for example, blue-500 = #2563EB. This layer does not specify the purpose of use; it is merely a storage space.
  • Semantic token (semantic or alias): Carries design intent, for example, color.action.primary point to blue-500. This is the layer that determines the context of use: warning background, secondary text, interactive borders.
  • Component token: Assigned to specific parts, for example, button.background.default point to color.action.primary. This layer is only necessary when the system truly expands.

Operation principle: components should read semantic tokens, not read the original tokens directly. This is a condition for changing light and dark themes or multi-branding without having to edit each component.

Separate three token layers so that each layer has its own reason for change. Changing one layer does not topple the others.

Nathan Curtis, Tokens in Design Systems (EightShapes)

Why the token determines the entire system

The way a design system works is: every component references tokens and does not contain hard-coded values. This means:

  • Changing the value of a token at the foundational or semantic level, causing the entire website, application, and documents to update immediately.
  • A token is a common contract between designers and developers. Both parties use the same name, eliminating the issue of different names being used in Figma and in the code.
  • When you need to expand to a new platform, whether iOS, Android, or an embedded application on a partner's website, tokens can be exported to that environment without needing to redesign from scratch.

Ignore the token layer, leaving only a set of standalone components. Changing brand colors means manually fixing hundreds of instances and still missing some.

When to invest in the token layer, when not yet needed

Invest in a full token layer when: You have two or more digital products, or one product needs to support light and dark modes, or you plan to expand the brand in the near future. It is also advisable to invest early when the design and programming teams are working in parallel and need a common language.

No need for multiple layers of tokens if: There is only one static page, with few changes, and one person handles everything from start to finish. In this case, a minimal semantic layer should still be in place for future protection, but three full layers are not yet necessary.

Sinh Vũ's perspective: create tokens before building components, as tokens are the foundation for everything above. Reversing the order means having to break and redo things later.

Common errors when implementing tokens

  • Set token names based on specific colors at the semantic level: For example, set names. color.xanh-500 for the main button color. When the brand switched to orange, the name turned out to be completely misleading and confused the entire team.
  • Component reads straight from the original token: Skipping the semantic layer causes dark mode and multi-branding to become stuck later, as there is no intermediate layer for swapping.
  • Too many unused tokens: The system expands, but the actual token usage rate is low, and the design team can no longer remember which tokens are used for what. Start from the actual needs of the existing interface, standardize, and then expand.

Naming tokens based on usage meaning, not current value, so the name remains accurate when the value changes.

Nathan Curtis, Naming Tokens in Design Systems (EightShapes)

The viewpoint of Sinh Vũ

Sinh Vũ regards the token layer as an essential foundation. In every design system project, Phase 1 always begins with a review of all existing digital interfaces, then standardizes them into three layers of tokens before building any components.

The operational perspective is a single source of truth for color, font, and spacing: changing at the source means the entire website, application, and components change accordingly, without missing any spots. This is not a technical ambition, but a minimum requirement for a brand to be consistent across multiple digital touchpoints without exhausting manpower on manual synchronization.

The tool brings back.

Decision checklist

Topic: What is a design token and why does it determine the entire system? Sinh Vũ guide, sinhvu.com

0 more than 6 items

Select each item you find appropriate, then print or save as PDF to take with you.

Sign indicating that you should take action
Questions to answer before deciding

If you have marked most of the signs above, this is the time to discuss in more detail. Sinh Vũ can help you review and propose a direction.

References

Nathan Curtis, Tokens in Design Systems (EightShapes); Nathan Curtis, Naming Tokens in Design Systems (EightShapes); Material Design 3, Design tokens overview.

Frequently asked questions

How do design tokens differ from CSS variables?

CSS variables are a technique for storing values in programming code. Design tokens are design decisions named for their intended use, existing independently of the technical platform, and can be exported to CSS, iOS, Android, or any environment. In other words, CSS variables are a way to implement tokens, while tokens are broader and exist at a common language layer between design and programming.

How many tokens are enough, and how can you tell if you are generating too many?

There is no absolute number. A sign of excessive token creation is a low ratio of tokens actually used in components, and the design team no longer remembers which tokens are used for what. Sinh Vũ recommends starting from the actual needs of the existing interface, standardizing, and then expanding, rather than defining the entire token system before having a product to reference.

If the product only has one interface and does not require a dark mode, is it necessary to have three layers of tokens?

It is not necessary to have all three layers from the start. However, the semantic layer should still be present even for simple products, as it protects you from having to adjust each component every time the colors change. The component token layer can be added later when the system truly expands.

← Back to Digital design system