Settle what a color paints
Each of the four regimes in css_guidelines “High contrast mode” resolves
differently in a chrome window than in an about: page, and two differ by
platform. Name which regime each side is in before calling chrome and the page
inconsistent. Load desktop-theme-probing before the first live launch (a
./mach theme resolve-token run is not one); it defines the platform files (the probing
machine’s and the target’s) that this skill cites by section.
Read the used value off the live element with the instruments in
desktop-theme-probing §1. Also apply the checks in
accessible/docs/HCMCSSChecklist.md on foreground/background pairs, matching
interaction states, borders, visual effects and SVG colors.
Also load desktop-theme-tokens when the color comes from a design token, and
desktop-theme-screenshots when the result needs showing on the bug.
1. Name the regime, in both realms, before naming the bug
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 the probe, read
css_guidelines “Colors that resolve per realm” and “High contrast mode” with its
“Content area” and “Chrome area” subsections, and the README’s “Chrome native OS
theme”. When the color comes from a theme, built-in or add-on, also read
“Theme support”: a WebExtension theme writes its mapped colors inline on the
root, where only an !important rule or a redefinition on a descendant beats
them, while the default and in-app themes paint from the app’s CSS. Trace the
winning declaration before choosing a manifest fix over a CSS one. This
skill builds on those sections and does not repeat them.
Then run one probe per realm:
const mq = q => matchMedia(q).matches;
return {
forcedColors: mq("(forced-colors)"),
forcedColorsActive: mq("(forced-colors: active)"),
prefersContrast: mq("(prefers-contrast)"),
contrastLevel: ["more", "less", "custom"].find(v => mq(`(prefers-contrast: ${v})`)),
dark: mq("(prefers-color-scheme: dark)"),
};
That is the firefox-probe.py -e shape; desktop-theme-probing §1 has the
others. Read every field: css_guidelines “High contrast mode” says why the two
forced-colors queries and the contrast grades can disagree.
Where no build can run (e.g. a report from a platform you can’t probe on), name
the regime from the report’s preconditions and the rule’s own conditions
instead. ./mach theme resolve-token --effective reads the token
sheets without a launch and prints each candidate regime’s values; say the
regime is inferred, not probed.
Reproduce in the regime the report names. A report’s preconditions (e.g. a
theme, a pref) and its platforms set the regime, and the default on the machine
you probe on is often a different one. Linux defaults to the native theme
(browser.theme.native-theme); Windows and macOS default to the pref off, and a
built-in theme never uses the native theme. The README’s “Chrome native OS
theme” table gives the layer each case paints. A Linux report may come from
either branch, so reproduce both where the changed rule differs between them:
run ./mach theme resolve-token --effective on the tokens the
rule reads and compare the default and -moz-native-theme rows, and check the
rule itself for a (-moz-native-theme) condition. For a report from another
platform than the one you probe on, read that platform’s file
(desktop-theme-probing), section CONTRAST, before choosing a regime. Set the
report’s regime up through §6’s rows before the first reading, and print the
theme and (-moz-native-theme) beside the values.
Design a chrome color probe around desktop-theme-probing §4’s marker values
or the rule matching in its §2 “Reach and read the state” from the start. A
value read names the rule that paints a state only when every candidate rule
computes to a distinct string, and getComputedStyle substitutes var()
references, so two rules resolving to one color read alike; on Linux and macOS a
chrome probe reads the default or prefers-contrast numbers, often equal in
every state, until it puts chrome under forced colors (§2).
2. Simulate the other realm’s regime
Reach either realm’s regime on any platform:
ui.useAccessibilityTheme: an int pref (widget/docs/look-and-feel.md, “Overriding values with prefs”). 1 turnsprefers-contraston in both realms. (ui.prefersContrastdoes not exist.)browser.display.document_color_use: whether the page also gets forced colors (values and per-platform defaults: css_guidelines “High contrast mode”); a Linux or macOS run sets 0 to reach the Windows regime.window.browsingContext.forcedColorsOverride = "active", from chrome JS: css_guidelines “Chrome area” says what it reaches and how to approximate Windows chrome, which is onlyrequested, by settingforced-color-adjust: noneon the chrome root;prefers-contraststays out of it.(forced-colors: active)matches under the override but not in Windows chrome, which matches(forced-colors: requested)and the bare(forced-colors), so check which form a rule uses before trusting a simulated pass. The override covers one window: set it on each window’s ownbrowsingContextand reset each to"none"afterward. Before passing a window to./mach theme check-hcm-colors, read §2 “Putting chrome under forced colors” inreferences/forced-color-filter.md.
All three take effect live. Set ui.useAccessibilityTheme at startup to load
the system colors under it from the beginning; flip document_color_use mid-run
to move the page between regimes without touching chrome.
The simulation reproduces the regime, not Windows’ color set: only under
XP_WIN does an active accessibility theme force the light system colors
(layout/style/PreferenceSheet.cpp). Pin ui.systemUsesDarkTheme=0 when the
measurement stands in for Windows.
Read it as a differential (desktop-theme-probing §4) of the custom
properties the chrome element and the in-page element share, read with
getComputedStyle(el).getPropertyValue(name). A row where chrome reads a system
color and the page reads a literal or a light-dark() of literals has named the
defect. A custom property reads back with its var() references substituted
but light-dark() and color-mix() as written; the color it resolves to in the
current scheme is on a property that uses it, such as borderTopColor.
3. What the forced-color adjustment does to a declaration
Before judging a declaration under forced colors, read css_guidelines “The
forced-color adjustment”.
The filter runs only in the active state, in tweak_when_ignoring_colors
(servo/components/style/properties/cascade.rs), on the longhands marked
ignored_when_colors_disabled in properties/longhands.toml. css_guidelines
“The forced-color adjustment” lists what it keeps, what a rejected value
becomes, which properties it leaves alone, and how it judges a var(), a
color-mix() and a relative color. A ring or separator drawn as a shadow or a
gradient vanishes. references/forced-color-filter.md §1
“What each declaration paints” has the measured rows, and css_guidelines “The
forced-color adjustment” the UA border color per element.
A transparent border used as a spacer paints where the document is active
(a page, or chrome under §2’s override), so a toolbar report is not this case.
Give it a system color matching the surface behind it under
@media (forced-colors: active), as css_guidelines prescribes, after measuring
that surface in the light, dark and stand-in sets (§6). Where the surface
varies so that no one system color matches it, or the border has no reason to
exist in any mode, move the gap into padding (inside the hit area) or margin
(between hit areas; not where adjacent hit areas must touch), which changes how
it snaps (desktop-theme-layout §2 “Device pixels”) and needs that skill’s §1
sweep. Say which fix you chose and why.
forced-color-adjust: none switches off the filter, the text backplate of the
block that carries it, and the replacement of author ::selection and
::target-text colors, and nothing else.
@media (forced-colors) rules and the tokens’ forced-colors layers still apply
under it, and Windows chrome has no filter for it to undo. A none subtree
that still paints filtered colors can be the style cache
(references/forced-color-filter.md §3 “A none subtree can read its
neighbor’s filtered colors”).
An icon follows the regime only through currentColor or a system color in
its fill or stroke, its own or one context paint hands it from the host
(-moz-context-properties; an SVG’s fill="context-stroke" takes the host’s
stroke). Trace a currentColor fill through the element’s color to
its declaring rule (getMatchingCSSRules up the ancestors,
desktop-theme-probing §2 “Reach and read the state”), and resolve a -moz-*
system color as §1 “Two names can be one pair” in
references/system-color-pairs.md says.
4. Pair the system colors per state and per selector
Pairing applies wherever system colors paint, filtered or not: content under
forced colors, Windows chrome under requested, and prefers-contrast. The
pairs, as PAIRS in toolkit/themes/tools/pair_walk.py lists them:
background |
text |
border |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
its |
its |
Two states with correct pairs can still paint the same and look like one state.
Compare each state’s pair with every other state’s on the same element, by
resolved value (two names can be one color: references/system-color-pairs.md
§1); whichever state the patch changed is a finding unless the design asks for
it.
A state shown only by opacity needs its own system color under forced
colors. Forced colors leave opacity alone, so a disabled control faded over
ButtonText paints a color outside the user’s palette. First establish what the
state means by reading the code that sets its class or attribute: a token named
for one state, consumed for another, is itself the finding. Then look for a
token for that state that already varies by regime
(./mach theme resolve-token --effective prints its value in each). A derived token keeps
the root’s value under an element that redefines its base: check per the
derived-token rule in desktop-theme-tokens §4 “Where a token’s value belongs”
before consuming one outside the rule that already reads it, or judging whether
a consumer could. A token that passes can be consumed unconditionally, so
consumers need no @media (forced-colors). Only where no token covers the state
does the consumer sheet give it, under forced colors, its pair at full opacity:
GrayText for disabled content, its icon’s fill included.
Before running ./mach theme check-hcm-colors, read §3 “Per descendant, with
./mach theme check-hcm-colors” in references/system-color-pairs.md for its setup; in chrome on
Linux and macOS that setup includes the override from §2 above, and the walk
exits 1 when an entry judged nothing. Before judging a state, read its §2 “Per
state” and §4 “Per selector”: a diff-only read misses the state the patch left
to an existing rule and the descendants a state repaints. Enumerate the elements
a narrowed selector drops, or a widened one adds, with desktop-theme-probing’s
references/probe-recipes.md §8 “Measure what a changed selector drops or adds”.
When a patch changes a background, check that the text uses the counterpart
designed for it. Between tokens, the use-paired-color-tokens stylelint rule
reports a missing or mismatched counterpart, and
its docs page
says which tokens pair.
The rule can’t see a system color pair (e.g. -moz-dialog with
-moz-dialogtext), or text left on another surface’s system color under a
token background that has no counterpart, so check those from the diff.
A passing ratio doesn’t show that two colors pair. Colors from different pairs
can resolve to the same value in one layer or on one platform and differ in
another. For example, headless Linux resolves -moz-dialogtext to
CanvasText’s value, so dialog text on a box background measures fine there.
Report the mismatch whatever the ratio says.
Judge forced colors by pair membership, and prefers-contrast alone by ratio
where a literal paints. Under forced colors the user’s palette only promises
contrast within a pair, and a local simulation does not resolve to a Windows
theme’s values, so a ratio can only illustrate a finding. Under
prefers-contrast alone the tokens-prefers-contrast layer mixes system colors
with tokens that resolve to literals; measure the ratio wherever a literal
paints, against 7:1, where Gecko_MediaFeatures_PrefersContrast grades more.
In the default regime, a theme’s colors included, judge a text pair against WCAG
AA: 4.5:1, or 3:1 for large text, and a focus ring or separator against its
surface at 3:1 (--non-text). Measure with ./mach theme contrast, never by
hand, and name the palette it was measured on; without a build, or where the
chain ends at a transparent root over a backdrop the OS paints (e.g. Windows
Mica), its --colors mode takes resolved values. --help has the flags, the
state locks, how to get the backdrop values for --colors, and the cases it reports
not judged, which need a pixel sample. Where a sibling paints a state (e.g. a
tab’s .tab-background behind its label), a state entry without --surface
reads the unchanged background and passes; the only sign is a warning on
stderr, so treat that entry as not judged until you rerun it with --surface.
5. Traps when reading a value back
Your measurement is not a resist-fingerprinting user’s (css_guidelines “Colors that resolve per realm”); run §6’s resist-fingerprinting row.
Read
outline-stylebeforeoutline-color(css_guidelines “Focus rings”): an element no author rule gives an outline style reads the token’s color and paints the accent (SelectedItemandCanvasTextin high contrast). Set the style with the color:outline: var(--focus-outline).A
::part()rule from the outer tree beats the shadow tree’s own rule (css_guidelines “Overriding across a shadow boundary”) unless the shadow rule is!important. Read a part’s value with both sheets in place.Before removing a declaration as redundant with a shared rule, list the rules that set the property on the element with the declaration in place (
desktop-theme-probing§2 “Reach and read the state”, “prove the rule applies”): the shared rule may lose to another rule there. When it loses, removing the declaration changes the computed value, and a pixel diff clears that only for the consumers captured. In a shared sheet, read what the sheet itself feeds the property into and capture a consumer that keeps it.A computed outline or inset shadow can be covered. A container’s inset outline paints over its in-flow children but under a positioned child with
z-indexauto or non-negative, whether or not the container itself is positioned, and an insetbox-shadowpaints under any child that has a background. Read it off pixels, through a compositor grab where the child is a page (desktop-theme-screenshots§2).
6. Judge the fix in every regime, then restore the prefs
Check that each cell moves the way it should (desktop-theme-probing §5).
Measure each cell’s ratio with ./mach theme contrast (§4), never by hand: one
run per row, light or dark side and variant, each with its own --setup-file
that sets the row’s live state (e.g. §2’s override, the scheme prefs). To judge
a revision you have not applied, set its changed declarations inline on the
subject in that setup file, so the before and after runs differ by those lines.
document_color_use is browser.display.document_color_use:
regime |
how to reach it |
|---|---|
default |
both prefs at their defaults, read back (§1); also pin and read back the prefs the host’s platform file ( |
prefers-contrast, no forced colors |
|
forced colors (the Windows regime) |
|
forced colors, content only |
|
forced colors, chrome only |
§2’s override; this row separates forced colors from |
prefers-contrast |
|
stand-ins, content only |
|
resist fingerprinting |
|
light and dark |
|
chrome and web content in different schemes |
|
lightweight or system theme |
|
built-in in-app theme |
an |
system accent color |
|
in-app light/dark pair on Linux |
|
native theme on Windows or macOS |
|
a backdrop the OS paints (e.g. Windows Mica) |
|
When the fix is in a shared sheet, run every row in both realms, the healthy one
included; for a token change, a realm where no sheet reads a changed token is
out. A change inside a conditional block (such as @media (forced-colors) or a
-moz-pref() block) needs before and after only in the rows where the condition
holds, plus one other row to confirm it does not apply there; moving a
declaration out of one needs every row, and each difference is a visible change
to report. A fix that changes only lengths needs only the rows that change
whether the affected ink paints (§3: forced colors paints a transparent border
or outline and drops a shadow) or what a changed length computes to (a
conditional block in the sheets that style the element). Add the light and dark
side of each row when the surface uses light-dark(), and the density and scale
axes of desktop-theme-layout §1 when the fix touches a length.
On Linux and macOS, take chrome’s forced-colors answer from the chrome-only row, and a Windows palette’s from a Windows try run.
Restore every pref, set any forced-colors override back to "none", and delete
any scratch probe (desktop-theme-probing §6).