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.
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.
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.
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.
contrastPairKind(observation: ContrastObservation): ContrastPairKind
ContrastPairKind#
(typeof CONTRAST_PAIR_KINDS)[number];
contrastRatio#
The contrast ratio of two OPAQUE colours, WCAG 2.x §contrast ratio.
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.
cuesReaching(reader: StatusReader): readonly StatusCue[]
cueValue#
One channel's value on a member, or the empty string where it carries none.
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.
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.
hueDistance(first: number, second: number): number
isChromatic#
True when a paint carries enough chroma to be a colour rather than a wash.
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.
measuredRatio(observation: ContrastObservation): number | null
namesTheStatus#
True when the visible text carries the status's own term.
namesTheStatus(statusToken: string, visibleText: string): boolean
NEUTRAL_ROLES#
Values: bg, surface, ink, muted, rule
oklch#
sRGB to OKLCh (Björn Ottosson, 2020).
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#
(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.
paintProvenance(colour: Srgb, palette: ContractPalette): PaintProvenance
PaintProvenance#
(typeof PAINT_PROVENANCES)[number];
relativeLuminance#
Relative luminance, WCAG 2.x §relative luminance.
relativeLuminance(colour: Srgb): number
ROLE_PROPERTIES#
The custom property each role is published under, so a run resolves the right name.
sameColour#
sameColour(first: Srgb, second: Srgb): boolean
sameHueFamily#
True when two paints are near enough in hue that nobody could name them apart.
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#
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#
(typeof SIGNAL_FAULTS)[number];
signalFaults#
The audit.
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.
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#
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#
(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#
(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#
(typeof STATUS_READERS)[number];
StatusRole#
(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#
statusVerdict(member: StatusObservation, vocabulary: readonly StatusObservation[]): SignalVerdict
vocabularyIds#
vocabularyIds(observations: readonly StatusObservation[]): readonly string[]
vocabularyMembers#
Every member sharing a vocabulary id, one entry per distinct member token.
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.jsonlibs/oshun/workbench-kit/src/signals.ts