Nova layers and overrides
Nova is the shipped look: browser.nova.enabled defaults to true, and the
-nova layers, the *.nova.tokens.json files, the nova key and the Figma
import build it. The pref-off path is unmaintained.
1. A nova block replaces Figma’s Nova values for its token
Paths in this section are relative to toolkit/themes/shared/design-system/.
The nova key’s shape and what ignoreFigma means are in
toolkit/themes/shared/design-system/docs/README.design-tokens.stories.md
“Overriding tokens”.
src/figma-import.mjs, the build-figma-nova step, runs in every
./mach buildtokens before the CSS build, after the import that only
--import-figma adds, and rewrites each *.nova.tokens.json from the
curated export, except for a token with a nova key or ignoreFigma on its
base value, which it skips wholesale (walkUpdateNovaTokens). The same README’s
“Importing from Figma” says which export the build reads and what
--import-figma brings in besides the change you meant; read it before standing
in for a Figma update. The export has no native-theme mode, so the importer
copies the base token’s nativeTheme into each Nova entry it writes: change it
in the base *.tokens.json, and the next build copies it into the Nova file. A
token it skips gets no copy, so a nova block has only the nativeTheme
written into it. The export also holds entries for tokens no code declares yet,
which the importer applies to the first token added under that name.
ignoreFigma changes the generated Nova sheets on every build.
A nova block without nativeTheme paints its light and dark values in the
native and lightweight themes too. The generator splits a value into the
native-theme and in-app layers only when it has a nativeTheme
(config/helpers/desktop-format/should-transform-browser-theme-value.mjs), so
the whole value lands in tokens-foundation-nova and
tokens-browser-theme-nova gets no declaration. Write nativeTheme into the
block whenever the base token has one. Any other side the block leaves out is
missing from the Nova CSS, where the base value paints instead, and from the
Figma export, where config/helpers/figma-format/transform-token-value.mjs
substitutes the literal string transparent for a light or dark value it cannot
find, and for a forcedColors value that is absent when light and dark differ,
so dist/tokens-figma-theme.json and dist/<id>/tokens-figma-theme.json (which
the Figma token importer reads) hold a color the browser never paints. The
export cannot tell a lossy transparent from a genuine one, so resolve the
token.
Price a nova or ignoreFigma key before accepting it, in a committed
tree: delete the key, run ./mach buildtokens, and read what the generator
writes into the component’s *.nova.tokens.json and into the Nova layer of
dist/tokens-shared.css; that is what the key suppresses.
./mach theme resolve-token <dist> --before HEAD shows the same as resolved values
against the committed tree. Repeat every side you do not mean to change inside
the nova value beside the key you do, then restore everything the generator
rewrote, not only dist/. It writes under every root of COMPONENT_TOKEN_PATHS
(config/helpers/general/token-paths.mjs) and into the New Tab Nova sheet:
git checkout HEAD -- toolkit/themes/shared/design-system toolkit/content/widgets \
browser/themes/shared browser/extensions/newtab/content-src/styles/nova
./mach buildtokens && git status --short # back at the fixed point
A sibling block that omits a side has the same defect. The fixed-point check in
SKILL.md §6 “./mach buildtokens generates and prunes” cannot catch it: the
export is the generator’s output, so it is already at the fixed point.
2. Where the Nova layers apply
The shared sheets declare their Nova layers under -moz-pref(), which parses
only in the sheets css_guidelines lists, whatever document loads it
(css_guidelines “Chrome-only media features go by the stylesheet, not the
document”). Every page that links them by chrome:// URL, in-content pages
included, therefore paints the Nova layers while browser.nova.enabled is on,
the default.
A generated sheet outside dist/ can declare its Nova layer under a condition
of its own: New Tab’s _tokens.scss declares @layer tokens-foundation-nova
under a root class, not -moz-pref(). Read the condition off the sheet’s
selector and trace what sets it, so the probe reaches that layer.