--- name: desktop-theme-tokens description: Design tokens and CSS variables - picking one for a hard-coded value, *.tokens.json edits, Nova/Figma overrides, buildtokens, value-neutral diffs; one undefined or ineffective on a surface; finding the revision that changed a token's value; a Firefox::Theme or Toolkit::Themes bug, even when the report already names the rule or token. allowed-tools: - Bash(./mach theme resolve-token:*) - Bash(./mach python --virtualenv wpt .claude/skills/desktop-theme-probing/scripts/firefox-probe.py:*) - Bash(./mach python --virtualenv wpt .agents/skills/desktop-theme-probing/scripts/firefox-probe.py:*) --- # 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: tries to reference ` 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`](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: ```sh ./mach theme resolve-token \ toolkit/themes/shared/design-system/dist --effective -- ``` 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. ```sh cd tools/lint/stylelint/stylelint-plugin-mozilla ../../../../mach node -e 'import("./helpers.mjs").then(h => console.log(h.isDesignToken("--")))' ``` `--before REV` diffs against the sheets committed at `REV` and moves nothing in the tree: ```sh ./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 ...` 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`](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\(--[,)]' browser toolkit`; a token or sheet under `toolkit/` also reaches Thunderbird, so add `searchfox-cli -R comm-central -q ''`, 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(--)`) 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 -- '--'` over the whole tree adds the uses outside stylesheets: the theme maps (§3), the built-in theme manifests ([`references/theme-manifests.md`](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`](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`](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`](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 '--\s*:' `): 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`](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`](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: ```sh ./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`](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`](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`](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. ```sh ./mach theme resolve-token \ --declared -- toolkit/themes/shared/design-system/dist/tokens-shared.css ``` `--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 []`, with no `dist` directory before it, sweeps all three generated sheets; [`references/token-history.md`](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=` 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.