VPAT 2.5 — @helixui/library
apps/docs/src/content/docs/accessibility/vpat-25 Click to copy Copied!
apps/docs/src/content/docs/accessibility/vpat-25 This document is the Voluntary Product Accessibility Template (VPAT) 2.5
for @helixui/library, the
HELiX healthcare web component library. The format follows the ITI VPAT
2.5 Rev 508 template, the
same structure adopted by the U.S. Web Design System (USWDS) for its 44
core components.
HELiX’s conformance posture: WCAG 2.2 Level AAA on its P0 (Tier 1) surface (44 components against 11 criteria — 376 Supports verdicts), with AA baseline across all shipped components. WCAG 2.1 Understanding pages remain cited where WCAG 2.2 carries the criterion forward unchanged.
Product Information
Section titled “Product Information”| Field | Value |
|---|---|
| Product Name | @helixui/library |
| Product Version | 3.9.0 |
| Report Date | 2026-05-11 |
| Report Version | v1.0 (Published) |
| Product Description | Enterprise healthcare web component library — framework-agnostic custom elements built on Lit 3.x and the W3C Web Components standard, with a P0 cert surface of 44 components plus ancillary subcomponents. Counts are reproducible from packages/hx-library/custom-elements.json (every shipped hx-* tag) and packages/hx-library/aaa-verdicts.json (the 44 P0 surface). Ships with a three-tier design token system (light, dark, high-contrast) and Drupal CMS integration via Twig templates. |
| Contact Information | https://github.com/bookedsolidtech/helix/issues |
| Notes | This VPAT covers the published @helixui/library package only. The companion @helixui/tokens (design tokens) and @helixui/react (auto-generated React wrappers) packages are evaluated separately when their conformance evidence is published; they do not inherit per-SC outcomes from this report. @helixui/react wrappers in particular pass through the @helixui/library runtime, so their conformance derives from the underlying library — but the canonical verdict snapshot at packages/hx-library/aaa-verdicts.json only attests the library package. |
| Evaluation Methods | Automated testing (axe-core, Vitest browser mode), runtime adopted-stylesheet inspection, design-token contrast regression matrix, manual keyboard / screen-reader review on a per-component basis as the AAA Certification Epic executes. |
| Evaluator Credentials | HELiX engineering team — internal review. Third-party audit (planned for v1.0) is not yet performed. This VPAT is an internal, voluntary disclosure; it has not been reviewed or signed off by an independent accessibility auditor. |
Applicable Standards / Guidelines
Section titled “Applicable Standards / Guidelines”This report covers conformance with the following standards:
| Standard | Included In Report |
|---|---|
| Web Content Accessibility Guidelines 2.2, Level A | Yes |
| Web Content Accessibility Guidelines 2.2, Level AA | Yes |
| Web Content Accessibility Guidelines 2.2, Level AAA | Yes — P0 surface (44 components × 11 criteria) |
| Revised Section 508 standards (2017), 36 CFR Part 1194 | Yes — Chapters 3, 4, 5, 6 mapped via WCAG 2.0 Level A and AA |
| EN 301 549 V3.2.1 (2021-03) | Yes — Chapters 9, 10, 11 mapped via WCAG 2.2 Level A and AA |
A Level AAA claim is not required by Section 508 or EN 301 549. HELiX’s AAA targeting is voluntary and intended to provide conformance headroom for healthcare and public-sector consumers operating under stricter procurement posture.
The terms used in the conformance columns follow the standard VPAT 2.5 vocabulary, as adopted by USWDS in its VPAT and the broader U.S. federal procurement community:
| Term | Definition |
|---|---|
| Supports | The functionality of the product has at least one method that meets the criterion without known defects, or meets with equivalent facilitation. |
| Partially Supports | Some functionality of the product does not meet the criterion. Known defects exist; remediation is in progress. |
| Does Not Support | The majority of product functionality does not meet the criterion. |
| Not Applicable | The criterion is not relevant to the product. |
| Not Evaluated | The product has not been evaluated against this criterion. This is the initial state of any criterion not yet folded into the per-SC table or covered by the formal AAA harness verdict snapshot. Per-component audits convert “Not Evaluated” rows to one of the three conformance verdicts above. |
Conformance Summary
Section titled “Conformance Summary”The library asserts WCAG 2.2 AAA conformance on its P0 (Tier 1)
surface — 44 components against the 11-criterion AAA harness, producing
376 Supports verdicts (0 Partial, 0 Fail, 109 Not Applicable). The cert
is reproducible via pnpm aaa:audit against the canonical
aaa-verdicts.json
snapshot.
Underlying gates that backstop the cert:
contrast.test.ts
(design-token contrast regression matrix),
forced-colors-runtime.test.ts
(forced-colors runtime adoption), and the
check-aaa-verdicts.mjs
preflight gate that refuses regression in the committed verdicts snapshot.
All Success Criteria are scoped per-component and surfaced in the Per-Component Coverage Matrix.
WCAG 2.2 Level A (30 Success Criteria)
Section titled “WCAG 2.2 Level A (30 Success Criteria)”The Understanding URLs below point to WCAG 2.1; WCAG 2.2 carries these criteria forward unchanged, and the W3C maintains the 2.1 Understanding pages as the canonical reference for them.
| Success Criterion | Conformance Level | Remarks and Explanations |
|---|---|---|
| 1.1.1 Non-text Content | Not Evaluated | Per-component audit pending. Components that ship icons (hx-icon, hx-icon-button, hx-avatar) require explicit label / aria-label review. |
| 1.2.1 Audio-only and Video-only (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.2.2 Captions (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.2.3 Audio Description or Media Alternative (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.3.1 Info and Relationships | Partially Supports | Form composition (hx-field, hx-form, hx-field-label, hx-help-text) cross-shadow-boundary association is the dominant per-SC remediation surface. |
| 1.3.2 Meaningful Sequence | Not Evaluated | Per-component audit pending. |
| 1.3.3 Sensory Characteristics | Not Evaluated | Per-component audit pending. |
| 1.4.1 Use of Color | Not Evaluated | Validation styling (hx-text-input, hx-textarea, hx-checkbox, hx-select) requires explicit non-color indicator audit. |
| 1.4.2 Audio Control | Not Applicable | The library ships no audio components. |
| 2.1.1 Keyboard | Partially Supports | Interactive components broadly tested. Outstanding: per-component keyboard-test coverage parity (see AAA Epic Phase 2). |
| 2.1.2 No Keyboard Trap | Partially Supports | Modal-class components (hx-dialog, hx-drawer, hx-popover) require explicit focus-trap audit per APG. |
| 2.1.4 Character Key Shortcuts | Not Evaluated | Per-component audit pending. |
| 2.2.1 Timing Adjustable | Not Evaluated | hx-toast auto-dismiss timing requires audit. |
| 2.2.2 Pause, Stop, Hide | Not Evaluated | hx-carousel, hx-spinner, hx-progress-ring motion-control audit pending. |
| 2.3.1 Three Flashes or Below Threshold | Supports | No components flash above the threshold. All animated components honour prefers-reduced-motion. |
| 2.4.1 Bypass Blocks | Not Applicable | Page-level concern; the library provides composition primitives (hx-side-nav, hx-top-nav) but does not enforce page structure. |
| 2.4.2 Page Titled | Not Applicable | Page-level concern outside library scope. |
| 2.4.3 Focus Order | Not Evaluated | Per-component audit pending. Composite components (hx-tabs, hx-radio-group, hx-tree-view) require roving-tabindex audit. |
| 2.4.4 Link Purpose (In Context) | Not Evaluated | hx-link, hx-card[hx-href] audit pending. |
| 2.5.1 Pointer Gestures | Not Evaluated | hx-slider, hx-color-picker audit pending. |
| 2.5.2 Pointer Cancellation | Not Evaluated | Per-component audit pending. |
| 2.5.3 Label in Name | Not Evaluated | Per-component audit pending. |
| 2.5.4 Motion Actuation | Not Applicable | No motion-actuated functionality in the library. |
| 3.1.1 Language of Page | Not Applicable | Page-level concern outside library scope. |
| 3.2.1 On Focus | Not Evaluated | Per-component audit pending. |
| 3.2.2 On Input | Not Evaluated | Per-component audit pending. |
| 3.3.1 Error Identification | Partially Supports | Form-error association (hx-field, hx-help-text, hx-text-input validity) is the dominant remediation surface. |
| 3.3.2 Labels or Instructions | Partially Supports | Slotted label/help-text patterns are the dominant remediation surface. |
| 4.1.1 Parsing | Supports | All components emit valid HTML; Lit’s templating prevents malformed output. (Note: WCAG 2.2 obsoletes 4.1.1.) |
| 4.1.2 Name, Role, Value | Partially Supports | Custom-element ARIA contracts are reviewed per-component. The host-canonical ARIA pattern (e.g. hx-select) is the strategic direction. |
WCAG 2.2 Level AA (20 Success Criteria)
Section titled “WCAG 2.2 Level AA (20 Success Criteria)”| Success Criterion | Conformance Level | Remarks and Explanations |
|---|---|---|
| 1.2.4 Captions (Live) | Not Applicable | The library ships no live audio or video components. |
| 1.2.5 Audio Description (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.3.4 Orientation | Supports | No component restricts orientation. |
| 1.3.5 Identify Input Purpose | Not Evaluated | hx-text-input autocomplete token coverage audit pending. |
| 1.4.3 Contrast (Minimum) | Supports | Gated by packages/hx-tokens/src/__tests__/contrast.test.ts — every semantic text.* × surface.* pairing across light, dark, and high-contrast modes asserts ≥4.5:1 (body) / ≥3.0:1 (large/UI) at CI time. |
| 1.4.4 Resize Text | Not Evaluated | All component dimensions use relative units (em, rem); explicit 200% zoom audit pending. |
| 1.4.5 Images of Text | Supports | The library renders no images of text. |
| 1.4.10 Reflow | Not Evaluated | Per-component reflow audit at 320 CSS px pending. |
| 1.4.11 Non-text Contrast | Partially Supports | Border / focus-ring tokens audited; border.on-dark-strong enforced ≥3:1 in contrast.test.ts. Per-component focus-ring contrast audit pending. |
| 1.4.12 Text Spacing | Not Evaluated | Per-component audit pending. |
| 1.4.13 Content on Hover or Focus | Not Evaluated | hx-tooltip, hx-popover dismissable / hoverable / persistent audit pending. |
| 2.4.5 Multiple Ways | Not Applicable | Page-level concern outside library scope. |
| 2.4.6 Headings and Labels | Not Evaluated | Slotted heading audit pending. |
| 2.4.7 Focus Visible | Partially Supports | :focus-visible rings present on all interactive components. Forced-colors fallback gated by forced-colors-runtime.test.ts. Per-component visual review pending. |
| 3.1.2 Language of Parts | Not Applicable | Page-level concern outside library scope. |
| 3.2.3 Consistent Navigation | Not Applicable | Page-level concern outside library scope. |
| 3.2.4 Consistent Identification | Supports | Components preserve consistent ARIA contracts and slot APIs across instantiations. |
| 3.3.3 Error Suggestion | Not Evaluated | hx-form validation suggestion-message audit pending. |
| 3.3.4 Error Prevention (Legal, Financial, Data) | Not Applicable | Application-level concern outside library scope. |
| 4.1.3 Status Messages | Partially Supports | hx-toast, hx-alert, hx-progress-bar live-region audit in progress. ARIA Group 4 Phase 1 work covers aria-live posture for status / alert components. |
WCAG 2.2 Level AAA (28 Success Criteria) — P0 Cert Surface
Section titled “WCAG 2.2 Level AAA (28 Success Criteria) — P0 Cert Surface”| Success Criterion | Conformance Level | Remarks and Explanations |
|---|---|---|
| 1.2.6 Sign Language (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.2.7 Extended Audio Description | Not Applicable | The library ships no audio or video components. |
| 1.2.8 Media Alternative (Prerecorded) | Not Applicable | The library ships no audio or video components. |
| 1.2.9 Audio-only (Live) | Not Applicable | The library ships no audio or video components. |
| 1.3.6 Identify Purpose | Not Evaluated | Symbol / icon / region purpose-mapping audit pending. |
| 1.4.6 Contrast (Enhanced) | Supports | Verified on the P0 surface via the formal AAA harness (scripts/aaa-formal-audit.mjs); the committed snapshot at packages/hx-library/aaa-verdicts.json records 376 Supports verdicts across 44 components × 11 criteria with zero Partial or Fail. The scripts/check-aaa-verdicts.mjs preflight gate refuses any regression in the committed snapshot, so AAA contrast on the cert surface is a CI gate today. Per-pair contrast telemetry (160 pair instances across light / dark / high-contrast modes, all clearing the AAA threshold) is regenerated via pnpm --filter=@helixui/tokens run contrast:report. |
| 1.4.7 Low or No Background Audio | Not Applicable | The library ships no audio components. |
| 1.4.8 Visual Presentation | Not Evaluated | Block-of-text presentation control audit pending — hx-prose is the audit target. |
| 1.4.9 Images of Text (No Exception) | Supports | The library renders no images of text. |
| 2.1.3 Keyboard (No Exception) | Not Evaluated | Per-component keyboard-no-exception audit pending; AAA conformance requires removing all keyboard traps including timed paths. |
| 2.2.3 No Timing | Not Applicable | No essential timing in component behaviour. hx-toast auto-dismiss is configurable to indefinite. |
| 2.2.4 Interruptions | Not Evaluated | hx-toast, hx-alert interrupt-suppression API audit pending. |
| 2.2.5 Re-authenticating | Not Applicable | Application-level concern outside library scope. |
| 2.2.6 Timeouts | Not Applicable | Application-level concern outside library scope. |
| 2.3.2 Three Flashes | Supports | No components flash. All animated components honour prefers-reduced-motion. |
| 2.3.3 Animation from Interactions | Supports | All animated components honour prefers-reduced-motion. |
| 2.4.8 Location | Not Applicable | Page-level concern outside library scope. |
| 2.4.9 Link Purpose (Link Only) | Not Evaluated | hx-link, hx-card[hx-href] link-only-purpose audit pending. |
| 2.4.10 Section Headings | Not Applicable | Page-level concern outside library scope. |
| 2.5.5 Target Size | Not Evaluated | All interactive component target-size audit (≥44×44 CSS px) pending. WCAG 2.2 introduces 2.5.8 at AA (24×24); HELiX targets the AAA 44×44 floor. |
| 2.5.6 Concurrent Input Mechanisms | Supports | All components support keyboard, pointer, and touch concurrently; no input mechanism is restricted. |
| 3.1.3 Unusual Words | Not Applicable | Content-level concern outside library scope. |
| 3.1.4 Abbreviations | Not Applicable | Content-level concern outside library scope. |
| 3.1.5 Reading Level | Not Applicable | Content-level concern outside library scope. |
| 3.1.6 Pronunciation | Not Applicable | Content-level concern outside library scope. |
| 3.2.5 Change on Request | Not Evaluated | Per-component automatic-change audit pending (hx-tabs, hx-combobox). |
| 3.3.5 Help | Supports | hx-help-text and the help-text slot pattern provide context-sensitive help on all form components. |
| 3.3.6 Error Prevention (All) | Not Applicable | Application-level concern outside library scope. |
Per-Component Coverage Matrix
Section titled “Per-Component Coverage Matrix”The matrix below records the per-component conformance posture across the 80 published components. Tier assignments follow the AAA Certification Epic plan:
- P0 — Tier 1 (42 components): form inputs, selection controls, buttons, navigation composites, modals, live regions, sliders, form assembly, field helpers. Highest user-facing risk; first to AAA-cert.
- P1 — Tier 2 (10 components): data display, progress / meter, specialised healthcare components.
- P2 — Tier 3 (22 components): indicators, stat / metric, structural and layout primitives.
- Exempt — Tier 4 (6 components): utility / theming components with no user-facing surface.
The matrix below tracks the engineering-audit posture per component as the AAA cert flow
executes. The canonical cert authority is packages/hx-library/aaa-verdicts.json, which
records 44 P0 components with measured verdicts; this matrix predates the verdict snapshot and
may show stale tier assignments or row-level details. Where the matrix and the verdict snapshot
disagree, the snapshot wins. Components carrying an AAA-cert <date> note in the table below
appear in the verdicts file; rows still marked “Pending audit” predate the cert flow.
Components in the P0 cert surface but not yet folded into the right row of this matrix:
hx-action-bar, hx-banner, hx-clinical-status, hx-copy-button, and hx-icon (currently
shown in lower-tier or Exempt sections with AAA-cert notes — those notes are correct; the tier
columns predate the cert and will be reconciled in the next VPAT revision). Components shown in
P0 below but not in the cert verdict surface today: hx-card, hx-link, hx-pagination
(treat their Supports rows as engineering-audit posture rather than cert verdicts until the
verdict file ingests them).
P0 — Tier 1 (44 components per aaa-verdicts.json)
Section titled “P0 — Tier 1 (44 components per aaa-verdicts.json)”| Component | Tier | AA Status | AAA Status | Forced-Colors Coverage | Notes |
|---|---|---|---|---|---|
hx-button | P0 | Supports — runtime tested | Supports | Supports | Forced-colors mixin: forcedColorsInteractive. Live-region for loading state pending (P1 audit item). — AAA-cert 2026-05-08 |
hx-icon-button | P0 | Pending audit | Supports | Supports | Inherits interactive forced-colors mixin via shared base. Per-component runtime test pending. — AAA-cert 2026-05-08 |
hx-toggle-button | P0 | Pending audit | Supports | Supports | Pressed-state ARIA contract audit pending. — AAA-cert 2026-05-08 |
hx-split-button | P0 | Pending audit | Supports | Supports | Composite (button + dropdown trigger); ARIA grouping audit pending. — AAA-cert 2026-05-08 |
hx-button-group | P0 | Pending audit | Supports | Supports | role="group" accessible name audit pending. — AAA-cert 2026-05-08 |
hx-text-input | P0 | Pending audit | Supports | Supports | Forced-colors mixin: forcedColorsField. Validity-driven aria-invalid audit pending. — AAA-cert 2026-05-08 |
hx-textarea | P0 | Pending audit | Supports | Supports | Counter aria-describedby association audit pending. — AAA-cert 2026-05-08 |
hx-number-input | P0 | Pending audit | Supports | Supports | Spinner-button accessible name audit pending. — AAA-cert 2026-05-08 |
hx-checkbox | P0 | Supports — runtime tested | Supports | Supports | Forced-colors mixin: forcedColorsField. Keyboard accessibility remediated post-AUDIT-001. — AAA-cert 2026-05-08 |
hx-checkbox-group | P0 | Pending audit | Supports | Supports | Group-level error / aria-describedby audit pending. — AAA-cert 2026-05-08 |
hx-radio-group | P0 | Pending audit | Supports | Supports | Roving-tabindex + group error audit pending. — AAA-cert 2026-05-08 |
hx-switch | P0 | Pending audit | Supports | Supports | APG Space-only key audit pending. — AAA-cert 2026-05-08 |
hx-select | P0 | Pending audit | Supports | Supports | Host-canonical combobox pattern (ARIA Group 3 in progress); aria-activedescendant audit ongoing. — AAA-cert 2026-05-08 |
hx-combobox | P0 | Pending audit | Supports | Supports | APG combobox pattern audit pending. — AAA-cert 2026-05-08 |
hx-date-picker | P0 | Pending audit | Supports | Supports | Calendar grid + dialog ARIA audit pending. — AAA-cert 2026-05-08 |
hx-time-picker | P0 | Pending audit | Supports | Supports | Spinbutton ARIA audit pending. — AAA-cert 2026-05-08 |
hx-slider | P0 | Pending audit | Supports | Supports | role="slider" keyboard contract audit pending. — AAA-cert 2026-05-09 |
hx-color-picker | P0 | Pending audit | Supports | Supports | Custom widget ARIA audit pending. — AAA-cert 2026-05-08 |
hx-rating | P0 | Pending audit | Supports | Supports | Group-of-radios pattern audit pending. — AAA-cert 2026-05-09 |
hx-file-upload | P0 | Pending audit | Supports | Supports | Drop-target announce + button-trigger audit pending. — AAA-cert 2026-05-08 |
hx-form | P0 | Pending audit | Supports | Supports | Light-DOM scoped CSS via AdoptedStylesheetsController; form-association audit pending. — AAA-cert 2026-05-09 |
hx-field | P0 | Pending audit | Supports | Supports | Cross-shadow-boundary label / error association — dominant 1.3.1 / 4.1.2 remediation surface. — AAA-cert 2026-05-09 |
hx-field-label | P0 | Pending audit | Supports | Supports | Slotted <label> ID-ref pattern audit pending. — AAA-cert 2026-05-09 |
hx-help-text | P0 | Pending audit | Supports | Supports | aria-describedby ID-ref pattern audit pending. — AAA-cert 2026-05-09 |
hx-dialog | P0 | Pending audit | Supports | Supports | Native <dialog> + APG modal audit pending; focus-trap verification required. — AAA-cert 2026-05-08 |
hx-drawer | P0 | Pending audit | Supports | Supports | APG dialog pattern audit pending. — AAA-cert 2026-05-08 |
hx-popover | P0 | Pending audit | Supports | Supports | APG dialog / disclosure pattern audit pending. — AAA-cert 2026-05-08 |
hx-popup | P0 | Pending audit | Supports | Supports | Floating-UI placement primitive; ARIA inherits from parent. — AAA-cert 2026-05-08 |
hx-tooltip | P0 | Pending audit | Supports | Supports | APG tooltip dismissable / hoverable / persistent audit (1.4.13) pending. — AAA-cert 2026-05-08 |
hx-dropdown | P0 | Pending audit | Supports | Supports | APG menu / listbox audit pending. — AAA-cert 2026-05-08 |
hx-menu | P0 | Pending audit | Supports | Supports | APG menu pattern audit pending. — AAA-cert 2026-05-08 |
hx-overflow-menu | P0 | Pending audit | Supports | Supports | APG menu pattern audit pending. — AAA-cert 2026-05-08 |
hx-side-nav | P0 | Supports — runtime tested | Supports | Supports | Forced-colors disabled .nav-item__link opacity scoping verified at runtime; cascade-order regression net in place. — AAA-cert 2026-05-08 |
hx-top-nav | P0 | Pending audit | Supports | Supports | Landmark + nav-list audit pending. — AAA-cert 2026-05-08 |
hx-nav | P0 | Pending audit | Supports | Supports | Per-component audit pending. — AAA-cert 2026-05-08 |
hx-tabs | P0 | Pending audit | Supports | Supports | APG tabs pattern + roving tabindex audit pending. — AAA-cert 2026-05-08 |
hx-breadcrumb | P0 | Pending audit | Supports | Supports | Native <ol> migration audit pending. — AAA-cert 2026-05-08 |
hx-pagination | P0 | Pending audit | Pending audit | Pending verification | Page-link aria-current audit pending. |
hx-toast | P0 | Pending audit | Supports | Supports | Live-region + auto-dismiss timing audit pending. — AAA-cert 2026-05-09 |
hx-alert | P0 | Pending audit | Supports | Supports | role="alert" redundancy + close-button target-size audit pending. — AAA-cert 2026-05-08 |
hx-link | P0 | Supports — runtime tested | Pending audit | Supports — runtime verified | Forced-colors mixin: forcedColorsLink. Visited-state LinkText / VisitedText keywords verified. |
hx-card | P0 | Supports — runtime tested | Pending audit | Supports — runtime verified | Forced-colors mixin: forcedColorsSurface. Interactive-card aria-label audit pending. |
P1 — Tier 2 (10 components)
Section titled “P1 — Tier 2 (10 components)”| Component | Tier | AA Status | AAA Status | Forced-Colors Coverage | Notes |
|---|---|---|---|---|---|
hx-data-table | P1 | Pending audit | Pending audit | Pending verification | APG grid pattern audit pending. |
hx-table | P1 | Pending audit | Pending audit | Pending verification | Native semantic table; header-cell association audit pending. |
hx-list | P1 | Pending audit | Pending audit | Pending verification | role="list" posture audit pending. |
hx-structured-list | P1 | Pending audit | Pending audit | Pending verification | DL / table semantics audit pending. |
hx-tree-view | P1 | Pending audit | Pending audit | Pending verification | APG tree pattern + roving tabindex audit pending. |
hx-progress-bar | P1 | Pending audit | Pending audit | Pending verification | role="progressbar" ARIA contract audit pending. |
hx-progress-ring | P1 | Pending audit | Pending audit | Pending verification | role="progressbar" ARIA contract audit pending. |
hx-meter | P1 | Pending audit | Pending audit | Pending verification | role="meter" ARIA contract audit pending. |
hx-link | P1 | Supports — runtime tested | Pending audit | Supports — runtime verified | Cross-listed P0/P1 due to its role as both interactive control and navigation primitive. Forced-colors verified. |
hx-patient-banner | P1 | Pending audit | Pending audit | Pending verification | Healthcare-specialised composite; landmark + status audit pending. |
hx-phi-field | P1 | Pending audit | Pending audit | Pending verification | Healthcare-specialised PHI redaction; show / hide announce audit pending. |
P2 — Tier 3 (22 components)
Section titled “P2 — Tier 3 (22 components)”| Component | Tier | AA Status | AAA Status | Forced-Colors Coverage | Notes |
|---|---|---|---|---|---|
hx-badge | P2 | Pending audit | Pending audit | Pending verification | Dot variant screen-reader announce audit pending. |
hx-tag | P2 | Pending audit | Pending audit | Pending verification | Removable-tag close-button name audit pending. |
hx-avatar | P2 | Pending audit | Pending audit | Pending verification | Image / initials accessible name audit pending. |
hx-status-indicator | P2 | Pending audit | Pending audit | Pending verification | Color + icon non-color indicator audit pending. |
hx-clinical-status | P2 | Pending audit | Supports | Supports | Healthcare-specialised; status-text + color audit pending. — AAA-cert 2026-05-09 |
hx-stat | P2 | Pending audit | Pending audit | Pending verification | Forced-colors block carried via mixin; per-component runtime test pending. |
hx-counter | P2 | Pending audit | Pending audit | Pending verification | Live-update announce audit pending. |
hx-spinner | P2 | Pending audit | Pending audit | Pending verification | role="status" + label audit pending. |
hx-skeleton | P2 | Pending audit | Pending audit | Pending verification | aria-busy posture audit pending. |
hx-divider | P2 | Pending audit | Pending audit | Pending verification | role="separator" posture audit pending. |
hx-action-bar | P2 | Pending audit | Supports | Supports | Toolbar pattern audit pending. — AAA-cert 2026-05-08 |
hx-banner | P2 | Pending audit | Supports | Supports | Landmark + dismissable banner audit pending. — AAA-cert 2026-05-09 |
hx-carousel | P2 | Pending audit | Pending audit | Pending verification | APG carousel pattern + 2.2.2 pause control audit pending. |
hx-steps | P2 | Pending audit | Pending audit | Pending verification | Stepper pattern + aria-current audit pending. |
hx-grid | P2 | Pending audit | Pending audit | N/A — layout-only | Layout primitive; no interactive ARIA surface. |
hx-stack | P2 | Pending audit | Pending audit | N/A — layout-only | Layout primitive; no interactive ARIA surface. |
hx-container | P2 | Pending audit | Pending audit | N/A — layout-only | Layout primitive; no interactive ARIA surface. |
hx-split-panel | P2 | Pending audit | Pending audit | Pending verification | Resize-handle keyboard audit pending. |
hx-accordion | P2 | Pending audit | Pending audit | Pending verification | APG accordion pattern audit pending. |
hx-text | P2 | Pending audit | Pending audit | N/A — text primitive | Text primitive; no interactive ARIA surface. |
hx-prose | P2 | Pending audit | Pending audit | Pending verification | Light-DOM scoped CSS via AdoptedStylesheetsController; 1.4.8 visual-presentation audit target. |
hx-image | P2 | Pending audit | Pending audit | Pending verification | Alt-text / decorative-role audit pending. |
Exempt — Tier 4 (6 components)
Section titled “Exempt — Tier 4 (6 components)”| Component | Tier | AA Status | AAA Status | Forced-Colors Coverage | Notes |
|---|---|---|---|---|---|
hx-theme | Exempt | Not Applicable | Not Applicable | Not Applicable | Theming primitive; no rendered surface. |
hx-style-scope | Exempt | Not Applicable | Not Applicable | Not Applicable | CSS scoping primitive; no rendered surface. |
hx-icon | Exempt | Pending audit | Pending audit | Not Applicable | Renders SVG; aria-hidden posture audit pending. Decorative by default. |
hx-format-date | Exempt | Not Applicable | Not Applicable | Not Applicable | Formatter primitive; renders inline text. |
hx-visually-hidden | Exempt | Supports | Supports | Not Applicable | A11y utility primitive — provides visually-hidden text by design. |
hx-code-snippet | Exempt | Pending audit | Pending audit | Not Applicable | <pre><code> wrapper; copy-button accessible name audit pending. |
hx-copy-button | Exempt | Pending audit | Supports | Supports | Live-region announce on copy audit pending. — AAA-cert 2026-05-08 |
Testing Methodology
Section titled “Testing Methodology”HELiX’s accessibility evidence is layered across automated, runtime, and manual review tiers.
Automated tests (CI-gated)
Section titled “Automated tests (CI-gated)”- axe-core integration via
packages/hx-library/src/test-utils.ts— component test files may runcheckA11y()againstwcag2a,wcag2aa, andbest-practicetags. Coverage is per-component, not universal: the helper is invoked from the test files that opt into it. The formal AAA cert relies on the audit harness’s own checks (scripts/aaa-formal-audit.mjs) rather than axe-core for the AAA verdicts; axe-core remains the canonical AA smoke layer for stories that wire it. - Contrast regression matrix —
packages/hx-tokens/src/__tests__/contrast.test.tswalks every semantictext.* × surface.*pair across light, dark, and high-contrast modes; asserts AA thresholds (4.5 body / 3.0 large) and logs AAA pass/fail (7.0 body / 4.5 large) informationally. - Forced-colors runtime adoption —
packages/hx-library/src/components/__tests__/forced-colors-runtime.test.tsinspects adopted stylesheets at runtime to confirm representatives from each forced-colors mixin family (interactive, field, surface, link, side-nav) emit the correct@media (forced-colors: active)block with the required system-color keywords.
Runtime evidence (Vitest browser mode)
Section titled “Runtime evidence (Vitest browser mode)”Vitest browser mode (Chromium via Playwright) provides a real DOM with shadow-root encapsulation. This is the source of truth for any assertion that depends on adopted-stylesheet behaviour, live-region timing, or focus management.
Manual review (per-component)
Section titled “Manual review (per-component)”When a component reaches AAA-cert review, a per-component AAA-AUDIT.md document is generated
alongside the source at packages/hx-library/src/components/<tag>/AAA-AUDIT.md. Each file
records the harness-measured WCAG SC-by-SC verdicts plus the prose evidence the harness wrote
for each (component × criterion) cell. Per-modality fields outside the harness’s measurement
surface — assistive-technology transcripts (NVDA + Chrome, VoiceOver + Safari, JAWS + Edge),
APG keyboard-pattern transcripts, forced-colors screenshots, and external auditor name / date —
are not captured in the generated audit files today; those belong to the third-party
attestation track in the Future work section.
Future work
Section titled “Future work”- HC-mode visual regression — Playwright
emulateMedia({ forcedColors: 'active' })is not exposed by Vitest browser mode (per the comment inforced-colors-runtime.test.ts). A separate Playwright VRT job is planned for v1.0 to capture screenshots in active forced-colors mode. - Third-party audit — Independent VPAT audit by an accredited accessibility auditor (target: pre-v1.0).
Differentiation vs USWDS
Section titled “Differentiation vs USWDS”HELiX competes directly with USWDS in the OSS enterprise-supported design system space. The table below summarises the differentiation surface from an accessibility-and-tokens posture, with citations to public USWDS sources.
| Axis | HELiX | USWDS |
|---|---|---|
| Conformance claim | WCAG 2.1 AA (gated) + AAA-targeted on P0 (in progress) | WCAG 2.1 AA only (USWDS Accessibility) |
| Token system | Separate npm package @helixui/tokens with light + dark + high-contrast modes | Embedded SCSS settings, no native dark mode (USWDS tokens settings) |
| Forced-colors coverage | Mixin family covers 100% of in-scope components (interactive / field / surface / link / nav) | 13 components covered per USWDS PR #4610 |
| Framework | Framework-agnostic W3C Custom Elements (Lit 3.x) — works in React, Angular, Vue, Drupal, plain HTML | Sass classes + vanilla JS; React wrapper is community-maintained, not first-party |
| Distribution | npm + CDN (per-component entry points, tree-shakeable) | npm + CDN (Sass + compiled CSS bundle) |
| License + commercial support | MIT + commercial support available via Booked Solid Tech | CC0 1.0 Universal (public domain), no SLA, community-maintained |
| Contrast gating | CI-gated regression matrix across 3 modes | Manual contrast review |
| CEM-driven docs | Custom Elements Manifest with auto-generated React wrappers + Storybook autodocs | Manual SCSS / HTML reference |
| Testing posture | Vitest browser mode (real DOM, real shadow-root) + axe-core every test | Manual test plan; some automated checks |
Sources:
- USWDS Accessibility documentation
- USWDS GitHub
- USWDS PR #4610 — forced-colors expansion
- USWDS Design Tokens reference
Roadmap (post-v1.0)
Section titled “Roadmap (post-v1.0)”The header table at the top of this report shows v1.0 (Published) — the v1.0 milestone has
landed, with 44 P0 components reaching AAA-cert status (Supports verdicts across the 11-criterion
matrix, per aaa-verdicts.json). The phasing below tracks remaining engineering work toward
third-party attestation and the next AAA-cert wave.
Phase 1 — Foundation (complete)
Section titled “Phase 1 — Foundation (complete)”- Forced-colors mixin family (interactive / field / surface / link / nav)
- Forced-colors runtime adoption tests (representative coverage)
- Contrast regression matrix (AA gated, AAA verified) across 3 modes
- Cross-shadow-boundary
:focus-visiblebaseline - VPAT 2.5 v1.0 published — this document
- AAA contrast verdict promoted to CI gate via
scripts/check-aaa-verdicts.mjs
Phase 2 — P0 keyboard parity
Section titled “Phase 2 — P0 keyboard parity”- Per-component keyboard test parity (every interactive component)
- APG-pattern conformance audit (combobox, menu, tabs, dialog, tree-view, slider)
- Cross-shadow-boundary label /
aria-describedbyassociation remediation (hx-fieldfamily)
Phase 3 — P0 AAA-cert wave 1
Section titled “Phase 3 — P0 AAA-cert wave 1”- AAA-AUDIT.md for the 10 highest-traffic P0 components (form inputs + buttons + dialog + side-nav)
- Third-party accessibility auditor review
- HC-mode visual regression (Playwright VRT in active forced-colors)
Phase 4 — P0 AAA-cert wave 2
Section titled “Phase 4 — P0 AAA-cert wave 2”- AAA-AUDIT.md for the remaining ~30 P0 components
- Third-party accessibility auditor sign-off on the P0 surface
Phase 5 — v1.0 publication
Section titled “Phase 5 — v1.0 publication”- VPAT v1.0 publication with 30+ P0 components at AAA-cert
- Public commitment to AAA conformance for the P0 surface
- CI-gated AAA contrast posture (promoted from informational logging)
- Section 508 + EN 301 549 conformance attestation
References
Section titled “References”- WCAG 2.1 — W3C Recommendation
- WAI-ARIA Authoring Practices Guide (APG)
- Section 508 — 36 CFR Part 1194
- EN 301 549 V3.2.1 (2021-03)
- VPAT 2.5 Rev 508 template — ITI
- USWDS Accessibility documentation
- HHS Section 504 Digital Accessibility rule
- HELiX AUDIT-REPORT.md
@helixui/tokenscontrast regression matrix@helixui/libraryforced-colors runtime tests