# Colour Contrast Checker

> Computes the WCAG 2.1 contrast ratio between a foreground and a background colour from their relative luminance (sRGB linearised) and checks it against the AA and AAA thresholds for normal text, large text and non-text UI components.

- Calculator id: `color-contrast` · Category: Developer & IT (`developer`) · Tool name: `calculate_color_contrast`
- Canonical page: https://tttkmbb.com/developer/color-contrast · This document: https://tttkmbb.com/developer/color-contrast.md · JSON definition: https://tttkmbb.com/developer/color-contrast.json

## Purpose

Computes the WCAG 2.1 contrast ratio between a foreground and a background colour from their relative luminance (sRGB linearised) and checks it against the AA and AAA thresholds for normal text, large text and non-text UI components.

**Use when:** You are choosing text or button colours for a website or app and need to verify accessibility compliance (WCAG 1.4.3, 1.4.6, 1.4.11).

**Do not use when:** Colours have transparency (composite them onto the background first), you need perceptual difference (ΔE) or colour-space conversion (use color-converter).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `foreground` | string |  | required | Hex colour: #RRGGBB or #RGB shorthand, with or without the #. |
| `background` | string |  | required | Hex colour: #RRGGBB or #RGB shorthand, with or without the #. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `contrast_ratio` | number |  | (L_lighter + 0.05) / (L_darker + 0.05), from 1 (identical) to 21 (black on white). |
| `contrast_ratio_text` | string |  | The ratio written as n:1. |
| `luminance_foreground` | number |  | WCAG relative luminance of the foreground, 0 (black) to 1 (white). |
| `luminance_background` | number |  | WCAG relative luminance of the background. |
| `aa_normal_text` | boolean |  | Passes SC 1.4.3 for text below 18 pt (24 px) regular or 14 pt (18.66 px) bold. |
| `aa_large_text` | boolean |  | Passes SC 1.4.3 for large text. |
| `aaa_normal_text` | boolean |  | Passes SC 1.4.6 enhanced contrast for normal text. |
| `aaa_large_text` | boolean |  | Passes SC 1.4.6 for large text. |
| `ui_components` | boolean |  | Passes SC 1.4.11 non-text contrast for icons, borders and focus indicators. |
| `rating` | string |  | Summary of the highest level passed. |
| `foreground_normalized` | string |  | Foreground as #RRGGBB. |
| `background_normalized` | string |  | Background as #RRGGBB. |

## Formula

`For each channel c = value/255: c_lin = c/12.92 if c ≤ 0.03928 else ((c + 0.055)/1.055)^2.4; L = 0.2126·R_lin + 0.7152·G_lin + 0.0722·B_lin; contrast = (L1 + 0.05) / (L2 + 0.05) with L1 ≥ L2`

WCAG 2.1 definitions of relative luminance and contrast ratio for sRGB colours; thresholds 4.5:1 / 3:1 (AA), 7:1 / 4.5:1 (AAA) and 3:1 for non-text elements. The ratio is not rounded before comparison, so 4.48:1 fails AA normal text.

## Data Sources

- WCAG 2.1 – Contrast ratio and relative luminance definitions (W3C) — https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio (standard, retrieved 2026-09-24)
- W3C – Understanding Success Criterion 1.4.3: Contrast (Minimum) — https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html (standard, retrieved 2026-09-24)
- W3C – Understanding Success Criterion 1.4.11: Non-text Contrast — https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html (standard, retrieved 2026-09-24)

Data freshness: `static`. Deterministic formula with fixed constants; results never go stale. Inputs supplied by the caller determine the output.

## API

- `GET https://tttkmbb.com/api/v1/calculate/color-contrast?foreground=…&background=…`
- `POST https://tttkmbb.com/api/v1/calculate/color-contrast` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/color-contrast · OpenAPI operationId `calculate_color_contrast` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "color-contrast", "inputs": {…}}`

## Example

- Black on white: inputs `{"foreground":"#000000","background":"#ffffff"}` → `{"contrast_ratio":21,"luminance_foreground":0,"luminance_background":1,"aa_normal_text":true,"aaa_normal_text":true,"ui_components":true,"contrast_ratio_text":"21:1"}`
- #777777 on white: inputs `{"foreground":"777777","background":"fff"}` → `{"contrast_ratio":4.48,"luminance_foreground":0.1845,"aa_normal_text":false,"aa_large_text":true,"aaa_normal_text":false,"aaa_large_text":false,"ui_components":true,"foreground_normalized":"#777777","background_normalized":"#FFFFFF"}`

```
GET https://tttkmbb.com/api/v1/calculate/color-contrast?foreground=%23000000&background=%23ffffff
```

## Limitations

Colours have transparency (composite them onto the background first), you need perceptual difference (ΔE) or colour-space conversion (use color-converter). WCAG 2.1 definitions of relative luminance and contrast ratio for sRGB colours; thresholds 4.5:1 / 3:1 (AA), 7:1 / 4.5:1 (AAA) and 3:1 for non-text elements. The ratio is not rounded before comparison, so 4.48:1 fails AA normal text. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**What counts as large text?**

At least 18 pt (24 px) regular or 14 pt (about 18.66 px) bold; large text only needs 3:1 for AA and 4.5:1 for AAA.

**Does swapping foreground and background change the ratio?**

No, the formula always divides the lighter luminance by the darker one, so the ratio is symmetric.

**Why does #777777 fail even though it looks readable?**

Its ratio on white is 4.48:1, just under the 4.5:1 AA threshold; #767676 (4.54:1) is the lightest grey that passes.

## Related

- [Color Converter](https://tttkmbb.com/conversion/color-converter.md) — Convert between hex, RGB and HSL before checking contrast.
- [CSS Unit Converter](https://tttkmbb.com/developer/css-units.md) — Font sizes that decide whether text counts as large.