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.