# burgee/contrast

> Every export of burgee/contrast, with its signature and doc comment: mix, ratio, check, report, fieldColorAt, auditBurgee and 3 more, plus 2 types.

Source: https://burgee.interlace.tools/docs/api/contrast

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

Contrast, as a thing the package checks rather than a thing someone remembers.

A burgee is a mark whose charge sits ON its own field, and whose field sits on
a page nobody here controls. Both of those are contrast relationships, and
both are easy to get wrong in a way that looks fine at 512px and fails at 24.
This module measures them, so `burgee brand` can refuse to emit a flag that
would not clear the floor and CI can hold ours to the same line.

WCAG 2.2 sets 4.5:1 for body text and 3:1 for large text and for the parts of
a graphic you need in order to understand it. A logo's bars are the latter, so
3:1 is the floor used here — see `AA`.

The measuring is `roundel`'s, not ours. Colour is the layer below this one, and until
2026-09-09 both packages carried the same forty lines of WCAG luminance — identical
constants, identical maths, differing only in which package name the hex error says.
What is left here is the part that is actually about a burgee: which pairs of a flag's
own colours have to clear the floor, and how to say so to a person running `burgee brand`.

```ts
import { mix, ratio, check, … } from 'burgee/contrast';
```

## Functions

### auditBurgee

Every contrast relationship a burgee has to survive.

Two are intrinsic — each bar against the field beneath it — and hold wherever
the flag is used. The rest depend on where it is placed, so pass the grounds
the flag will actually fly on and they are checked too. A flag that passes the
intrinsic pair and fails a ground has a page problem, not a logo problem.

```ts
function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];
```

| Parameter | Type |
| :-- | :-- |
| `brand` | `AuditInput` |
| `grounds` (optional) | `readonly string[]` |

**Returns** `ContrastFinding[]`

### check

```ts
function check(what: string, a: string, b: string, required?: 3): ContrastFinding;
```

| Parameter | Type |
| :-- | :-- |
| `what` | `string` |
| `a` | `string` |
| `b` | `string` |
| `required` (optional) | `3` |

**Returns** `ContrastFinding`

### contrast

The WCAG contrast ratio between two colours. Order does not matter.

```ts
function contrast(a: string, b: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |

**Returns** `number`

### fieldColorAt

The field colour at a point along the gradient axis, for stops given in order.

```ts
function fieldColorAt(stops: ReadonlyArray<{
    offset: number;
    color: string;
}>, at: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `stops` | `ReadonlyArray<{ offset: number; color: string; }>` |
| `at` | `number` |

**Returns** `string`

### luminance

WCAG relative luminance.

```ts
function luminance(hex: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `hex` | `string` |

**Returns** `number`

### mix

Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science.

```ts
function mix(a: string, b: string, t: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |
| `t` | `number` |

**Returns** `string`

### ratio

Round to 2dp for reporting, without pretending to more precision than that — roundel's `round2`.

```ts
function ratio(a: string, b: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |

**Returns** `number`

### report

One line per finding, aligned, for a terminal or a failing test.

```ts
function report(findings: readonly ContrastFinding[]): string;
```

| Parameter | Type |
| :-- | :-- |
| `findings` | `readonly ContrastFinding[]` |

**Returns** `string`

## Constants

### AA

The floors WCAG 2.2 sets, as ratios.

```ts
const AA: {
    /** Body text against its background. */
    readonly TEXT: 4.5;
    /** Large text, UI components, and meaningful parts of a graphic. */
    readonly GRAPHIC: 3;
};
```

## Interfaces

### AuditInput

```ts
interface AuditInput {
    mark: {
        lead: string;
        follow: string;
    };
    field: ReadonlyArray<{
        offset: number;
        color: string;
    }>;
    bordure?: {
        color: string;
        width: number;
    } | ReadonlyArray<{
        color: string;
        width: number;
    }>;
}
```

### ContrastFinding

```ts
interface ContrastFinding {
    /** What was compared, in the words someone fixing it would use. */
    what: string;
    a: string;
    b: string;
    ratio: number;
    required: number;
    passes: boolean;
}
```