In a design system, how should design-file variables relate to the coded design tokens, and what goes wrong when they are maintained separately?
answer
- one source, two outputs
- same names, same tiers
- semantic variables alias primitives
- modes match themes
- hand-copied values drift silently
basics
~20 sDesign-file variables should mirror the coded tokens: same names, same tiers and aliases, same modes, ideally generated from one source. Maintained by hand on both sides, values and names drift, so designs show colours or spacing the product never renders.
solid answer
~50 sIn a design editor, **variables** (or styles) are what designers apply for colour, spacing, radius and type; in code, **design tokens** play the same role. They should be one set of decisions expressed twice. That means the **same names**, so 'color/text/critical' in the design file is the same decision as the coded token; the **same structure**, so a semantic variable aliases the same primitive the semantic token does; and the **same modes**, so a design file's light, dark or brand modes match the coded themes. Ideally both are produced from one token source, with a defined direction of sync. When the two are maintained separately, values drift: a designer tweaks a grey in the file, code keeps the old one, and nobody notices until a review. Names drift too, and designers start applying raw values because the variable they need is missing.
go deeper
Recall that design-file variables and coded tokens represent the same decisions, so they should share names and values.
Explain what mirroring covers beyond values, including tiers, aliases and modes, and why flattening semantic variables breaks theming later.
Show how you would choose and document a direction of sync, keep the generated side read-only, and catch drift with regular comparisons.
Weigh token-first, design-first and two-way sync for your organisation, given who edits most, how much review is needed and how many platforms consume the tokens.
## Two representations of the same decisions A **design token** is a named design decision, such as a colour, a spacing step or a corner radius, stored so every platform can use it. Design editors have an equivalent: **variables** or styles that designers apply to shapes and text. In a **design system**, these are not two sets of decisions; they are one set expressed in two places. **Library parity** for tokens means the design-file variables mirror the coded tokens exactly. ## What mirroring means | Aspect | Design-file variables | Coded tokens | Parity rule | |---|---|---|---| | **Names** | color/text/critical | the same name in each platform's form | Same logical name | | **Tiers** | Semantic variables referencing primitives | Semantic tokens aliasing primitives | Same alias structure | | **Values** | Resolved colour, size, radius | Resolved values per platform | Same resolved values | | **Modes** | Light, dark, brand or density modes | Themes or modes | Same set of modes, same names | | **Scope** | Where a variable may be applied | Where a token is meant to be used | Same intended use | The most overlooked row is **tiers**. If the design file stores only resolved values while code uses semantic tokens that alias primitives, a designer can pick the right colour but the wrong decision: a primitive grey instead of the semantic 'text-secondary'. The screen looks identical today and diverges the day a theme remaps the semantic token. ## One source, a defined direction Mirroring is only reliable when one side is the **source of truth** and the other is produced from it. Teams commonly choose one of three shapes: 1. **Token source first.** A tool-agnostic token file is the source; the design-file variables and every platform's code output are generated from it. 2. **Design file first.** Designers edit variables, and an export turns them into the token source, which then generates code. 3. **Two-way sync.** Changes on either side are reconciled. This is the most convenient in daily use and the easiest to get wrong, because conflicting edits need rules. Whichever shape a team picks, it must be written down: who edits where, how a change travels, and what happens if someone edits the generated side by hand. ## What goes wrong when both are maintained by hand - **Value drift.** A designer adjusts a grey to improve contrast in the file; the code keeps the old value. Designs and product quietly differ. - **Name drift.** A token is renamed in code; the variable keeps the old name, so handoff notes reference a name engineers cannot find. - **Missing variables.** A new token exists only in code, so designers apply a raw value instead, and that raw value is now in every design using it. - **Mode mismatch.** Code has a high-contrast theme; the design file has no matching mode, so nobody can design or review it. - **Broken aliases.** The design file flattens semantic variables into raw values, losing the link that theming depends on. Each defect is invisible in any single screen, which is why they accumulate. ## An example: an insurance claims portal An insurance claims portal has an adjuster dashboard and a claimant app, both with a light and a dark mode and a separate partner brand for a broker's white-labelled version. The team makes the token source the single source. Design-file variables are generated from it with the same names and the same semantic tier, and the file has three modes matching the three coded themes. When accessibility review asks for a stronger critical-status colour, the change is made once in the token source; the next sync updates the design variables and the platform outputs together, and both the rejected-claim banner in the design file and the one in the product change at the same time. ## Keeping it true - Treat the generated side as **read-only**; edits there are overwritten or blocked. - **Compare regularly**: a scripted check that lists names and resolved values on both sides catches drift early. - Include design variables in the **definition of done** for any token change. - Keep **modes and themes** in the same list, so adding a theme in code without a design mode is visibly incomplete.
- Why is two-way sync between design variables and coded tokens risky?Both sides become editable, so conflicting edits need rules: which wins, and how a reviewer sees the change. Without them, a designer's experiment can overwrite a reviewed token value, or a code change can silently alter designs. One source with a single direction of change is easier to review, and teams that use two-way sync usually add review steps to compensate.
- Why keep the semantic tier in design-file variables instead of only resolved values?Resolved values let a designer pick the right colour for the wrong reason, such as a primitive grey instead of the semantic text-secondary. The screen matches today, but when a theme remaps the semantic token, code changes and the design does not. Keeping aliases makes the designer's decision the same one the code makes.
saying these in an interview costs you the question
- Design variables only need the same colour values; names can differ.
- Flattening semantic variables to raw values in the design file is harmless.
- Two-way sync removes the need to agree a source of truth.
- A theme added in code needs no matching design-file mode.
- Designers should adjust generated variables directly when a value looks off.