Skip to content
Interface language: English
Design / Signal

Design tokens: turning a brand's language into rules that survive the next screen

How to name colour, spacing and typography roles and carry a change from a design decision to the elements used on a website.

Article language: English

Aeneia world concept: a worn wooden template with brass hinges and red thread on material samples.
In this article

“This red is a little too red” is a perfectly understandable comment at the start of a project. Once twenty screens are live, it becomes a puzzle. Is it the brand colour, a form error, a promotion background or the border of a delete button? Changing one value might improve one view and break three others that used it for entirely different reasons.

A design token is a named decision that can be reused: a colour, spacing, text style or another property. It becomes most useful when its name describes its role. “Error text” says where the value belongs. “Red number three” mainly says that someone has already chosen two other reds.

You do not have to build an extensive system at once. A small set of decisions that both the designer and developer understand is enough for a growing website. It should help the team answer what is changing, why, and which places need checking afterwards. A list of values without those relationships can be little more than a tidier way to store a mess.

Name the role before choosing the value

Imagine a fictional shop selling studio equipment. Its brand uses a deep red accent, and a similar shade appears in an address error. At first both look fine. When the team changes the brand colour, the error message takes on the new shade even though nobody decided to change its readability.

The problem is one value serving different roles. The two can start with the same shade, but name the brand accent and error text separately. A later change does not then have to affect both. A deliberate rule, rather than an accident in a stylesheet, determines whether they stay linked.

Distinguish three things: the raw value, its role, and its use in a particular element. The raw value is the shade. The role might be “error message text”. The element is the text below the address field. Not every project needs three separate naming layers for every property, but it helps to understand the difference before linking dependencies.

In the Design Tokens Format Module 2025.10, an alias refers to the value of another token. The report also describes using such references to create semantic relationships. It provides a technical basis for connecting decisions; it does not choose a brand's names or palette.

In our example, give each working name a role and a scope to check after a change:

  • Brand accent highlights promotional content. After a change, inspect headings, links and offer accents.
  • Error text explains a problem beside a field. Check the message's legibility against its background.
  • Error border connects the field to the problem. Check the field state and neighbouring indicators.
  • Field-to-error spacing defines the relationship between the control and its instruction. Check longer text and magnification.

These are prompts for a conversation, not code names to copy. A developer may use a different syntax. Both sets of names should refer to the same roles and make it possible to identify the corresponding element on the site.

Do not name a token solely after its current position. “Text on the left” soon loses meaning when the layout or language changes. Nor should a shared role be named after one screen. A name should survive moving an element, without becoming so broad that it fits everything.

Follow one change from decision to screen

Suppose the team wants to distinguish an error message more clearly from a decorative brand accent. First it states why: a person filling in the form should be able to connect the explanation to the field easily, while a promotional heading should not look like a warning. Only then does it choose values for the relevant roles.

The designer identifies the error text, field border and space between them. The developer checks which elements use those decisions. They may find a hard-coded colour or an old local style. If it stays outside the system, the change will only appear complete: a new card will work, while an old form still speaks a different visual language.

Inspect elements that happen to use the same value as well. Perhaps an error border was used on a promotional card because it looked right. Now decide what role it actually performs. Do not fix this by adding another unnamed exception. An exception is also a design decision and needs a reason.

After the change, test a concrete set of states: an empty field, a value that is too long, corrected data and resubmission. Does the text still fit beside the field? Does the border compete with the visible keyboard focus indicator? Does the message disappear too early? A token organises a value; it cannot replace testing the whole element's behaviour.

Include less frequently visited places in the impact review: an expanded menu, a no-results message and a form after several errors. The shared role may appear in different surroundings. A colour that works on white also needs checking in a panel with its own background. Names make these places easier to find, but assessment still requires opening the relevant page state.

Icons have roles too. The meaning and labels of website icons determine what a control communicates. A token can maintain its state colour or spacing from text. It cannot make a mysterious drawing understandable without a suitable label. The guide to icon meaning and labels (in Polish) explores this context.

Aeneia conceptual photography

Also check the ordinary state without an error. Changing shared spacing can affect the height of every field, even when the design concerned one message. Acceptance should cover places using the role, not just the screen where the decision was made.

The Aeneia Design service can help teams establish shared visual rules for a growing website. Before work begins, agree which elements will be maintained as a set and who will be responsible for using them afterwards.

A system must work in different conditions, not just on a mockup

The Atlassian documentation for Forge shows tokens for colour, spacing and typography and their relationship to an app theme. It is an example in a particular environment, not a guarantee that another template works with the same library.

For a company website, first establish which variants actually exist. If the design includes light and dark views, the same text role may need a different value depending on its background. Do not reduce dark mode for a company website to inverting a few colours. Inspect the relationships among content, surfaces, borders and states. For the wider process, see the guide to assessing dark mode (in Polish).

For a brand with several offer families, separate shared roles from distinguishing features. A family may have its own accent colour without changing the character of error text. Brand architecture and product names begin by clarifying relationships within the offer. The visual system should represent those relationships, not invent additional divisions on its own. For a related perspective, see the article on relationships among brand and offer names (in Polish).

Do not create a separate token for every visible gap without checking whether it recurs. You need a few recognisable relationships: between a label and field, between fields, and between sections. Their names can reflect both the chosen scale and the role. A hundred nearly identical values make decisions as difficult as having no rules.

Typography needs similar discipline. A heading style covers more than size: its use, spacing and behaviour with longer content matter too. A website typography system needs to preserve hierarchy when text changes. A token should not shrink a single title merely because it did not fit a mockup. If the system includes data, define roles for chart colours, labels and scales instead of assigning them random palette accents. Related questions are covered in the guide to website typography (in Polish). See also the guide to presenting charts in a brand (in Polish).

Exceptions can be justified. A campaign may have its own accent, or a special module a different rhythm. Record the scope of the exception and its relationship to shared rules. That way the next screen will not accidentally inherit a solution made for one event. Some of the most persistent exceptions are the ones nobody called temporary.

For transactional store messages, shared roles help retain the brand's character, but the technical use must be checked separately. The same design may need different preparation for an email template and a web page. The visual principle is shared; how its values are delivered depends on the environment. The guide to transactional store messages (in Polish) discusses how visual hierarchy supports the next step.

Start with a small set that people use

If the site already works, you do not have to rewrite every component at once. Choose an area that is actually growing or causing trouble, such as a family of offer cards, a form or navigation. Record current values, name their roles and decide which differences are intentional. Only then decide the order of the cleanup.

During migration, keep a map of old names and their replacements. When an old style is to be retired, identify its replacement and the places that need checking. Simply removing a name may reveal a problem only after publication. Documentation should help the developer understand the intent of the change.

Agree on one source of current decisions or a clear synchronisation process. Design and code may use different tools, but they should not maintain different versions of the same rule for weeks without marking the discrepancy. Otherwise the team may discuss conflicting materials while thinking it is reviewing the same design.

Agree how to report a new need too. An editor does not need to know token syntax to point out that a caption on a new card is hard to read. They should know whom to send the address, an example of the content and a description of the problem. The person responsible can then decide whether a new role, a shared value adjustment or a single-component fix is needed. This gives users of the system a route to change a rule instead of creating local workarounds.

A new value needs a short reason. “We need to separate the panel from the background more clearly” provides a basis for assessment. “It looked better in this mockup” may start a conversation, but is not enough as a shared rule. Also record where the new role may be used so that it does not become a remedy for every vague problem.

Do not judge completeness by the number of tokens. For a small site, twenty well-used decisions can be a better start than a large catalogue of names nobody knows how to apply. The set should make the next change possible without reconstructing the project's entire history.

At acceptance, ask the designer and developer to identify the same element and its role. Then choose one change and trace its effects. If both can explain what changed, which places need checking and why others were outside scope, the set is beginning to work. That is a more concrete test than showing a tidy file of values.

Give the decisions an owner. Tokens do not maintain order on their own. They help a team that understands the roles of its elements and records the reasons for changes. Then a comment about a red that is “a little too red” can become a short, testable adjustment rather than an expedition through every screen.

Aeneia / Aeneia editorial

Editorial article. Source links are included in the text.

About Aeneia

Brands we have worked with

  • L’Oréal
  • Garnier
  • Netflix
  • Carrefour
  • Warner Bros. Discovery
  • Biedronka
  • HBO Max
  • Wolt
  • Żabka
  • COSRX
  • Embassy of China in Poland
  • Mixa
Aeneia / Initium

From knowledge to a decision

Tell us what you want to put in order. We will agree on where to start.

Contact Aeneia

We partner with and use solutions from:

  • Google
  • OpenAI
  • Microsoft
  • Stripe
  • Anthropic
  • Linear