HWB colors: whiteness and blackness in CSS

Treat HWB as an sRGB editing model

HWB means hue, whiteness, and blackness. CSS Color 4 defines it as another way to specify an sRGB color: begin with the fully saturated sRGB hue, mix in a proportion of white, and reserve a proportion for black. The result remains inside sRGB, so HWB does not unlock Display P3 or other wide-gamut colors. Its value is operational. A picker can expose a stable hue while a person adjusts how much of the result comes from the white and black ends of the range.

• Hue uses the same circle as HSL, including the same uneven visual spacing between numeric angles.
• Whiteness raises the minimum sRGB channel and moves the result toward white while the color remains opaque.
• Blackness lowers the maximum available channel and moves the result toward black while the color remains opaque.
• HWB resolves to sRGB, so an equivalent HEX or rgb() value can represent every opaque HWB result.
• HWB coordinates are editing controls, not accessibility evidence; contrast must be calculated from the resolved rendered colors.

Write the space-separated syntax and keep alpha separate

The function is written hwb(H W B / A). Hue accepts an angle or a unitless number interpreted as degrees; angles outside one turn wrap to the same position. Whiteness and blackness are clearest as percentages. Alpha follows a slash and defaults to 100% when omitted. Unlike hsl(), HWB has no legacy comma-separated form: commas inside hwb() make the value invalid. Modern CSS also permits the none keyword for a missing component, but none is not a synonym for zero and is mainly relevant when colors are interpolated.

:root {
  --action: hwb(210 10% 20%);
  --action-translucent: hwb(210 10% 20% / 60%);
  --action-wrapped-hue: hwb(570deg 10% 20%); /* Same hue as 210deg */
}

/* Invalid: HWB does not have a comma syntax. */
.invalid-example {
  color: hwb(210, 10%, 20%);
}

Raise whiteness and watch the foreground threshold

Hold hue at 210 degrees and blackness at 20%, then increase whiteness. The largest resolved channel stays at 80% while the smaller channels rise. The table follows the CSS Color 4 HWB-to-sRGB algorithm, rounds each channel to the nearest 8-bit value, and then calculates contrast from that rounded HEX with the WCAG relative-luminance formula. AA for normal text requires at least 4.5:1.

• The foreground changes between 10% and 20% whiteness for this particular hue and blackness.
• At 10% whiteness, black reaches only 4.37:1 while white reaches 4.81:1; rounding the input percentage does not make both safe.
• The 40% step gives black 6.99:1, which passes AA but is just below the 7:1 AAA threshold for normal text.
• Test every semantic state independently; the same foreground cannot be assumed safe across a generated HWB ramp.
• Keep unrounded contrast values for pass/fail decisions and round only the displayed documentation.

Raise blackness without confusing it with opacity

Now hold hue at 210 degrees and whiteness at 10%. Increasing blackness reduces the available contribution from the pure hue while the minimum channel remains near 10%. Every row is still fully opaque. That is fundamentally different from lowering alpha: a translucent color reveals an unknown backdrop, but a higher-blackness HWB value already resolves to a complete sRGB triplet. The foreground switches in the opposite direction as the scale gets darker.

Normalize whiteness plus blackness at 100%

The most important HWB edge case appears when W + B is at least 100%. CSS does not reject the color. Instead, it normalizes the two amounts by their sum and returns an achromatic result whose three sRGB channels equal W / (W + B). The original hue cannot affect that gray and is therefore powerless. This means values with different totals but the same W:B ratio can resolve to the same color once they cross the boundary.

• The first row is the normalization example defined in CSS Color 4: 40 / (40 + 80) produces one-third gray.
• Equal whiteness and blackness always normalize to 50% gray once their sum reaches the boundary.
• Do not encode a semantic hue in an achromatic token; changing the angle cannot change the rendered result.
• If a generated scale is intended to retain hue, validate W + B < 100% before publishing it.
• Avoid repeated round trips through rounded HWB percentages because the W:B ratio can drift near the boundary.

Convert between RGB, HWB, and HSL without losing the source

For an sRGB color, HWB whiteness is the smallest normalized RGB channel and blackness is one minus the largest channel. Hue is derived from the channel difference using the same hue geometry as HSL. The conversion is deterministic, but display-friendly rounding is not reversible. Preserve one canonical representation at sufficient precision, then derive the alternatives for documentation and copy controls instead of repeatedly overwriting the source.

Ship HWB tokens with resolved evidence

A practical HWB token set keeps the editable coordinates, a resolved sRGB fallback, and tested foreground results together. Direct property declarations can put HEX first and HWB second, allowing software that does not understand the later value to retain the earlier declaration. This fallback does not solve alpha contrast and it does not make an untested scale accessible; every final rendered state still requires its own evidence.

:root {
  --action: hwb(210 10% 20%);
  --action-muted: hwb(210 30% 20%);
  --action-dark: hwb(210 10% 40%);
  --on-action: #FFFFFF;
  --on-action-muted: #000000;
}

.action {
  color: #FFFFFF;
  background: #1A73CC;
  background: var(--action); /* 4.81:1 with white */
}

.action-muted {
  color: var(--on-action-muted);
  background: #4D8CCC;
  background: var(--action-muted); /* 5.94:1 with black */
}

• Keep W + B below 100% whenever the selected hue must remain visible.
• Store the canonical HWB coordinates with enough precision and export rounded HEX as a derived sRGB value.
• Test normal, hover, active, selected, focus, disabled, light-theme, and dark-theme foreground pairs separately.
• Resolve alpha against the actual backdrop before calculating luminance or contrast.
• Do not call HWB wide-gamut or perceptually uniform; it inherits the gamut and hue limitations of its sRGB foundation.
• Use HSL when saturation and model lightness are the intended controls, and OKLCH when perceptual spacing is the requirement.
• Link the conversion specification and retain unrounded audit values so a future generator can reproduce the result.