Pairing system colors per state and per selector
The recipe behind SKILL.md §4 “Pair the system colors per state and per
selector”.
1. Two names can be one pair
Resolve a name the way Windows does, since the
forced-colors pairing is judged there: in NativeGetColor of
widget/windows/nsLookAndFeel.cpp, the IsHighlightColor() and
IsHighlightTextColor() predicates list the IDs that collapse onto
COLOR_HIGHLIGHT and COLOR_HIGHLIGHTTEXT, and the switch below them maps
the rest; there is no ID to COLOR_* table to grep. desktop-theme-probing’s
platform-windows.md, section CONTRAST, lists the names that resolve to one
color under high contrast, so compare states by resolved value, not by name.
2. Per state
For each state the surface has (e.g. default, hover, active, focus, selected, checked, disabled, open), including the states the patch leaves to an existing rule, list the background, the text, the icon fill and the outline that resolve together under forced colors, and every descendant the surface shows only in some modes or states (e.g. a label, a badge). A row that mixes pairs is a finding, and so is a state that recolors the text but not the icon fill, or the reverse.
3. Per descendant, with ./mach theme check-hcm-colors
Walk every descendant a state repaints. A patch that moves a state’s
background onto a new pair leaves each descendant with its own color or
fill on the old one, often in a rule the diff never touched.
In chrome on Linux and macOS, pass a --setup-file that sets SKILL.md §2’s
override (forced-color-filter.md §2 “Putting chrome under forced colors”).
The prefs reach only the prefers-contrast regime there. Without the override
the walk still judges a surface whose resolved color equals a system color, and
exits 1 for an entry that judged nothing (checked: 0), so read
regime.forcedColorsActive before taking a clean walk as a forced-colors check.
./mach theme check-hcm-colors locks the state, maps each
visible descendant’s surface to its system colors and lists every foreground
outside that pair; its --help has what it checks and its flags. It locks a
pseudo-class state only in chrome, so a --realm content run takes
--state default and exits 1 on any other state. The walk matches surfaces to
pairs by this platform’s values, so two pairs that share a value here pass a
mix of them, and a clean walk is a verdict on this palette only.
4. Per selector
Pair by selector as well as by state. A new declaration and the one it pairs
with must match the same elements, so compare their selectors’ scope; a member
of a selector list that can never be in the state (not hit-testable, or the
state attribute never lands on it) pairs nothing. Copy the replaced rule’s own
conditions (e.g. a :not() exclusion, an attribute or ancestor scope) into the
new selector, or the new value paints in the mode the old one skipped. An
element that a more specific rule exempts from the declaration you replace (the
old value reset in the same state) needs the same exemption from the new one, so
search the sheets for other rules in that state that set the property.