How Hue Codex calculates WCAG contrast

Representative automated fixture coverage

Hue Codex imports versioned JSON fixtures and tests the corresponding pure production functions directly. The groups below are the representative regression evidence most relevant to this methodology.

• Contrast fixtures: Known ratios, threshold boundaries, symmetry, and unrounded pass/fail behavior. View the JSON fixtures.
• Parsing fixtures: Accepted CSS color syntax, alpha behavior, clamping, invalid input, and out-of-gamut fallback cases. View the JSON fixtures.

What a pass means. A passing group confirms the named vectors and tested properties still match the documented implementation. It does not prove every possible input, final browser rendering, full accessibility conformance, profile-aware print output, or every downstream export consumer.

Contrast tools accept concrete CSS colors including alpha HEX, RGB, HSL, HWB, Lab/LCH, OKLab/OKLCH, supported color() profiles, fixed named colors, transparent, and tool-generated colors. Base channels resolve to sRGB for WCAG luminance math, but alpha is retained until the visible foreground/background stack has been composited.

Opacity behavior is explicit per tool. Contrast Checker composites a translucent background over a white reference canvas, then composites the foreground over that rendered background before calculating contrast. Opacity Calculator multiplies embedded foreground alpha by the selected alpha control, resolves a translucent background over white, and then scores the final rendered pair. Gradient contrast is sampled from representative stops and midpoint colors on its stated reference surface, 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.

Highest-contrast candidates compare candidate foreground colors against the selected background and rank them by raw contrast ratio. This label means highest contrast within the offered candidate pool; it does not mean closest visual match to the source color.

The legacy closest-passing helper is the opaque, single-pair HSL-lightness suggestion family implemented by suggestMinimumContrastColor(). It searches HSL lightness steps from 0 to 100 in 0.1 increments while preserving normalized source HSL hue and saturation values. It chooses the passing candidate with the lowest raw ratio that still meets the requested target, then breaks ties by the smallest absolute HSL lightness distance from the source color.

This legacy helper does not optimize a perceptual-distance metric, preserve alpha, or validate multiple contexts. It is not the Color Picker Repair V2 method described below.

Strict Hue Codex heuristic uses 7:1 as a product heuristic for choosing one strict candidate across common text scenarios. It is not a separate WCAG category and it is not automatically the highest-contrast color.

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.
• Strongest available fallback: if no candidate reaches the target, Hue Codex returns the highest raw-contrast candidate and marks the suggestion as not passing the requested target.

Color Picker first resolves the selected Usage into role-specific evidence. Body text, large text, meaningful icons, meaningful borders, focus indicators, interactive accents, surfaces, decorative color, and data series do not share one universal pass rule. Pass, fail, review required, incomplete, and not applicable remain distinct.

For applicable contrast cells, the selected foreground is composited over each exact resolved background with its preserved alpha. Raw ratios decide the result; displayed ratios are rounded afterward. A passing cell covers only the named foreground, background, role, alpha, and threshold.

Disabled content has exemptions and context-dependent treatment rather than one universal Color Picker pass. Focus-ring color alone does not prove focus-indicator size, area, visibility, obstruction, or state change. Data-series review also needs labels, patterns, ordering, separation, and color-vision checks. Decorative colors that carry no information do not acquire a contrast requirement merely because they were entered in the picker.

Color Picker Repair V2 is a deterministic, selected-color-only search. It receives one resolved sRGB source, one to four exact opaque background contexts, preserved foreground alpha, and one applicable target. It never changes a background, typography, focus geometry, state cue, label, or chart encoding.

The search builds a bounded OKLab a/b neighborhood around the source, samples it on a 13 by 13 grid, evaluates both OKLab lightness endpoints, bisects a passing endpoint path 22 times, serializes every evaluated candidate to six-digit sRGB, and locally refines the best serialized candidates in RGB with channel steps 16, 8, 4, 2, and 1.

Every returned repair must pass every supplied context after its exact uppercase six-digit sRGB value is reparsed and its preserved alpha is composited. The engine ranks full-precision metrics calculated from that serialized candidate; rounded display values do not decide the repair.

• Candidate neighborhood radius: max(0.06, source OKLCH chroma x 0.7), clamped to 0.06 through 0.16.
• Local refinement limit: at most 32 improvement iterations per RGB step.
• Output gamut enforced by Repair V2: clipped and quantized sRGB.
• Determinism: identical normalized inputs produce identical candidates and ordering; lexical uppercase HEX is the final tie-break.
• Method version: color-picker-repair-v2; public methodology version 2.0, effective and last reviewed 2026-07-23.

Minimal perceptual change is the lowest Euclidean OKLab distance multiplied by 100 among passing serialized candidates evaluated by V2. This is a perceptually oriented approximation inside a bounded search, not a globally nearest proof or a universal model of human vision. Alpha is fixed and is not part of the distance.

Preserve hue and Preserve chroma are ranking objectives, not exact equality constraints. Preserve hue uses circular OKLCH hue distance across zero and 360 degrees. Preserve chroma uses absolute OKLCH chroma change. Lightness, hue, or chroma may still move when the best passing serialized candidate requires it.

For achromatic resolved sRGB colors, the shared conversion path uses numeric hue zero rather than preserving a separate CSS none or undefined-hue marker. That zero is a serialization convention, not evidence of a meaningful red hue.

All supplied contexts are hard pass constraints. Repair V2 does not average them or accept a majority. The Color Picker role model supplies the maximum finite applicable target to the repair call.

Selected foreground alpha is clamped to the valid range and preserved. Fully transparent foregrounds cannot be repaired by changing hidden RGB channels. A translucent background is resolved over the Color Picker reference canvas before the opaque context is sent to Repair V2.

The required-gamut and mapping-objective controls are decision and export metadata. They are not Repair V2 search inputs. Authored Display P3 or perceptual input is resolved to the selected serialized sRGB repair value; V2 does not optimize Display P3 coordinates.

If the bounded OKLab search has no passing candidate, Repair V2 locally stabilizes its strongest failure in serialized RGB. It moves only for fewer failed contexts or a strictly higher weakest-context raw ratio. A newly passing value enters the normal candidate-refinement path; otherwise the stabilized value remains explicitly labeled failed.

Bounded-search completeness. No repair returned means no passing candidate was found by the evaluated V2 search, including local failure stabilization. It does not prove no sRGB solution exists. The mixed black/white 4.5:1 fixture now records #777777 refining to passing #777676.

Accessibility scope. A repaired color pair does not certify a complete component or page. Final typography, geometry, interaction, labels, non-color cues, actual canvases, states, and assistive-technology behavior still require review.

These rows are assembled from the committed machine-readable fixture generated by the production parser, contrast engine, and Repair V2 implementation. Raw values, displayed values, deltas, alpha, serialized output, and every context remain available in the downloadable JSON.

• 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. Legacy HSL repair and Color Picker Repair V2 are separate Hue Codex heuristics 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))
  closest_passing = null
  strongest_available_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.

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

    # Closest passing adjustment 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 closest_passing is null
         or raw < closest_passing.raw
         or (raw == closest_passing.raw
             and distance < closest_passing.distance):
        closest_passing = {candidate, raw, distance, lightness}

  if closest_passing exists:
    return closest_passing with possible = true
  return strongest_available_fallback with possible = false

repair_v2(source, backgrounds[1..4], alpha, target):
  before = evaluate(serialized_srgb(source), backgrounds, alpha, target)
  if before passes every context:
    return unchanged

  passing = evaluate black and white boundaries
  radius = clamp(max(0.06, source_oklch_chroma * 0.7), 0.06, 0.16)

  for each point in a 13 by 13 OKLab a/b neighborhood:
    for endpoint_lightness in [0, 1]:
      endpoint = evaluate_serialized(endpoint_lightness, a, b)
      if endpoint fails any context:
        continue
      bisect source_lightness toward endpoint 22 times
      retain every serialized passing candidate

  if no passing candidate was evaluated:
    strongest = best failure by failed contexts, weakest ratio, distance, HEX
    stabilize strongest in serialized RGB at steps 16, 8, 4, 2, 1
      move only for fewer failures or a strictly higher weakest ratio
    if strongest now passes:
      retain it as a passing candidate
    else:
      return no repair plus the locally stabilized strongest failure

  for objective in [minimal_oklab, preserve_hue, preserve_chroma]:
    refine the best eight seeds in serialized RGB
      with signed channel steps 16, 8, 4, 2, 1
      and at most 32 improvements per step
    rank with full-precision objective metrics
    break a final tie with lexical uppercase HEX

  return up to three distinct passing serialized candidates

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.

Report a calculation issue

If a result does not match the documented formula or fixture, send the exact input, tool settings, displayed result, expected result, precision mode, and browser details. Please do not include private images, personal information, or secrets.