Verify a design-token change

Resolve, don’t read. Instruments and displays: load desktop-theme-probing before the first live launch (a ./mach theme resolve-token run is not one); it defines the host’s and the target’s platform file that this skill’s references cite by section.

Also load desktop-theme-colors when a token resolves to a system color or the change touches a (forced-colors) or (prefers-contrast) layer, desktop-theme-layout when it changes a size, space or font-size token, and desktop-theme-screenshots when the result needs showing on the bug.

1. Every *.tokens.css is generated; edit its *.tokens.json

Two documents in the source tree back this skill: docs/code-quality/coding-style/css_guidelines.md and toolkit/themes/shared/design-system/docs/README.design-tokens.stories.md. They’re kept up to date with how different parts of the code base interact in non-obvious ways; they may differ from what you remember. Before adding, renaming or removing a variable, read css_guidelines “Using CSS variables” and “Adding new variables”. This skill builds on them and does not repeat them.

Before editing a token, read the README’s “JSON format deep dive” (where the generator reads and writes, and where it writes a token’s comment).

The generated sheets live in toolkit/themes/shared/design-system/dist/ and beside the code they style. A hand edit to a generated sheet works until the next build overwrites it. The tell is style-dictionary failing with Reference doesn't exist: <token> tries to reference <x> for a token you believe you already fixed in the CSS. A grep for a value lands in the generated file, so check the filename suffix and the header before changing any token declaration. The Nova sheet under browser/extensions/newtab/content-src/styles/nova/ (_tokens.scss) is generated by the same build, so its diff lines are output, not authored code.

The file’s own name supplies the leading segment of a token’s path (README “Naming” and “@base”), and a jq path into the file drops that segment: --urlbar-box-text-color-active reads as jq '.box.text.color.active' urlbar.tokens.json, while .urlbar.box… reads null with no error. Never grep for a leaf key: hover, active and @base occur under every variant, so a hit can show a sibling variant’s value. The JSON is only the input; quote the value ./mach theme resolve-token prints (§2). A variant usually mirrors its sibling, {"value": "{urlbar.box.text.color.@base}"}; match the sibling’s shape, except a sibling nova block that omits a side (§1 in references/nova-overrides.md), and edit the file with a JSON round-trip that preserves key order (object_pairs_hook=OrderedDict, indent=2) so the diff is only your addition.

2. Diff resolved values, not diff lines

For any patch touching tokens, fully resolve every declaration a realm sees before and after, then diff the two maps.

A realm is two sheets. Chrome reads tokens-shared.css plus tokens-platform.css, in-content reads tokens-shared.css plus tokens-brand.css; the brand or platform sheet overrides shared values, and a shared value may reference a name only that sheet defines. ./mach theme resolve-token pairs them and reports each realm separately.

The generated sheets are checked in, so reading one token’s current value needs no build:

./mach theme resolve-token \
  toolkit/themes/shared/design-system/dist --effective --<token>

Both sides of a diff have to be generated output, so run ./mach buildtokens first; an unbuilt *.tokens.json edit diffs empty and reads as value-neutral. Apart from --declared, which reads the files it is given, the script reads only the three dist/ sheets: a component *.tokens.css, New Tab’s _tokens.scss and a hand-written redefinition (:root[uidensity], a window attribute) are invisible to it, so a patch confined to a component’s *.tokens.json diffs empty as well, and --effective on a component token prints it undeclared everywhere and exits 1. Read a redefined value with getComputedStyle in that state. Resolve each component declaration a patch changes by hand, with --effective on the shared tokens it references, in every layer (§3). Resolve each reference the patch writes on every side it writes (default, forcedColors, prefersContrast, a nova block) and in every environment that side reaches, because a reference’s target can resolve differently there: a token can resolve to one system color under forced colors with Nova and to another without it. A change to one side moves the value in every environment that side reaches, whatever the patch is about, so resolve every side before and after the patch.

To decide whether a name is a token at all, ask the linter’s table, not dist/, which lacks the component token files (§1); a grep of dist/ that misses one reads a real token as a token-shaped local variable.

cd tools/lint/stylelint/stylelint-plugin-mozilla
../../../../mach node -e 'import("./helpers.mjs").then(h => console.log(h.isDesignToken("--<name>")))'

--before REV diffs against the sheets committed at REV and moves nothing in the tree:

./mach buildtokens
./mach theme resolve-token \
  toolkit/themes/shared/design-system/dist --before HEAD~1   # the change under test is the tip commit; HEAD for uncommitted edits

./mach theme resolve-token --help describes the output; in the --before diff, an EFFECTIVE line is a value change, and a removal or layer move with none is value-neutral. To read values at an earlier commit of a stack, add --at REV to --name or --effective; like --before, it leaves the tree alone. A glean.dispatcher panic after the output is mach’s telemetry, harmless.

A removed or changed declaration in any override context is neutral only if the declaration that now wins under that context’s conditions resolves to the old value. The new winner is the highest remaining layer whose conditions hold, not necessarily tokens-foundation (§3 has the order), and a reference resolves under the same conditions. --effective <token>... prints the winner and its layer per environment, a whole pairing table (desktop-theme-colors §4) in one run, with no browser launch. A review comment that calls a token side redundant, or proposes a value, is a removal or change like any other: resolve it before editing, in every realm and in the generated sheets outside dist/ (New Tab’s _tokens.scss), not after. The layer is the winning declaration’s own: where that value is a var(), the referenced token can win in another layer, so values that differ under one layer name come from the reference, and --effective on the referenced token names its layer. --name prints each declaration resolved in its own context, which is not what paints where a higher layer also applies; README “Chrome native OS theme” has which layer each theme paints, and §2 in references/token-layers.md how to tell the regime from the root.

A token set to a CSS-wide keyword leaves its readers unset. A token with the value inherit (or initial, unset, revert) is guaranteed-invalid on :root, so a var(--x) reader without a fallback acts as unset: a color reader inherits, a background-color reader takes its initial value. A token that references one through var() without a fallback is invalid as a whole at computed-value time, whatever function wraps the reference, so its readers are unset too. The script marks these [empty: unset] and [invalid: unset]; it cannot say what the reader then paints. revert-layer is marked [revert-layer] and left unresolved, since an earlier token layer can supply the value. Confirm a guaranteed-invalid token in a live probe: it reads back empty on the root, and a color reader follows a color you set on its parent.

Filter CHANGED, REMOVED, ADDED and --name lines on the start of the context label (rg -v '\[tokens-forced-colors|> tokens-forced-colors'), never on a bare substring. Every in-app theme label (tokens-browser-theme[-nova]) contains not ((forced-colors) or (-moz-native-theme)), so rg -v forced-colors drops the values the default theme paints on Windows and macOS, and a bare layer name such as tokens-foundation also matches its -brand and -nova twins. An EFFECTIVE line lists several environments; read it whole.

Do not hand-pair -/+ lines from git show --unified=0. Pair lines only for the consumer CSS files the resolved-value diff does not cover, and confirm each by resolving both sides.

A token’s new value reaches every sheet that reads it, and the resolved-value diff stops at the token. List the readers in both trees (rg -n -g '*.css' -g '*.scss' -e 'var\(--<name>[,)]' browser toolkit; a token or sheet under toolkit/ also reaches Thunderbird, so add searchfox-cli -R comm-central -q '<name>', without the leading dashes, which searchfox-cli takes for an option, and ignore its hits under mozilla/ and suite/), follow a reader that is itself a custom property (--x: var(--<name>)) to its own readers, search for the value’s literal and for “keep in sync” comments (a sheet in a realm that cannot read the token copies its value), and for each one either check it in the environment the value changed in or say why it is left. git grep -- '--<name>' over the whole tree adds the uses outside stylesheets: the theme maps (§3), the built-in theme manifests (references/theme-manifests.md) and tests.

3. Judge in every layer

Before judging a token under a built-in or add-on theme, read css_guidelines “Theme support” and the README’s “Chrome native OS theme”.

The generator emits ten layers; judge a change in each one its realm has. In cascade order (README “Overriding tokens” has how the order is generated): tokens-foundation (in chrome, what Linux’s native theme and lightweight themes paint), tokens-browser-theme (chrome’s in-app light/dark pair, the default on Windows and macOS), tokens-foundation-brand (in-content), their three -nova twins, then tokens-prefers-contrast[-nova] and tokens-forced-colors[-nova]. Which of them paints chrome depends on the theme and the platform: README “Chrome native OS theme” has the table, and §2 in references/token-layers.md how to reach the in-app pair. A generated sheet outside dist/ can switch its Nova layer by its own condition: read §2 “Where the Nova layers apply” in references/nova-overrides.md before judging Nova on a surface that loads one.

Before adding a @layer name to a generated sheet, read the README’s “Overriding tokens”: a name getLayerString does not list outranks the forced-colors and prefers-contrast layers. ./mach theme resolve-token already treats every -moz-pref() context as an override.

Pairing is a real change wherever a layer replaces the pair with fixed values. Many tokens derive from currentColor in the foundation layer only, so pairing a background token with its text counterpart changes nothing there and changes every layer that gives either token a fixed value: the in-app theme, Nova and forced colors.

An add-on theme writes specific tokens; paint a themed surface with the token the theme writes (css_guidelines “Theme support” names the two maps). A different token on a themed surface ignores the theme, however equal it is by default. Find the surface’s property in those maps and use the token it maps to. When a value they write is the defect, the fix goes in the theme’s manifest: under browser/themes/addons/ for a theme built from the tree, and to the theme’s author for one hosted on addons.mozilla.org.

A redefinition of a token name outranks the whole generated stack, forced-colors values included. On the element the token sheet declares on (:root, or a component’s :host), an unlayered redefinition beats every layer. On a descendant element a redefinition wins in any layer, because a declaration on the element beats the value it inherits, so wrapping it in a layer fixes nothing. When a surface misbehaves under one condition only (e.g. forced colors, prefers-contrast, Nova, the in-app theme) or a token change has no effect there, grep the surface’s sheets for a redefinition before suspecting the token, and for every name in its var() chain in that layer (./mach theme resolve-token --name): a redefinition of a base token on the root reaches every token that references it there, including a reference only one layer makes. Prove it at the live document by finding the rule, not by toggling a class on the root, which can switch a whole layered token set: remove the property from the unlayered rule alone and re-read, and if the value snaps to the layered one, the redefinition is the defect. §7 “Find the layer a declaration sits in” in desktop-theme-probing’s references/probe-recipes.md has the probe that finds the rule and its layer.

4. Where a token’s value belongs

A consumer sheet that redefines a token under a condition the token JSON has a key for is doing the token’s job by hand; move the value into a token’s JSON. The keys are light/dark (the color scheme), nativeTheme (-moz-native-theme and lightweight themes), nova (the Nova pref), prefersContrast and forcedColors. A redefinition on the element the token sheet declares on goes into that token’s JSON; one scoped to a single surface goes into that surface’s own component token, since the shared token’s JSON changes every surface. The rule covers design tokens (§2’s isDesignToken check); a sheet-local custom property is not one, whatever its casing suggests. In review, ask for this move before discussing the override’s media query or comment. Under a condition with no key (e.g. a -moz-platform or other platform media feature, a [uidensity] attribute), or one that combines a keyless condition with a keyed one, the value stays in the consumer sheet; scope it with the token layer’s own conditions, plus prefers-contrast and forced-colors where that layer has them as separate layers, so the unlayered rule does not outrank the accessibility values. Judge the reverse patch, which adds tokens and new consumer rules for them, by desktop-theme-colors §4’s pairing by state and by selector. Before writing a high-contrast value into a token’s JSON, read §1 “Writing a high-contrast value into the token’s JSON” in references/token-layers.md.

A derived token resolves where the token sheet declares it, so overriding its base token on an element does not reach it (css_guidelines “Overriding across a shadow boundary” has the mechanism). Under an element that overrides a base token, the tokens that reference it (e.g. its -hover and -active variants, its aliases) keep the root’s value; a write on the root itself, such as an add-on theme’s inline properties, reaches them. Override the derived tokens beside the base, or override the derived token itself. When a patch adds a token derived from a base, or reads one in a rule that did not read it before, and when you judge whether a rule could, search the consumer sheets for elements that redefine the base (rg -g '*.css' -g '*.scss' -e '--<base>\s*:' <dirs>): each one loses its value in the states that read the new token. To confirm one live, set the base on that element in a probe and read the state’s computed value, in an environment where the base’s override differs from the root’s value (--effective shows which; where the native theme gives both the same value, run Linux on the in-app row of desktop-theme-colors §6).

A value that regressed goes back to what it was. When the report says the value was right before, find the revision that changed it (§8 --history) and check its old value against the reporter’s “before” pixels (desktop-theme-screenshots §6) before choosing a reference. A token whose value only looks close paints a different color, and its contrast has not been checked.

Prefer a reference to a repeated value, and pick it by what the target’s name says it paints. The target names the same property and state in the variant the component looks like (a hover background at the same state’s background in the variant it resembles), or the property the part is drawn with (e.g. a fill at a text color, a background at a border color). Such a cross-type reference goes in the token JSON, since use-design-tokens rejects fill: var(--text-color) in a consumer sheet (docs/code-quality/lint/linters/stylelint-plugin-mozilla/rules/use-design-tokens.md, “Token categories”). A literal that equals such a token’s value is a missing reference on any side, forcedColors and prefersContrast included; reference the token once --effective shows it resolving to that value in every environment the side reaches. Check every literal the patch writes, background and text in each state, since finding one missing reference does not settle the others. Where such a token resolves differently, ask whether the two should agree before keeping the literal. Never reference a differently named token because its value matches. Under forced colors many unrelated tokens share each system color, and such a reference drifts once the target’s light, dark, Nova or theme value moves.

A literal that equals an expression over other values (a sum, a difference or a multiple of tokens the rule could reference) is a missing calc(). Equality alone can be coincidence; a commit message or comment stating the relationship confirms it. Ask for the expression, so the value follows when one of its terms changes.

Don’t ask in review to inline a component token that only aliases a shared token: Nova, high-contrast and theme overrides land on the alias later, and other surfaces redefine the component’s colors through it. A component that also reads shared tokens directly is normal.

A wrong Nova value from the Figma export is fixed with a nova key on the base token, or upstream in Figma (§6 before proposing either).

5. rem is not 16px in either realm

A px token and a rem token (the --space-* and --font-size-* scales) match only at a 16px root, which neither realm has, so never call them equivalent without naming the root (design-token README “rem is the system font size in chrome”, css_guidelines “Chrome versus in-content”). A rem token is fractional at most chrome roots (0.125rem is 1.375px at 11px), so round a length built from one where it must be whole. A raw px literal in a use site is a lint error even when the declaration hiding it is not (docs/code-quality/lint/linters/stylelint-plugin-mozilla/rules/use-design-tokens/space.md).

When a raw value becomes a token, take the token the property type’s customFixes in the stylelint plugin’s config.mjs maps it to, even across px and rem (docs/code-quality/lint/linters/stylelint-plugin-mozilla/rules/use-design-tokens.md, “Autofix”). Don’t take a larger one that renders nearer the original at chrome’s smaller root: the whole scale shrinks together, so compensating at one call site breaks its rank against the spacing around it.

Measure; the system font varies. Before quoting what a rem token computes to, read §1 “One launch sweeps every platform’s root size” in references/rem-roots.md.

6. ./mach buildtokens generates and prunes

./mach buildtokens re-derives every *.nova.tokens.json from the committed Figma export and deletes an override that matches its base token; the deletion belongs in your patch (design-token README, “Overriding tokens”). Before committing a pruned *.nova.tokens.json, or reshaping, renaming or deleting a token, run the grep in references/theme-manifests.md: a built-in theme manifest may read the file or the token’s path (README “Built-in theme manifests read token JSON”).

One check settles whether a token patch is complete:

./mach buildtokens && git status --short

Empty output means the committed tree is a fixed point of the generator; otherwise the generator wins. In a tree with untracked files, take git status --short before the run as well and count only what the generator added or changed. Run it on the committed patch: with uncommitted edits the generated files already show as modified, so save git diff before the run and compare it with git diff after. Run the check after every rebase too. A fixed point says nothing about the values the generator wrote: read what the build wrote into *.nova.tokens.json for each token you add, and resolve it with --effective, since the Figma export can already hold Nova values under its name (§1 in references/nova-overrides.md).

When a rebase conflicts only in generated files, resolve the source *.tokens.json and any hand-written consumer sheet, run ./mach buildtokens, git add what it wrote and continue; never hand-merge the generated files. Build with ./mach buildtokens, never npm run build, which skips the build-figma-nova step that rewrites the *.nova.tokens.json files. Before submitting, also run the CI check (node tests/try-runner.js from toolkit/themes/shared/design-system/); it does not cover Nova pruning, so it does not replace the fixed-point check (README “Testing”).

Before accepting or writing a nova or ignoreFigma key, read §1 “A nova block replaces Figma’s Nova values for its token” in references/nova-overrides.md: it has why a side the key omits paints the base value under Nova, and how to price the key and restore the tree afterwards.

7. A token without a Nova value paints its base value for everyone

The generator emits only overridden tokens (design-token README, “Overriding tokens”), so an override sheet references far more than it defines and the rest resolve from a lower layer. Nova is on by default, so a removed Nova override moves every user to the base value: judge the removal by what now paints, not by whether the override sheet still defines the token. For the shared sheets, the EFFECTIVE lines (§2) settle whether a disappearance changes anything. For a generated sheet outside dist/ (New Tab’s _tokens.scss is one), --declared shows whether the shared sheets declare the token, and --effective’s default rows for that sheet’s realm (Nova on), with the sheet’s own Nova condition on (§2 in references/nova-overrides.md), show what now paints; compare them with the removed value. --before REV needs the revision that removed the override: §8 --history finds it.

./mach theme resolve-token \
  --declared --<token> toolkit/themes/shared/design-system/dist/tokens-shared.css <the sheet>

--declared prints yes, no or -- per sheet, the last meaning the file is absent, which generated build outputs often are, so name the checked-in source.

8. A token’s value moves between sheets, so read all three histories

--history <token> [<range>], with no dist directory before it, sweeps all three generated sheets; references/token-history.md has the output format and range rules. Run it on the token that lost its value, which may be one the reported token references through var(). Bound it with --since=<date> a few weeks before the report’s first affected build: an unbounded sweep takes two to three minutes, past a 120 s tool timeout, so give it a timeout of 300 s and tell the user before starting one.

9. Read the patch that introduced what you are removing

The introducing commit tells you two things the diff cannot:

  • What each call site held before, which separates a faithful restoration from an accidental revert of a deliberate fix (e.g. a scale rebase, a rounding cleanup, a tuned value).

  • Which tests are value-sensitive, from its backouts: git log --grep="Bug NNNNNN" | rg -i revert. Run those against your patch, with a baseline.

The introducing patch may itself have changed values while converting them, so compare before it, after it, and at your HEAD, and flag only where your HEAD diverges from after it.

Adding a token with no consumer fails browser_parsable_css.js as well as removing one (css_guidelines “Adding new variables”).

10. Leave the tree clean

A New Tab token change absent at runtime may be a stale source-tree bundle shadowing the objdir copy; New Tab’s docs, browser/extensions/newtab/docs/index.md “Bundles left in the source tree”, say how to find and clear one.

For a live pre-patch baseline, revert the paths by hand as desktop-theme-probing §6 “Leave the tree clean” describes, to the commit §2 “Diff resolved values, not diff lines” names; ./mach theme resolve-token --before needs no baseline in the tree. Never git stash in a shared checkout. If you must detach, verify the branch ref and a clean tree afterwards.