How to choose a readable text color for any background

Start with the background that users will actually see

A color token is only an input. The relevant background is the color behind the glyphs after CSS variables, opacity, overlays, gradients, images, blending, and component state have been resolved. A card declared as white may sit below a translucent layer and render as pale blue. Text declared as black at 70% alpha is no longer #000000 after compositing. Measuring the declarations without resolving that rendering chain can produce a confident answer to the wrong question.

• Identify the exact component, state, viewport, and theme being tested.
• Resolve the text color and every layer behind it to effective rendered colors.
• Record the source tokens as well as the effective foreground and background.
• Repeat the test for hover, focus, selected, disabled, error, dark-theme, and responsive variants when they change either color.
• Treat gradients, photographs, video, and patterned surfaces as ranges of backgrounds rather than one sampled color.

Compare candidates by ratio, not by hue or intuition

The WCAG contrast ratio compares the relative luminance of the lighter rendered color with the darker one. It ranges from 1:1 for equal luminance to 21:1 for black against white. Hue names, HSL lightness, and personal impressions cannot replace this calculation. A saturated blue and a saturated yellow can both use 50% HSL lightness while producing radically different luminance and therefore different text choices.

For ordinary text, WCAG 2.2 Success Criterion 1.4.3 requires at least 4.5:1 at level AA. Large-scale text has a 3:1 threshold under that criterion. Enhanced level AAA uses 7:1 for ordinary text and 4.5:1 for large-scale text. Compare the unrounded ratio with the required number; round only the label shown to a reader. A displayed 4.5:1 may still fail if its full value is 4.48:1.

• Choose the conformance target and text class before comparing candidates.
• Calculate each candidate against the same effective background.
• Discard candidates below the applicable threshold instead of ranking them as almost acceptable.
• Among passing candidates, choose by hierarchy, brand system, and readability in context.
• Keep the measured values with the design decision so it can be reviewed later.

Tested black and white choices on common backgrounds

Black and white are useful first candidates because one of them always has strong mathematical contrast against an opaque sRGB background, but they are not interchangeable. The table uses the WCAG 2.2 relative-luminance formula, compares full-precision values, and displays four decimals. “Better” means the higher ratio of these two candidates; it does not claim that the resulting component meets every accessibility requirement.

Do not stop at an automatic black-or-white switch

A binary switch is a safe baseline for many generated swatches, but a product usually has more constraints. Pure black can feel unnecessarily harsh on a nearly white reading surface; pure white may create too much emphasis for secondary text on a dark panel. The correct workflow is to test the actual candidates from the design system. A softer neutral is acceptable only if its own measured ratio passes the target—being derived from a passing black token proves nothing.

• List the allowed foreground tokens for primary, secondary, interactive, inverse, and status text.
• Calculate every token against the resolved background rather than altering the background silently.
• Filter by the required threshold, then preserve intentional hierarchy among the remaining choices.
• If no brand candidate passes, change the foreground, the background, or add a controlled surface behind the text.
• Avoid algorithms that continuously lighten or darken a brand color until a number passes; the output may drift outside the reviewed palette and still fail in another state.

const candidates = ["#17181C", "#4F46E5", "#FFFFFF"];
const threshold = 4.5;

const passing = candidates
  .map((foreground) => ({
    foreground,
    ratio: contrastRatio(foreground, background),
  }))
  .filter(({ ratio }) => ratio >= threshold)
  .sort((a, b) => b.ratio - a.ratio);

// Choose from `passing` by semantic role; do not round before filtering.

Transparency, gradients, and photos need a range test

Alpha colors must be composited before luminance is calculated. CSS Color 4 defines simple alpha compositing channel by channel. The effective color depends on both the translucent foreground and what lies below it, so a token such as rgb(0 0 0 / 60%) has no single contrast ratio on its own. Parent opacity can modify both text and its background, and multiple translucent layers must be resolved in their paint order.

• Composite translucent text over the effective background, then compare the resulting text color with that background.
• Composite translucent overlays and backgrounds from the bottom layer upward before testing the text.
• For a gradient, test the minimum ratio across the complete area occupied by each line of text.
• For photographs or video, sample representative and worst-case content or introduce an opaque or controlled translucent scrim.
• Lock dynamic art direction when possible; a contrast result for one hero image does not transfer to the next image.

Text size changes the threshold, not the rendered evidence

WCAG defines large-scale text using rendered size and weight, not an HTML heading level or a design-tool label. Under Success Criterion 1.4.3, large-scale text can use 3:1 at level AA, but body copy normally needs 4.5:1. Do not promote text to the large category merely because it is bold, important, or visually prominent. Test the computed font size and weight of the actual element.

• Use the ordinary-text threshold by default.
• Apply the large-scale exception only after confirming the rendered size and weight.
• Retest when responsive CSS reduces the font on a smaller viewport.
• Measure placeholder, helper, error, badge, and button text separately when they use different tokens.
• Remember that inactive controls, logos, decorative text, and incidental text have narrowly defined exceptions; an exception is not a general design shortcut.

The text ratio also does not certify icons, focus indicators, input borders, charts, or other visual information. Non-text Contrast has its own scope and 3:1 requirements for covered user-interface components and graphical objects. Color must not be the only way important meaning is communicated. Keyboard behavior, semantics, zoom, reflow, and real usability remain separate checks.

A repeatable foreground-selection checklist

• Name the component, locale, theme, viewport, state, and exact text style.
• Resolve the final foreground and all background layers, including alpha and overlays.
• Classify the content and select the applicable AA or AAA threshold.
• Calculate full-precision ratios for every permitted foreground candidate.
• Reject candidates below the threshold before applying brand or hierarchy preferences.
• For variable backgrounds, test the least favorable region occupied by the text.
• Verify responsive and interactive states that change color, size, weight, or imagery.
• Record the source colors, effective colors, ratio, threshold, result, and review date.
• Continue with non-text contrast, non-color cues, semantics, keyboard, zoom, and human review.

This process scales because the factual step is deterministic and the design step remains explicit. Color Atlas exposes exact ratios for catalog colors and keeps the primary W3C references beside the explanation. Use those numbers to eliminate failing candidates quickly, then inspect the selected text in the real component. A passing ratio is necessary evidence for the criterion being tested, not a promise that the page, product, or organization is certified.