How Hue Codex calculates WCAG contrast

Contrast tools accept parsed sRGB colors from HEX, RGB-style CSS input, HSL-style input, Lab/LCH, OKLab/OKLCH, and tool-generated colors. Every accepted input is normalized to an opaque sRGB HEX value before contrast math runs.

Opacity behavior is tool-specific. Contrast Checker expects resolved opaque foreground and background colors; it does not composite transparent color input. Opacity Calculator composites the transparent foreground over the selected background, then calculates contrast for the effective color pair. Gradient contrast is sampled from representative gradient stops and midpoint colors, so it is a warning signal rather than proof for every pixel.

Relative luminance is calculated by converting each 8-bit sRGB channel into a 0 to 1 encoded value, applying the WCAG sRGB linearization curve, then weighting the linear red, green, and blue channels with 0.2126, 0.7152, and 0.0722.

The WCAG 2.2 breakpoint for the piecewise sRGB channel conversion is 0.04045. Older WCAG references sometimes show 0.03928; Hue Codex uses 0.04045.

Contrast ratio is (lighter luminance + 0.05) divided by (darker luminance + 0.05).

Hue Codex compares the raw ratio with the target threshold. The displayed ratio is rounded to two decimal places for readability, but the raw value decides pass or fail.

Text contrast is evaluated from the source foreground and background colors obtained from the user agent, markup, or stylesheets, not from anti-aliased screenshot pixels. Anti-aliasing, font smoothing, thin strokes, and unusual fonts can make rendered text appear fainter than the nominal CSS color pair.

WCAG defines large-scale text as at least 18pt normal text or 14pt bold text, or equivalent size for CJK fonts. W3C Understanding SC 1.4.3 gives the CSS conversion as 1pt = 1.333px, so 18pt is approximately 24px and 14pt is approximately 18.5px.

For each 8-bit sRGB channel C8:
  CsRGB = C8 / 255

  if CsRGB <= 0.04045:
    Clinear = CsRGB / 12.92
  else:
    Clinear = ((CsRGB + 0.055) / 1.055) ^ 2.4

L = 0.2126 * Rlinear + 0.7152 * Glinear + 0.0722 * Blinear

contrast_ratio = (max(Lforeground, Lbackground) + 0.05)
               / (min(Lforeground, Lbackground) + 0.05)

WCAG 1.4.11 Non-text Contrast applies a 3:1 adjacent-color contrast target to visual information required to identify component states, including authored focus indicators.

WCAG 2.2 SC 2.4.13 Focus Appearance is a separate Level AAA criterion. It requires a visible focus indicator area at least as large as a 2 CSS pixel thick perimeter of the unfocused component or sub-component, and a 3:1 contrast change between the same pixels in the focused and unfocused states.

The Hue Codex Focus Ring Contrast tool checks contrast only: ring color against the page background and ring color against the component fill. It does not calculate focus-indicator area, prove the 2px perimeter-equivalent size, evaluate focused-vs-unfocused pixel changes, check obstruction, or verify that every keyboard-focusable component has a visible indicator.

Best text suggestions compare candidate foreground colors against the selected background and rank them by raw contrast ratio. Adjustment helpers search HSL lightness steps from 0 to 100 in 0.1 increments while preserving the source HSL hue and saturation values.

For opaque contrast suggestions, Hue Codex chooses the passing candidate with the lowest raw ratio that still meets the requested target. Ties are broken by the smallest absolute HSL lightness distance from the source color. If raw ratio and distance are both tied, the earlier dark-to-light candidate remains selected.

The all-checks recommendation uses 7:1 as a Hue Codex product heuristic for choosing one strict candidate across common text scenarios. It is not a separate WCAG category.

Accessible pair finding ranks foreground/background combinations by pass state and contrast. The ranking is useful for screening palettes, but final roles still need real component review.

• Search direction: dark to light, evaluating lightness 0.0, 0.1, 0.2, ... 100.0 without stopping early.
• Hue and saturation: copied from the normalized source HSL value; only HSL lightness changes during the search.
• Clamping and rounding: hue is normalized, saturation and lightness are clamped to valid HSL ranges, then RGB channels are rounded and clamped into six-digit sRGB HEX.
• Closest means absolute HSL lightness distance from the source color, measured in percentage points; it does not mean Delta E, RGB distance, or OKLCH distance.
• Fallback: if no candidate reaches the target, Hue Codex returns the strongest raw-contrast candidate and marks the suggestion as best effort.

• A ratio of 4.499:1 does not pass a 4.5:1 threshold, even if it displays near 4.5 after rounding.
• Hue Codex uses source colors for contrast math. Anti-aliased screenshots and subpixel-rendered glyph edges are not sampled as the pass/fail source of truth.
• Anti-aliasing, thin type, image text, textured backgrounds, and gradients can reduce practical readability.
• Disabled controls, logos, brand marks, and incidental text can have different WCAG treatment than ordinary readable UI text.
• Color contrast does not replace labels, icons, focus visibility, state affordances, or color-vision review.

These equations and steps are the reproducible contrast path. The suggestion algorithm is a Hue Codex heuristic layered on top of the standards-based contrast formula.

srgb_to_linear(channel_8bit):
  v = channel_8bit / 255
  if v <= 0.04045:
    return v / 12.92
  return ((v + 0.055) / 1.055) ^ 2.4

relative_luminance(hex):
  r, g, b = hex_to_rgb(hex)
  return 0.2126 * srgb_to_linear(r)
       + 0.7152 * srgb_to_linear(g)
       + 0.0722 * srgb_to_linear(b)

contrast_ratio_raw(foreground, background):
  fg = relative_luminance(foreground)
  bg = relative_luminance(background)
  lighter = max(fg, bg)
  darker = min(fg, bg)
  return (lighter + 0.05) / (darker + 0.05)

wcag_score(foreground, background):
  raw = contrast_ratio_raw(foreground, background)
  return {
    display_ratio: round(raw, 2),
    normal_AA: raw >= 4.5,
    normal_AAA: raw >= 7,
    large_AA: raw >= 3,
    large_AAA: raw >= 4.5,
    ui_AA: raw >= 3
  }

suggest_minimum_contrast_color(target, fixed, minimum_ratio = 7):
  target_hex = normalize_hex(target)
  fixed_hex = normalize_hex(fixed)
  target_hsl = rgb_to_hsl(hex_to_rgb(target_hex))
  best = null
  fallback = null

  # Search direction is dark to light.
  # Step size is 0.1 HSL lightness from 0.0 through 100.0.
  # Hue and saturation are copied from target_hsl for every candidate.
  # hsl_to_rgb normalizes hue, clamps s/l to valid ranges,
  # rounds RGB channels, and rgb_to_hex clamps to displayable sRGB.
  for step from 0 to 1000 inclusive:
    lightness = step / 10
    candidate = rgb_to_hex(hsl_to_rgb({
      h: target_hsl.h,
      s: target_hsl.s,
      l: lightness
    }))
    raw = contrast_ratio_raw(candidate, fixed_hex)
    distance = abs(lightness - target_hsl.l)
    # "Closest" means this absolute HSL lightness distance,
    # not Delta E, RGB distance, or OKLCH distance.

    # Fallback chooses strongest available raw contrast.
    # Tie-breaker: closest HSL lightness to the source.
    # Exact ties keep the earlier dark-to-light candidate.
    if fallback is null
       or raw > fallback.raw
       or (raw == fallback.raw and distance < fallback.distance):
      fallback = {candidate, raw, distance, lightness}

    # Opaque passing candidate chooses the lowest raw passing ratio.
    # Tie-breaker: closest HSL lightness to the source.
    # Exact ties keep the earlier dark-to-light candidate.
    if raw >= minimum_ratio:
      if best is null
         or raw < best.raw
         or (raw == best.raw and distance < best.distance):
        best = {candidate, raw, distance, lightness}

  if best exists:
    return best with possible = true
  return fallback with possible = false

These vectors use the WCAG relative-luminance formula and compare unrounded raw ratios against the relevant threshold. Displayed ratios can round to two decimals, but pass/fail must use the raw value.

Tools using this methodology

These Hue Codex tools link to this methodology because they depend on the formulas, assumptions, limits, or data policy described here.