Token layers: the high-contrast JSON keys, which layer each theme paints

1. Writing a high-contrast value into the token’s JSON

The prefersContrast and forcedColors keys of a value object, and of the value inside a nova block, feed the tokens-prefers-contrast[-nova] and tokens-forced-colors[-nova] layers (toolkit/themes/shared/design-system/docs/README.design-tokens.stories.md “High Contrast Mode (HCM) media queries”). The trigger is any value side, base or nova, that writes a literal (e.g. color-mix(), light-dark(), a hex) where a reference used to supply high-contrast handling, or where its sibling tokens have it. The fix is a forcedColors or prefersContrast entry that references a token with the handling:

"nova": {
  "comment": "color-mix with currentColor cannot be expressed in Figma",
  "value": {
    "nativeTheme": "color-mix(in srgb, currentColor 22%, transparent)",
    "default": "{<another token>}",
    "forcedColors": "{<a token that has the handling>}"
  }
}

A token’s comment lands above its declaration in every layer, so put a derivation of one side’s value in the commit message (README “JSON format deep dive”).

Verify with ./mach buildtokens and read the diff of the generated *.tokens.css: it should contain the declarations the hand-written block did, and the block in the consumer sheet then goes.

2. Which layer each theme kind paints

toolkit/themes/shared/design-system/docs/README.design-tokens.stories.md The default theme paints tokens-foundation on Linux, where browser.theme.native-theme is true, and the in-app layer on Windows and macOS; Light and Dark paint the in-app layer everywhere; Alpenglow and add-on themes paint tokens-foundation; forced colors swaps in the default theme. README “Chrome native OS theme” has the table, and the in-app layer’s selector and media query. Each layer’s -nova twin paints over it while browser.nova.enabled is on, which it is by default.

--setpref browser.theme.native-theme=false reaches the in-app layer on Linux and changes nothing on Windows and macOS, where the pref is already false. Tell the regime from the root: lwtheme without theme-in-app is a lightweight theme, which still reads (-moz-native-theme) false; theme-in-app with no lwtheme is the native or the in-app theme, and (-moz-native-theme) tells them apart. Setting lwtheme on the root with no theme-in-app drops a probe back to the foundation layer the way a lightweight theme does.

A system theme and a lightweight theme share the foundation layer, so only a nativeTheme value controls them, and a bug filed against either says nothing about the in-app pair. Put a value that follows the system or lightweight theme in nativeTheme and the fixed in-app color in light/dark (README “Chrome native OS theme”); git grep -l nativeTheme -- '*.tokens.json' lists the tokens with this shape.