A ride-hailing driver app's design system re-pointed its primary-action semantic token for a brand refresh, but many screens still show the old blue. What bypassed the semantic layer, and how do you fix it?
answer
- rule out stale releases first
- literals and direct primitive references
- classify intent before replacing
- make the semantic path the easy one
basics
~20 sThose screens bypassed the semantic tier: they hold a pasted color value or reference the brand-blue primitive directly, so re-pointing the semantic alias never reached them. Classify each usage by purpose, map it to the matching semantic token, then guard against recurrence.
solid answer
~50 sFirst rule out the boring cause: the affected apps may not have taken the release with the new token values yet. If they have, those screens bypassed the semantic layer. Typical bypasses are a color value pasted from a design file, a direct reference to the brand-blue primitive (which the refresh did not change), a local constant that copied the token's old value, or a component token wired straight to the primitive. The fix is not a global replace with `color.action.primary`: a pasted blue carries no intent, so each usage must be classified — primary action, link, selected state, map route — and mapped to the semantic token for that purpose, adding a token where one is missing. Then make bypasses hard: primitives marked internal, automated checks that flag raw values and primitive references, and a quick way to request a missing semantic token.
go deeper
Know that a screen only follows a token change if it references the semantic token, and that pasted values and primitive references never follow.
Explain why re-pointing an alias misses direct primitive references, local copies and component tokens wired to primitives, and why a global replace is wrong.
Run the diagnosis in order — delivery first, then bypass inventory, intent classification and guardrails — and coordinate the fixes across teams and platforms.
Treat the refresh as a measurement of how connected each product is to the system, and decide where to invest: guardrails, missing tokens, or design-side hygiene.
## Why re-pointing an alias does not reach every screen In a tiered token system, a **semantic token** such as `color.action.primary` aliases a **primitive** such as the brand blue `color.blue.600`. A brand refresh that changes the primary-action color re-points that one alias at a different primitive. Everything that references `color.action.primary` — directly or through a component token — follows. Anything that does not reference it cannot follow. The primitive `color.blue.600` itself did not change, so a screen tied to it keeps showing the old blue, and a screen holding a pasted color value keeps that value indefinitely. So "many screens still show the old blue" means one of two things: the new token values have not reached those screens yet, or those screens were never connected to the semantic token. ## Step 1: rule out delivery Before hunting for bypasses, confirm the change actually shipped to the affected apps: - Is each consuming app on the release that contains the re-pointed token? A team still on an older release shows the old blue on every primary action, not just some screens. - For native apps, token values are often compiled into the app, so the change reaches drivers only with a new app build. - Are any affected surfaces images or illustrations with the old blue baked in? Those need new assets, not token work. A pattern of *some* screens wrong in an otherwise up-to-date app is the signature of a bypass. ## Step 2: find the bypasses | Bypass | Example in the driver app | Why the refresh missed it | How to find it | |---|---|---|---| | Pasted value | The go-online button styled with the blue's literal value copied from a design file | No link to any token | Search product code for the old color value in every notation the platforms use | | Direct primitive reference | The trip-details link reads `color.blue.600` | The primitive did not change | Search for primitive references outside the token source and the library | | Local copy | A screen-level constant set once from the token's old resolved value | A snapshot, not an alias | Search for constants holding color values | | Component token wired to a primitive | `ride-card.accept.background` aliases `color.blue.600`, skipping the semantic tier | The chain never passes through the re-pointed alias | List component tokens whose alias target is a primitive | | Raw colors in design files | Mockups drawn with unlinked colors, then implemented faithfully | The bypass started upstream | Audit the design library for colors not linked to tokens | ## Step 3: classify, then replace The tempting fix — replace every old blue with `color.action.primary` — is wrong. A pasted blue carries no intent, and the brand blue served several purposes in this app. 1. **List every bypass** found in step 2, with its screen and element. 2. **Classify each by purpose**: a primary action, a text link, a selected tab, the map route line, the surge-zone highlight. 3. **Map each to the semantic token for that purpose.** Only the genuine primary actions get `color.action.primary`; links get the link token; the route line gets whatever the system defines for map routes. 4. **Add missing semantic tokens** where a recurring purpose has none, instead of forcing the nearest existing one. 5. **Confirm with design** which uses the refresh was meant to change, because some old-blue screens may have been correct to stay as they are. Mapping everything to the primary-action token would make the screens look right today while coupling unrelated purposes, so the next change to primary actions would recolor the map route too. ## Step 4: stop it recurring - **Make primitives internal**, or clearly marked as not for product use, so the easy reference is the semantic one. - **Add automated checks** to each product's build that flag raw color values and primitive references in product code; designing those rules is a guardrail topic of its own. - **Close the gap that caused the bypass.** Many literals exist because no semantic token fit; a fast way to request one removes the reason to improvise. - **Fix the design side too**, so mockups use the shared library's semantic styles rather than raw colors. ## What this says about the tier model A semantic layer only moves what is connected to it. A refresh is the moment a system discovers which parts of each product were connected, which also makes it a good moment to measure how much of each product actually flows through the tiers — and to report that number to the teams whose screens did not follow.
- Why not replace every occurrence of the old blue with the primary-action token?Because the old blue served several purposes: actions, links, a selected tab, the map route line, a surge highlight. Mapping all of them to the primary-action token makes screens look right today but couples those purposes, so the next change to primary actions recolors the map as well. Classify each occurrence by intent and add semantic tokens where none fits.
- Why did a screen that referenced the brand-blue primitive, which is a token, still miss the refresh?The refresh re-pointed the semantic token at a different primitive; it did not change the primitive itself. A screen referencing the primitive is linked to the old blue, which still exists with its old value. Only references that pass through the semantic token follow a change to that decision.
saying these in an interview costs you the question
- Referencing a primitive token is just as safe as referencing a semantic token.
- Fix it with a global find-and-replace of the old value to the primary-action token.
- Once the token package is updated, every screen must already show the new color.
- Hardcoded values are harmless as long as they match the current token value.
- A bypass is only a code problem; design files cannot cause one.