# Color contrast wcag

`color-contrast-wcag` · version 1.0.0 · Geometry, location & color · free, no key needed

Compute WCAG 2.x relative luminance, contrast ratio, and AA/AAA pass flags for two opaque sRGB colors.

**Use when you need to: compute WCAG color contrast · check text color accessibility · calculate contrast ratio between colors.**

## Decide before calling

Read the [versioned contract](/v1/tools/color-contrast-wcag/versions/1.0.0) and the supported scope below. Reuse `color-contrast-wcag@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `color-contrast-wcag@1.0.0` for compute WCAG color contrast. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- compute WCAG color contrast
- check text color accessibility
- calculate contrast ratio between colors
- test WCAG AA contrast
- test WCAG AAA contrast
- compare foreground and background luminance
- convert sRGB colors to relative luminance

## Not supported

- alpha compositing or translucent colors
- APCA perceptual contrast
- wide-gamut or non-sRGB colors

## Behavior

- Each color is exactly a #RRGGBB string or an object with integer r, g and b channels from 0 through 255; output hex is uppercase.
- Relative luminance uses the WCAG 2.x sRGB transfer breakpoint 0.04045 and coefficients 0.2126, 0.7152 and 0.0722.
- The contrast ratio is (lighter luminance + 0.05) / (darker luminance + 0.05); raw values determine thresholds before formatting.
- Relative luminance strings have exactly six digits after the decimal point and contrast_ratio has exactly two, both rounded by ECMAScript Number toFixed.
- AA thresholds are 4.5 for normal text and 3 for large text; AAA thresholds are 7 for normal text and 4.5 for large text.
- Colors are opaque sRGB only; this tool performs neither alpha compositing nor APCA.

## Input

- `foreground` (string or object, required)
- `background` (string or object, required)

## Output

- `foreground` (object, required)
- `background` (object, required)
- `contrast_ratio` (string, required): pattern `^(?:[1-9]|1[0-9]|2[01])\.[0-9]{2}$`
- `passes` (object, required)

## Limits

- max color text bytes: 7

## Example

Request input:

```json
{
  "foreground": "#000000",
  "background": "#FFFFFF"
}
```

Response:

```json
{
  "result": {
    "foreground": {
      "hex": "#000000",
      "r": 0,
      "g": 0,
      "b": 0,
      "relative_luminance": "0.000000"
    },
    "background": {
      "hex": "#FFFFFF",
      "r": 255,
      "g": 255,
      "b": 255,
      "relative_luminance": "1.000000"
    },
    "contrast_ratio": "21.00",
    "passes": {
      "aa_normal": true,
      "aa_large": true,
      "aaa_normal": true,
      "aaa_large": true
    }
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "color-contrast-wcag",
  "version": "1.0.0",
  "input": {
    "foreground": "#000000",
    "background": "#FFFFFF"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/color-contrast-wcag/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"foreground":"#000000","background":"#FFFFFF"}'
```

The machine-readable contract is at [/v1/tools/color-contrast-wcag/versions/1.0.0](/v1/tools/color-contrast-wcag/versions/1.0.0).

### CLI

```sh
node cli.mjs run color-contrast-wcag 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Point in polygon classify](/tools/point-in-polygon-classify): Classifies a rational-coordinate point as inside, outside, or boundary using an exact half-open ray rule.