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.