<accessibility-specimen>
WCAG contrast-ratio table and accessibility checklist web component for design-system docs. Computes AA/AAA pass/fail badges from authored foreground/background color pairs.
Overview
The <accessibility-specimen> component renders a WCAG 2.x contrast-ratio table from authored foreground/background color pairs, or an accessibility checklist from an authored list. It computes relative luminance and contrast ratio client-side and shows AA / AA Large / AAA / AAA Large pass-fail badges per pair — no design-token dependency, so it works with any color values.
<accessibility-specimen> <button data-fg="#000000" data-bg="#ffffff" data-label="Black on white">Default text</button> <button data-fg="#666666" data-bg="#ffffff" data-label="Mid-gray on white">Muted text</button> <button data-fg="#ffffff" data-bg="#0066cc" data-label="White on accent blue">Action button</button> <button data-fg="#ffffff" data-bg="#dddddd" data-label="White on light-gray">Bad pairing</button></accessibility-specimen>Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
type |
string | contrast |
Rendering mode: contrast (color-pair table) or checklist (status list). |
Authoring Contrast Pairs
In contrast mode (the default), author direct <button> children with data-fg / data-bg / optional data-label. The component replaces them with a table — one row per pair, each with a live sample, the computed ratio, and pass/fail badges for AA, AA Large, AAA, and AAA Large thresholds.
| Child attribute | On | Required | Description |
|---|---|---|---|
data-fg |
button |
Yes | Foreground color (hex, rgb(), or named CSS color). |
data-bg |
button |
Yes | Background color (hex, rgb(), or named CSS color). |
data-label |
button |
No | Display label for the pair. Defaults to the button's text content. |
Checklist Mode
Set type="checklist" and author a <ul> of <li data-status="pass|fail|warn|na"> items. The component normalizes the list styling and prepends a status icon (with a screen-reader-only label) per item.
- Form inputs have associated labels.
- Focus indicators are visible at 2px width minimum.
- Some images may be missing alt text.
- Color contrast on muted text fails AA.
- No videos in this component (captions N/A).
<accessibility-specimen type="checklist"> <ul> <li data-status="pass">Form inputs have associated labels.</li> <li data-status="pass">Focus indicators are visible at 2px width minimum.</li> <li data-status="warn">Some images may be missing alt text.</li> <li data-status="fail">Color contrast on muted text fails AA.</li> <li data-status="na">No videos in this component (captions N/A).</li> </ul></accessibility-specimen>| Child attribute | On | Description |
|---|---|---|
data-status |
li |
pass, fail, warn, or na (default when omitted). |
Reading the Badges
Ratios are computed per WCAG 2.x relative luminance. Thresholds: AA normal text ≥4.5:1, AA large text ≥3:1, AAA normal text ≥7:1, AAA large text ≥4.5:1. A pair that fails to parse (unsupported color syntax) shows ? for the ratio and fails every badge.
<accessibility-specimen> <button data-fg="#333333" data-bg="#f5f5f5" data-label="Dark gray on off-white">Body copy</button> <button data-fg="oklch(70% 0.15 145)" data-bg="#ffffff" data-label="Success green on white">Status text</button></accessibility-specimen>Accessibility
- Contrast table uses semantic
<table>markup with<th scope="col">/<th scope="row">, so screen readers can navigate rows and columns. - Pass/fail badges carry an explicit
aria-label("Pass" / "Fail") — they never rely on the check/cross glyph alone. - Checklist items get a screen-reader-only status label (e.g. "Warning: ") prepended before the item text, in addition to the visual icon.
- The component itself doesn't judge your page's actual colors — it's a documentation aid. Always verify real rendered text against these thresholds, not just documented token pairs.