The short answer: a contrast ratio is a test, not a conformance decision

Testing a color token against WCAG 2.2 really means testing a pair made of a foreground and a background color. The ratio is computed with a formula and compared with the thresholds without rounding: at AA, 4.5:1 for normal text and 3:1 for large text; at AAA, 7:1 for normal text and 4.5:1 for large text; and 3:1 for UI components and graphical objects. In this article a working example tests those pairs across two themes and several states.

A boundary is needed here. A contrast ratio is only one part of WCAG 2.2 conformance: keyboard use, zooming, focus, not conveying information by color alone and much more are tested by separate criteria. A contrast ratio is also not a legal compliance decision, nor the result of another algorithm such as APCA. This article does not discuss legal obligations or deadlines; it only describes the criteria in W3C's own texts and a way to test them.

Last checked: 25 October 2026. The colors and token names are an original design example, not a measurement of a real site. All examples are limited to opaque sRGB colors: computing with this formula on a semi-transparent color that has not first been composited onto its background gives no valid result. More on that in the third section.

From token to test: pair, threshold and scope

Design systems usually keep color as semantic tokens: --text, --muted, --link, --surface. A single token gives no meaningful contrast ratio; the ratio is between two colors. So you first write down which foreground token is used on which background token: that is a pair. The pair is tied to a kind that says which threshold applies: text or UI component.

WCAG 2.2 contrast thresholds (from W3C documents, 25 October 2026)
CriterionLevelFor whatThreshold
1.4.3 Contrast (Minimum)AANormal text and images of text4.5:1
1.4.3 Contrast (Minimum)AALarge-scale text3:1
1.4.6 Contrast (Enhanced)AAANormal text7:1
1.4.6 Contrast (Enhanced)AAALarge-scale text4.5:1
1.4.11 Non-text ContrastAAVisual information required to identify UI components and states; parts of graphics required to understand the content3:1, against adjacent colors

According to W3C, large-scale text is at least 18 point or 14 point bold; the Understanding page says these are roughly 24 px and 18.5 px (1 point = 1.333 px). The font size is the size when the content is delivered; a zoom the user applies later does not count.

Two distinctions are a source of mistakes. The first is the difference between text and non-text: 1.4.3 and 1.4.6 apply to text, while 1.4.11 applies to a component's boundary, a focus ring or a part of a graphic. The same color can have two different thresholds: a button's text needs 4.5:1, while the button's border (if it is needed to identify the component) needs 3:1. The second is that 1.4.11 compares against adjacent colors: for a component, the colors next to the component; for a graphic, the colors next to the graphic.

Without the kind and the size of the pair, a ratio cannot be interpreted. A --muted text needs 4.5:1 in 16-pixel body text; the same pair may pass at 3:1 in a heading of at least 18 point regular or 14 point bold. Do not round the approximate pixel equivalent down to decide whether text is large; at the boundary use the CSS point size. If you use fluid typography (for example with clamp()), whether a text counts as large text depends on its size at that screen width; generate and check the range with the CSS clamp generator. Not counting text as large at its smallest size and using the normal threshold is a design choice, not a rule W3C states.

The math: relative luminance and the contrast ratio

The WCAG 2.2 formula is explicit. Each channel is converted from 0–255 to 0–1 (RsRGB = R8bit/255). If the value is 0.04045 or below it is divided by 12.92; otherwise (value + 0.055) / 1.055 is raised to the power 2.4. Relative luminance is 0.2126·R + 0.7152·G + 0.0722·B. The contrast ratio is (L1 + 0.05) / (L2 + 0.05), where L1 is the luminance of the lighter color and L2 of the darker one. The ratio ranges from 1:1 to 21:1. W3C also notes that this threshold used to be 0.03928 and that the change has no practical effect.

The script below runs this for two themes and ten cells. The cells cover the default, hover and focus states, plus a disabled button. For each cell it prints the ratio at three decimals; for text pairs it prints the AA, large-text AA and AAA thresholds, for UI pairs the 3:1 threshold, and for the inactive component EXEMPT. The decision uses >= on the unrounded ratio.

WCAG 2.2 contrast ratios of token pairs for two themes (offline, synthetic design example, opaque sRGB)Python
01THEMES = {02    "light": {"surface": "#ffffff", "text": "#1c2733", "muted": "#6c7886", "link": "#0b57d0", "link-hover": "#0842a0",03              "btn-bg": "#1a62d6", "btn-hover": "#1450b0", "btn-fg": "#ffffff", "dis-fg": "#a4adb8", "dis-bg": "#eef1f4",04              "border": "#8793a0", "border-hover": "#5f6b78", "ring": "#0b57d0"},05    "dark": {"surface": "#12161c", "text": "#e7edf3", "muted": "#8f9bab", "link": "#8ab4f8", "link-hover": "#a8c7fa",06             "btn-bg": "#8ab4f8", "btn-hover": "#a8c7fa", "btn-fg": "#0b1220", "dis-fg": "#5a6572", "dis-bg": "#1b2027",07             "border": "#466586", "border-hover": "#8f9bab", "ring": "#8ab4f8"},08}09CELLS = [  # (pair, state, foreground token, background token, kind)10    ("text", "default", "text", "surface", "text"),11    ("muted", "default", "muted", "surface", "text"),12    ("link", "default", "link", "surface", "text"),13    ("link", "hover", "link-hover", "surface", "text"),14    ("button", "default", "btn-fg", "btn-bg", "text"),15    ("button", "hover", "btn-fg", "btn-hover", "text"),16    ("button", "disabled", "dis-fg", "dis-bg", "inactive"),17    ("border", "default", "border", "surface", "ui"),18    ("border", "hover", "border-hover", "surface", "ui"),19    ("focus", "focus", "ring", "surface", "ui"),20]21LEVELS = {"text": {"AA": 4.5, "AA-large": 3.0, "AAA": 7.0}, "ui": {"UI": 3.0}}22 23 24def channel(value):25    s = value / 25526    return s / 12.92 if s <= 0.04045 else ((s + 0.055) / 1.055) ** 2.427 28 29def luminance(color):30    r, g, b = (int(color[i:i + 2], 16) for i in (1, 3, 5))31    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)32 33 34def ratio(foreground, background):35    light, dark = sorted((luminance(foreground), luminance(background)), reverse=True)36    return (light + 0.05) / (dark + 0.05)37 38 39for theme, tokens in THEMES.items():40    for pair, state, fg, bg, kind in CELLS:41        value = ratio(tokens[fg], tokens[bg])42        if kind == "inactive":43            verdict = "EXEMPT"44        else:45            verdict = " ".join(f"{name}={'PASS' if value >= need else 'FAIL'}" for name, need in LEVELS[kind].items())46        print(f"{theme:<6}{pair:<7}{state:<9}{value:7.3f}  {verdict}")47 
Output of the script as runOutput
01light text   default   15.136  AA=PASS AA-large=PASS AAA=PASS02light muted  default    4.498  AA=FAIL AA-large=PASS AAA=FAIL03light link   default    6.386  AA=PASS AA-large=PASS AAA=FAIL04light link   hover      9.141  AA=PASS AA-large=PASS AAA=PASS05light button default    5.582  AA=PASS AA-large=PASS AAA=FAIL06light button hover      7.489  AA=PASS AA-large=PASS AAA=PASS07light button disabled   2.003  EXEMPT08light border default    3.129  UI=PASS09light border hover      5.439  UI=PASS10light focus  focus      6.386  UI=PASS11dark  text   default   15.386  AA=PASS AA-large=PASS AAA=PASS12dark  muted  default    6.433  AA=PASS AA-large=PASS AAA=FAIL13dark  link   default    8.611  AA=PASS AA-large=PASS AAA=PASS14dark  link   hover     10.555  AA=PASS AA-large=PASS AAA=PASS15dark  button default    8.884  AA=PASS AA-large=PASS AAA=PASS16dark  button hover     10.890  AA=PASS AA-large=PASS AAA=PASS17dark  button disabled   2.760  EXEMPT18dark  border default    2.995  UI=FAIL19dark  border hover      6.433  UI=PASS20dark  focus  focus      8.611  UI=PASS

Two cells stand out in the output. In the light theme muted is 4.498, below the AA normal text threshold, but it passes the 3:1 large-text threshold: this token is enough in a 24-pixel heading and not enough in 16-pixel body text. If you round to two decimals you see 4.50, yet W3C states plainly that computed values should not be rounded: 4.499:1 does not meet the 4.5:1 threshold. In the dark theme border is 2.995, below 3:1; even though it shows as 3.00 at two decimals it does not meet the non-text contrast requirement (W3C: 2.999:1 does not meet the 3:1 threshold).

The fix is usually a one-step adjustment: darken muted a little in the light theme, or lighten the border a little in the dark theme, and test again. This article does not say which value is right; the example tokens are a design example and belong to no brand. To try a single pair quickly there is the color contrast checker; it calculates the WCAG 2.2 ratio of two colors and shows the AA and AAA results for normal and large text in words.

Scope limit: the script is for 6-digit opaque sRGB hex colors. For a semi-transparent (alpha) foreground or background you must first composite the color onto the background it actually sits on; computing with the hex equivalent of an uncomposited rgba() value gives a wrong result. This article does not describe the compositing method; for tokens that use alpha, do the math on the composited opaque color. W3C's 1.4.3 Understanding page has no explanation about alpha colors.

I also verified the math separately: the output of the Python script was compared with an implementation of the same formula written with 50-digit decimal and with a separate implementation written in Node.js. The ratios came out equal within 1e-9 and the decisions are identical. This is a verification of the math; it does not mean your page conforms to WCAG.

The theme matrix: light and dark

Light and dark themes side by side, five pairs in each: text 15.136 and 15.386; muted 4.498 (Fail) and 6.433; link 6.386 and 8.611; btn-fg / btn-bg 5.582 and 8.884; border 3.129 and 2.995 (Fail). Each row shows a color sample, the hex values, the ratio, the threshold and the word Pass or Fail.
The same token names map to different colors in the two themes and the pair is re-tested in each theme: muted text in the light theme and the input border in the dark theme fall below the threshold.

The same token name maps to a different color in each theme, so every pair is tested again in every theme. In the diagram five pairs sit side by side across two themes: in the light theme muted fails, in the dark theme border fails. A pair that passes in one theme may not pass in the other.

A common dark-theme mistake is to derive a pair by inverting a pair that passes in the light theme and assuming the ratio is preserved. Inverting the RGB channels of both colors does not preserve the ratio; recalculate the new pair with the formula. Simply swapping the foreground and background roles of the same two colors does preserve the ratio.

You can also test the theme switch and the token table in continuous integration: generate the script's THEMES dictionary from your design token file and run the same loop. Whether a failing cell stops the build (for example, only AA counting as an error) is your team's decision.

The state matrix: default, hover, focus and disabled

State matrix for the light theme: four rows (link text, button text, muted text, input border) and four columns (default, hover, focus, disabled). The link passes at 6.386 and 9.141; the button passes at 5.582 and 7.489 and the disabled button is exempt at 2.003; muted text fails at 4.498; the input border passes at 3.129 and 5.439; the focus ring passes at 6.386.
Every cell gives the ratio and the decision in words; inactive components are exempt and the focus ring needs 3:1 against the adjacent background.

States are where text rules and non-text rules mix most. The matrix in the diagram shows four rows across four states for the light theme and gives the ratio and the decision in words in every cell; color alone carries no decision.

Hover: if a link's color changes, the new color is also tested with the text rule, that is 4.5:1; in the diagram link-hover passes at 9.141. For a non-text border it is different: W3C says additional author-supplied hover treatments are considered supplemental and do not themselves need to meet 3:1, but adds that the component must not lose contrast with the adjacent colors.

Focus: under 1.4.11 the focus indicator must have sufficient contrast against the adjacent background when the component is focused; the criterion does not directly compare the focused and unfocused states. In the diagram the focus ring passes at 6.386. Whether a focus indicator exists is a job for a separate criterion: 2.4.7 Focus Visible requires that any keyboard-operable interface has a mode of operation where the focus indicator is visible, and it does not specify the form of the indicator. 2.4.13 Focus Appearance (AAA), added in WCAG 2.2, gives guidance on size and shape; this article does not test it.

Disabled: for text that is part of an inactive user interface component 1.4.3 requires no contrast, and 1.4.11 also exempts inactive components. In the diagram the disabled button's ratio is 2.003 and the decision is Exempt. That is not an excuse to ignore visibility when you design the disabled state; it is only an exception for these two criteria.

Color must also not carry information alone. 1.4.1 Use of Color (Level A) requires that color is not the only visual means of conveying information, indicating an action or distinguishing a visual element. One sufficient technique for telling inline links apart from surrounding text is to use a contrast ratio of at least 3:1. That is why every cell in the diagram gives its decision in words and with an icon as well as color: Pass, Fail, Exempt.

What a contrast ratio does not cover

What does a contrast ratio not cover?
TopicWhy it is separate
Semi-transparent colorsThey must first be composited onto the background they actually sit on; this article is limited to opaque sRGB.
Images and gradients behind textW3C describes backgrounds that give insufficient contrast as failure F83 and measures contrast against the specified background the text is rendered over in normal usage; this article's script tests solid backgrounds.
Logos and brand names1.4.3 and 1.4.6 have no contrast requirement for them.
Pure decoration and text nobody can seeThe same criteria exempt them.
APCA and other algorithmsThis article only covers the WCAG 2.2 contrast ratio; another algorithm may give a different result.
WCAG conformance and legal complianceA contrast ratio is only one input to these; this article does not describe legal obligations or deadlines.

This list is kept short: each row marks a question that this article's script does not answer. The script saying "pass" for a pair does not mean the pair passes everywhere it is used; it is only true for the two stated colors and the stated threshold.

Manual checks: zoom, keyboard and a colorless look

A formula tests contrast; it does not test usability. A few things need a manual look. Zoom: 1.4.4 Resize Text (AA) requires that text can be resized without assistive technology up to 200 percent without loss of content or functionality; the browser's full-page zoom is one example, and above 200 percent zoom may be more effective than text resizing. Open the page at 200 percent and check that button labels, the focus ring and everything painted with tokens stay in place and legible.

Keyboard: move through the page with Tab and Shift+Tab only. Is the focus indicator visible on every interactive element (2.4.7), and does its color meet 3:1 against the adjacent background in both the light and the dark theme (1.4.11)? Repeat these checks per theme. The accessible interactions article covers the HTML side of keeping focus visible.

A colorless look: look at the page with color information switched off; can you still tell states such as error, selected or required? This is the practical test for 1.4.1, not part of the formula. On the typography side, heading hierarchy and font-size decisions are covered in typography in the interface; you can also check the page's heading structure with the heading hierarchy checker. That tool is not about contrast; it is part of the same manual review.

Connecting it to a token system, and the share image

Three steps are enough to connect the working example to your own token file: read the tokens into a dictionary, write the pairs and thresholds explicitly (which pair is text, which is a UI component) and stop or report the build on a failing cell. Treating the disabled state as exempt is a decision; write it down so the next person knows why.

The share image is a separate job: the Open Graph image generator creates an exact 1200×630 pixel image and gives a contrast warning. That warning is for the text in the image; it is not a WCAG test of your site's tokens.

Limitations and a working checklist

The limits of this article are explicit. I did not measure any real site; the colors and token names are an original design example. The sources are W3C's WCAG 2.2 text and the related Understanding pages; thresholds and definitions are written as they stood on 25 October 2026. Alpha colors, images and gradients behind text, APCA, legal obligations and deadlines are out of scope. No item is a guarantee of WCAG conformance, legal compliance or accessibility.

  • Every color token is tested within a pair: the foreground, the background and the kind (text or UI component) are written down.
  • The threshold decision uses the unrounded ratio; borderline values such as 4.498 or 2.995 do not count as a pass.
  • Normal text 4.5:1, large-scale text (18 point or 14 point bold) 3:1; where AAA is targeted, 7:1 and 4.5:1.
  • UI component boundaries, focus rings and required graphical parts are 3:1 against the adjacent colors.
  • Every pair is tested separately in the light and the dark theme; the dark theme does not rest on a ratio assumed by inverting colors from the light theme.
  • Hover, focus and disabled states are tested in separate cells; the exemption of an inactive component is a written decision.
  • State is not conveyed by color alone; there is also text, an icon or a shape.
  • Semi-transparent colors were composited onto the background first; the script is used only for opaque sRGB.
  • 200 percent zoom and keyboard navigation were checked by hand; a contrast ratio does not replace them.

Sources and check date

The W3C pages below were read on 25 October 2026. Last checked: 25 October 2026.

  1. W3C: Web Content Accessibility Guidelines (WCAG) 2.2
  2. W3C WAI: Understanding SC 1.4.3 Contrast (Minimum)
  3. W3C WAI: Understanding SC 1.4.6 Contrast (Enhanced)
  4. W3C WAI: Understanding SC 1.4.11 Non-text Contrast
  5. W3C WAI: Understanding SC 1.4.1 Use of Color
  6. W3C WAI: Understanding SC 1.4.4 Resize Text
  7. W3C WAI: Understanding SC 2.4.7 Focus Visible

No real site's colors or accessibility were measured for this article; the token names and colors are an original design example limited to opaque sRGB. The WCAG 2.2 Recommendation is dated 12 December 2024; the update dates of the Understanding pages can differ and may have changed since, so verify the current state there. A contrast ratio does not replace WCAG conformance, legal compliance or another algorithm such as APCA; the article describes no legal obligation or deadline.

✳

Write the pair and the threshold first, then test with the unrounded ratio; let words, not color, carry the decision.

Explore more articles ↗