use-paired-color-tokens (stylelint)

This rule requires that the background and text color design tokens styling one surface are used as the semantic pair they were designed as: a block that paints its background with a token that has a paired text color token declares that text color, and a text color declared beside a token background is the background’s counterpart.

Paired tokens share a name apart from the background-color / text-color part, so --button-background-color-primary-hover pairs with --button-text-color-primary-hover. A pair is guaranteed to have sufficient contrast in every theme, in dark mode, under prefers-contrast and under forced-colors — high contrast mode, which applies to chrome windows on Windows and to about: pages on every platform. Combining one half with an unrelated token is not, and neither is leaving the text to whatever color an ancestor happens to supply. Either way the mismatch usually only shows up in the theme the author did not try.

Rule Scope

The rule checks the declarations that win the cascade within one declaration block, and reports the following.

A background token used without a text color. A block that paints a background claims a surface, and it owes that surface a text color. The rule reports a block whose winning background or background-color declaration reads a background token that has a paired text color token, and which sets no color; the message names the counterpart. A background token without a counterpart is meant to combine with whatever the surface inherits, so it makes no claim to report.

A background and text color that are not counterparts. Where the block sets both halves, the rule reports two tokens that are not each other’s counterpart, whether they come from different components (--sidebar-background-color with --panel-text-color) or from different variants of one component (--button-background-color-menu with --button-text-color). A component with any text color token has one for every background variant, which the design system’s tests enforce, so the message can always name the counterpart.

A state variant that inherits the wrong text color. A block selected by a state that repaints the background and sets no color takes its text color from the rule it nests in. The rule walks up to the nearest enclosing color and reports it when it reads a text token that pairs with some other background, or another variant of the background’s component. --button-text-color-hover and --button-text-color are separate tokens that can resolve to entirely different values under forced-colors:

.action {
  color: var(--button-text-color);

  &:hover {
    /* Reported: the inherited text color pairs with the base background. */
    background-color: var(--button-background-color-hover);
  }
}

Tokens without a counterpart make no pairing claim and are left alone. That covers most of the global --background-color-* and --text-color-* tokens, which are meant to combine freely, and any value that is not a design token. A component that declares a base text color has a counterpart for every background variant, which the design system’s own tests enforce. A global token that does have a counterpart is paired like any other, so --background-color-list-item-hover still has to go with --text-color-list-item-hover.

None of the checks applies to a block that sets only a text color. That block is usually a descendant of the element painting the background, which the rule cannot see.

Declarations directly inside an at-rule are checked as their own block, since a @media query can paint a background the rule around it does not. A nested rule matches a different element and stands on its own.

Exemptions of the missing-text-color check

A block selected by a state — :hover, :focus, [open], [disabled] and their kin — usually restyles an element its base rule has already given a text color, so it is exempt from the missing-text-color check, along with any block nested inside it. Where it nests in that base rule, the inherited text color is checked as described above. Where the base rule is a flat sibling (.action:hover {} beside .action {}), or the nesting reaches no color, nothing is checked. Read that as a gap in the rule, not as permission: declare both halves in a state variant too. A negated state such as :not(:hover) names the base state itself, so a block selected that way owes the surface a text color and is reported. Pair checking applies to state variants like any other block.

The element an at-rule paints is the one its enclosing rule matches, so for this check a color on that rule covers what the at-rule paints:

.card {
  color: var(--panel-text-color);

  @media -moz-pref("browser.nova.enabled") {
    /* Fine: the color above applies to this element in every query. */
    background-color: var(--panel-background-color);
  }
}

A block can hand the surface a text color through a custom property instead of a color declaration, which is how a component that renders the text in its own shadow tree takes one. Defining a paired text token, or a property that reads one, satisfies the check:

.new-badge {
  background-color: var(--badge-background-color-filled);
  --badge-text-color: var(--badge-text-color-filled);
}

Examples of incorrect usage for this rule

#header {
  background-color: var(--sidebar-background-color);
}

.menu-item {
  background-color: var(--button-background-color-menu);
  color: var(--button-text-color);
}

Examples of correct usage for this rule

#header {
  background-color: var(--sidebar-background-color);
  color: var(--sidebar-text-color);
}

.menu-item {
  background-color: var(--button-background-color-menu);
  color: var(--button-text-color-menu);
}

.card {
  background-color: var(--panel-background-color);
  color: var(--text-color-deemphasized);
}

Autofix functionality

Where the text color is missing, --fix declares the counterpart of the background token, after the declaration that paints the surface:

/* Before autofix */
#header {
  background-color: var(--sidebar-background-color);
}

/* After autofix */
#header {
  background-color: var(--sidebar-background-color);
  color: var(--sidebar-text-color);
}

Where the text color is the wrong half of a pair, --fix swaps it for the background’s counterpart:

/* Before autofix */
.menu-item {
  background-color: var(--button-background-color-menu);
  color: var(--button-text-color);
}

/* After autofix */
.menu-item {
  background-color: var(--button-background-color-menu);
  color: var(--button-text-color-menu);
}

The counterpart is fixed by the design system rather than chosen by the author, and the missing-text-color check reports only where that counterpart exists, so the declaration to insert is determined. What the block alone does not say is whether the surface takes its text color from elsewhere on purpose, where inserting one is a silent rendering change. A surface like that carries the disable comment described below, which stylelint honours for fixes as well as reports.

Two cases are reported without a fix: a violation against a token that does not exist, since choosing between the component’s base text color and a new token is the author’s call, and a background declaration whose line ends in a comment, since the insertion would take the comment onto the new line.

Disabling the rule

Prefer declaring the color. The tempting disable is the one that reasons about what the block contains — this element holds no text, its icon takes the color from a fill below, a child element colors itself. Those are all easy to falsify: markup changes, forced-colors turns a translucent wash into an opaque ButtonFace, and the next person to put a text node in the element inherits whatever happens to be there. Declaring the counterpart costs one line and is usually value-neutral in the default theme.

A ::part() is not an exception to that. A ::part() rule in the outer tree overrides the component’s own declaration for that part, so a block repainting a part’s background sets the color in the same block:

.section-context-menu.context-menu-open > moz-button::part(button) {
  background-color: var(--button-background-color-ghost-hover);
  color: var(--button-text-color-ghost-hover);
}

moz-select.css is the in-tree example to follow: its panel-item[selected]::part(button) sets background-color and color together on the element panel-item.css gives background-color: transparent and color: inherit.

Where a component remaps a background token into its own palette, remap the text counterpart beside it, rather than pairing the remapped background with the palette’s own text token:

panel-list {
  --button-background-color-hover: var(--smartwindow-panel-item-background-color-hover);
  --button-text-color-hover: var(--panel-list-text-color);
}

That leaves the disable worth writing, for a block where declaring the color would do damage or would not resolve at all, and for a surface that genuinely needs an unpaired combination:

/* The tracker count below takes the box text color; a color here would recolor
   the shield. */
/* stylelint-disable-next-line stylelint-plugin-mozilla/use-paired-color-tokens */
background-color: var(--urlbar-box-background-color);

/* The dropdown sits on the toolbar, not on the panel it belongs to. */
/* stylelint-disable-next-line stylelint-plugin-mozilla/use-paired-color-tokens */
color: var(--toolbar-text-color);

The comment must name what setting a color here would break, or where the color comes from instead, in terms a reviewer can check. If the surface should have a text color of its own but the token does not exist, or the pair you want does not exist, file a bug for the missing token and reference it from a TODO.