Eve library

The token and contrast audit

Evidence

Revision 1

On this page

How many hue families carry the accent role, whether every semantic status is separate from the accent and from the other statuses, whether the separation survives for each of the two readers who lose the colour, and what every measured pair contrasts at against the floor its kind is recorded under.

Generated from libs/oshun/workbench-kit/src/signals.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S7.22.e. Do not edit by hand.

Summary#

  • src/signals.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/signals contract S7.22.e

Exports#

Symbol Kind Summary
ACCENT_HUE_TOLERANCE_DEG constant How far two hues may sit apart and still be one colour.
ACCENT_ROLE constant The colour roles ADR-S4's token contract names, as the audit uses them.
BOLD_WEIGHT constant The CSS weight at which the criterion's word "bold" starts.
CHROMATIC_CHROMA_FLOOR constant The chroma at which a paint stops being a tinted surface and becomes a colour.
colourSeparation function How many other members of a vocabulary this one's colour tells it apart from.
composite function One colour laid over another — simple alpha compositing, in the encoded space.
CONFORMANCE_TARGET constant The conformance target this audit judges against, and where it is written.
ContractPalette interface The palette a run resolved off a live page, one colour per role.
CONTRAST_PAIR_FAULTS enumeration The faults about a measured contrast pair, named so the ratio helper can cite them.
CONTRAST_PAIR_KINDS enumeration The kinds of pair the recorded baseline gives a separate number for.
contrastFloor function The floor this pair has to clear.
ContrastObservation interface —
contrastPairKind function Which kind a measured pair is.
ContrastPairKind type —
contrastRatio function The contrast ratio of two OPAQUE colours, WCAG 2.x §contrast ratio.
ContrastRow interface —
CUE_REACHES constant Which reader each channel actually reaches.
cuesReaching function The cues that reach a given reader.
cueValue function One channel's value on a member, or the empty string where it carries none.
distinguishingCues function The cues on which this member differs from EVERY other member of its own vocabulary, restricted to the ones the given reader can perceive.
FLOOR_FOR_PAIR_KIND constant The floor each kind must clear, from 's document.
GOVERNED_PROVENANCES enumeration The provenances under which something owns the value.
hueDistance function The shorter way round the hue wheel, in degrees, 0..180.
isChromatic function True when a paint carries enough chroma to be a colour rather than a wash.
LARGE_TEXT_BOLD_PX constant The same criterion's bold threshold: 14 point, which is 18.666… CSS pixels.
LARGE_TEXT_PX constant The size at which text becomes large text, in CSS pixels.
measuredRatio function The pair's measured ratio, or null where the background was never settled.
namesTheStatus function True when the visible text carries the status's own term.
NEUTRAL_ROLES enumeration —
oklch function sRGB to OKLCh (Björn Ottosson, 2020).
Oklch interface —
PAINT_PROVENANCES enumeration Where a paint came from, measured rather than declared.
PAINTED_PROPERTIES enumeration Which property painted the colour.
PaintedProperty type —
PaintObservation interface —
paintProvenance function Which role a paint agrees with, or the honest answer that none does.
PaintProvenance type —
relativeLuminance function Relative luminance, WCAG 2.x §relative luminance.
ROLE_PROPERTIES constant The custom property each role is published under, so a run resolves the right name.
sameColour function —
sameHueFamily function True when two paints are near enough in hue that nobody could name them apart.
SIGNAL_FAULTS enumeration —
SIGNAL_VERDICTS enumeration —
signalAudit function —
SignalAudit interface —
SignalFault type —
signalFaults function The audit.
SignalFinding interface The token and contrast audit: what a colour signals, and whether the signal survives without it (S7.22.e).
signalHeadline function The sentence the audit reports.
SignalInput interface —
signalSummary function —
SignalSummary interface —
SignalVerdict type —
Srgb interface A colour the way an engine hands one back, alpha included.
STATUS_CUES enumeration The non-colour channels a status can be carried on.
STATUS_READERS enumeration The two people a status has to reach, and they are not reached by one channel.
STATUS_ROLES enumeration —
STATUS_WORD_PREFIX constant The shortest run of characters that makes a word the status's OWN word.
StatusCue type —
StatusCueReading interface —
StatusObservation interface —
StatusReader type —
StatusRole type —
StatusRow interface —
statusVerdict function —
vocabularyIds function —
vocabularyMembers function Every member sharing a vocabulary id, one entry per distinct member token.

Shapes#

ACCENT_HUE_TOLERANCE_DEG#

How far two hues may sit apart and still be one colour.

Value: 15

ACCENT_ROLE#

The colour roles ADR-S4's token contract names, as the audit uses them.

Value: 'accent'

BOLD_WEIGHT#

The CSS weight at which the criterion's word "bold" starts.

Value: 700

CHROMATIC_CHROMA_FLOOR#

The chroma at which a paint stops being a tinted surface and becomes a colour.

Value: 0.04

colourSeparation#

How many other members of a vocabulary this one's colour tells it apart from.

ts
colourSeparation(member: StatusObservation, vocabulary: readonly StatusObservation[]): { readonly separated: number; readonly others: number }

composite#

One colour laid over another — simple alpha compositing, in the encoded space.

ts
composite(over: Srgb, under: Srgb): Srgb

CONFORMANCE_TARGET#

The conformance target this audit judges against, and where it is written.

ContractPalette#

The palette a run resolved off a live page, one colour per role.

Field Type Required Notes
accent Srgb | null — Srgb required —
statuses Readonly<Partial<Record<StatusRole, Srgb>>> — Srgb, StatusRole required —

CONTRAST_PAIR_FAULTS#

The faults about a measured contrast pair, named so the ratio helper can cite them.

Values: contrast-below-the-recorded-floor, contrast-measured-against-a-background-nothing-paints

CONTRAST_PAIR_KINDS#

The kinds of pair the recorded baseline gives a separate number for.

Values: body-text, large-text, placeholder-text, disabled-control, control-affordance, focus-indicator, state-indicator, meaningful-icon

contrastFloor#

The floor this pair has to clear.

ts
contrastFloor(observation: ContrastObservation): number

ContrastObservation#

Field Type Required Notes
pairId string required —
hostId string required —
foreground Srgb required The foreground, composited.
background Srgb | null — Srgb required The background, composited down to something opaque — or null where the walk never reached a paint.
isText boolean required Whether the foreground is text at all.
fontPx number required —
fontWeight number required —
isPlaceholder boolean required —
isDisabled boolean required —
nonTextKind | 'control-affordance' | 'focus-indicator' | 'state-indicator' | 'meaningful-icon' required For a non-text pair: which of the baseline's non-text rows it is.

contrastPairKind#

Which kind a measured pair is.

ts
contrastPairKind(observation: ContrastObservation): ContrastPairKind

ContrastPairKind#

ts
(typeof CONTRAST_PAIR_KINDS)[number];

contrastRatio#

The contrast ratio of two OPAQUE colours, WCAG 2.x §contrast ratio.

ts
contrastRatio(first: Srgb, second: Srgb): number

ContrastRow#

Field Type Required Notes
pairId string required —
hostId string required —
kind ContrastPairKind required —
floor number required —
ratio number | null required —
clears boolean | null required —

CUE_REACHES#

Which reader each channel actually reaches.

cuesReaching#

The cues that reach a given reader.

ts
cuesReaching(reader: StatusReader): readonly StatusCue[]

cueValue#

One channel's value on a member, or the empty string where it carries none.

ts
cueValue(member: StatusObservation, cue: StatusCue): string

distinguishingCues#

The cues on which this member differs from EVERY other member of its own vocabulary, restricted to the ones the given reader can perceive.

ts
distinguishingCues(member: StatusObservation, vocabulary: readonly StatusObservation[], reader: StatusReader): readonly StatusCue[]

FLOOR_FOR_PAIR_KIND#

The floor each kind must clear, from 's document.

GOVERNED_PROVENANCES#

The provenances under which something owns the value.

Values: agrees-with-the-accent-role, agrees-with-a-status-role, agrees-with-a-neutral-role

hueDistance#

The shorter way round the hue wheel, in degrees, 0..180.

ts
hueDistance(first: number, second: number): number

isChromatic#

True when a paint carries enough chroma to be a colour rather than a wash.

ts
isChromatic(colour: Srgb): boolean

LARGE_TEXT_BOLD_PX#

The same criterion's bold threshold: 14 point, which is 18.666… CSS pixels.

LARGE_TEXT_PX#

The size at which text becomes large text, in CSS pixels.

measuredRatio#

The pair's measured ratio, or null where the background was never settled.

ts
measuredRatio(observation: ContrastObservation): number | null

namesTheStatus#

True when the visible text carries the status's own term.

ts
namesTheStatus(statusToken: string, visibleText: string): boolean

NEUTRAL_ROLES#

Values: bg, surface, ink, muted, rule

oklch#

sRGB to OKLCh (Björn Ottosson, 2020).

ts
oklch(colour: Srgb): Oklch

Oklch#

Field Type Required Notes
l number required Perceptual lightness, 0..1.
c number required Chroma. 0 is a neutral; the sRGB gamut reaches about 0.32.
h number required Hue angle in degrees, 0..360. Meaningless at zero chroma.

PAINT_PROVENANCES#

Where a paint came from, measured rather than declared.

Values: agrees-with-the-accent-role, agrees-with-a-status-role, agrees-with-a-neutral-role, agrees-with-no-role-the-contract-names, the-contract-did-not-resolve-in-this-document

PAINTED_PROPERTIES#

Which property painted the colour.

Values: text, background, border, outline, shadow

PaintedProperty#

ts
(typeof PAINTED_PROPERTIES)[number];

PaintObservation#

Field Type Required Notes
paintId string required Stable within one run.
hostId string required —
property PaintedProperty required —
colour Srgb required Already composited to opacity, because a hue is not a property of an alpha.
provenance PaintProvenance required —

paintProvenance#

Which role a paint agrees with, or the honest answer that none does.

ts
paintProvenance(colour: Srgb, palette: ContractPalette): PaintProvenance

PaintProvenance#

ts
(typeof PAINT_PROVENANCES)[number];

relativeLuminance#

Relative luminance, WCAG 2.x §relative luminance.

ts
relativeLuminance(colour: Srgb): number

ROLE_PROPERTIES#

The custom property each role is published under, so a run resolves the right name.

sameColour#

ts
sameColour(first: Srgb, second: Srgb): boolean

sameHueFamily#

True when two paints are near enough in hue that nobody could name them apart.

ts
sameHueFamily(first: Srgb, second: Srgb): boolean

SIGNAL_FAULTS#

Values: more-than-one-hue-family-carries-the-accent-role, no-accent-was-painted-in-this-run, a-chromatic-paint-agrees-with-no-role-the-contract-names, the-contract-does-not-reach-the-surfaces-it-governs, a-status-shares-the-accents-hue-family, a-status-is-told-apart-by-colour-alone-for-a-sighted-reader, a-status-is-told-apart-by-colour-alone-for-a-screen-reader, a-cue-the-whole-vocabulary-draws-identically, contrast-below-the-recorded-floor, contrast-measured-against-a-background-nothing-paints, a-vocabulary-this-run-saw-one-member-of

SIGNAL_VERDICTS#

Values: signal-survives-without-colour, signal-carried-by-colour-alone, signal-not-settled-by-this-run

signalAudit#

ts
signalAudit(input: SignalInput): SignalAudit

SignalAudit#

Field Type Required Notes
statuses readonly StatusRow[] — StatusRow required —
contrast readonly ContrastRow[] — ContrastRow required —
accentFamilies readonly string[] required —
ungovernedChromaticPaints readonly string[] required —

SignalFault#

ts
(typeof SIGNAL_FAULTS)[number];

signalFaults#

The audit.

ts
signalFaults(input: SignalInput): readonly SignalFinding[]

SignalFinding#

The token and contrast audit: what a colour signals, and whether the signal survives without it (S7.22.e).

Field Type Required Notes
kind SignalFault required —
subject string required —
detail string required —

signalHeadline#

The sentence the audit reports.

ts
signalHeadline(summary: SignalSummary): string

SignalInput#

Field Type Required Notes
palette ContractPalette required —
paints readonly PaintObservation[] — PaintObservation required —
statuses readonly StatusObservation[] — StatusObservation required —
contrast readonly ContrastObservation[] — ContrastObservation required —

signalSummary#

ts
signalSummary(input: SignalInput, audit: SignalAudit): SignalSummary

SignalSummary#

Field Type Required Notes
paints number required —
chromaticPaints number required —
governedPaints number required —
accentFamilies number required —
vocabularies number required —
statuses number required —
survivingWithoutColour number required —
colourAlone number required —
unsettledStatuses number required —
contrastPairs number required —
contrastClearing number required —
contrastUnsettled number required —
pairKindsSeen number required How many of the eight pair kinds the run measured at all.

SignalVerdict#

ts
(typeof SIGNAL_VERDICTS)[number];

Srgb#

A colour the way an engine hands one back, alpha included.

Field Type Required Notes
r number required —
g number required —
b number required —
a number required —

STATUS_CUES#

The non-colour channels a status can be carried on.

Values: words, glyph, border-style, weight, assistive-name, announced-role

STATUS_READERS#

The two people a status has to reach, and they are not reached by one channel.

Values: sighted-monochrome, screen-reader

STATUS_ROLES#

Values: ok, warn, danger, info

STATUS_WORD_PREFIX#

The shortest run of characters that makes a word the status's OWN word.

Value: 4

StatusCue#

ts
(typeof STATUS_CUES)[number];

StatusCueReading#

Field Type Required Notes
cue StatusCue required —
value string required What the channel carries on this member, normalised.

StatusObservation#

Field Type Required Notes
vocabularyId string required The vocabulary this member belongs to — a part of a surface, not a global list.
statusId string required The member's own token, as the surface spells it.
hostId string required —
elementId string required —
colour Srgb required The colour this member is drawn in, composited, and the one a reader sees it as.
provenance PaintProvenance required Which contract role this member's colour agrees with.
cues readonly StatusCueReading[] — StatusCueReading required —

StatusReader#

ts
(typeof STATUS_READERS)[number];

StatusRole#

ts
(typeof STATUS_ROLES)[number];

StatusRow#

Field Type Required Notes
vocabularyId string required —
statusId string required —
hostId string required —
colour string required —
reachesSighted readonly StatusCue[] — StatusCue required —
reachesScreenReader readonly StatusCue[] — StatusCue required —
colourSeparatesFrom string required How many of the other members this member's COLOUR separates it from, out of how many there are.
verdict SignalVerdict required —

statusVerdict#

ts
statusVerdict(member: StatusObservation, vocabulary: readonly StatusObservation[]): SignalVerdict

vocabularyIds#

ts
vocabularyIds(observations: readonly StatusObservation[]): readonly string[]

vocabularyMembers#

Every member sharing a vocabulary id, one entry per distinct member token.

ts
vocabularyMembers(observations: readonly StatusObservation[], vocabularyId: string): readonly StatusObservation[]

Valid examples#

No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.

Invalid examples#

No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.

Authorization and scope#

Not applicable: nothing on this page carries an actor, a grant, a scope or a tenant, so authorization is decided entirely by the caller.

Idempotency and concurrency#

Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
ContractPalette.statuses Readonly<Partial<Record<StatusRole, Srgb>>> —
namesTheStatus function True when the visible text carries the status's own term.
SIGNAL_VERDICTS enumeration —
SignalAudit.statuses readonly StatusRow[] —
SignalInput.statuses readonly StatusObservation[] —
SignalSummary.statuses number —
SignalSummary.unsettledStatuses number —
SignalVerdict type —
STATUS_CUES enumeration The non-colour channels a status can be carried on.
STATUS_READERS enumeration The two people a status has to reach, and they are not reached by one channel.
STATUS_ROLES enumeration —
STATUS_WORD_PREFIX constant The shortest run of characters that makes a word the status's OWN word.
StatusCue type —
StatusObservation.statusId string The member's own token, as the surface spells it.
StatusReader type —
StatusRole type —
StatusRow.statusId string —
StatusRow.verdict SignalVerdict —
statusVerdict function —

Compatibility#

Not applicable: nothing on this page is versioned independently of the package.

Deprecation#

Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.

Evidence#

  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/signals.ts