Self-Certification Scope

Every “AAA Certified” badge on HELiX is a self-certification by the project maintainers, backed by an open-source formal harness whose source, methodology, and per-component evidence is all in the repo. It is not a third-party VPAT attestation. This page tells you exactly what each cert measured, what it didn’t, and where to look if you need to defend the claim to a procurement reviewer.

What “AAA Certified” means here

Cert authority: scripts/aaa-formal-audit.mjs

• 44 P0 components self-certed — library 3.9.0 surface
• 11 success criteria measured — 9 WCAG 2.2 AAA + 2 peer standards (forced-colors + APG keyboard)
• 1 primary audit story per component — many components use a curated AaaAudit (or similar) story rather than the bare Default so the harness measures the canonical AAA-shaped variant; the choice is per-component and recorded in the harness manifest

Brand × theme coverage (light / dark / forced-colors) is exercised by a separate, informational harness (pnpm aaa:matrix). The matrix is purely informational — it is not the cert authority and does not appear in the verdict snapshot. The formal audit is the only cert-authoritative measurement.

The cert authority is scripts/aaa-formal-audit.mjs (CLAUDE.md is explicit: the formal harness wins where any other tool disagrees). It sources every criterion from scripts/aaa-standards.json (W3C-verified URLs), spins up Playwright against a running Storybook, and produces measured verdicts plus evidence prose for each (component × criterion) cell. The raw output lives at .reports/formal-aaa-audit/audit.json and is regenerated when a maintainer runs pnpm aaa:audit locally (typically before a release; the release-publish workflow itself does not currently invoke the harness). The committed, consumable snapshot is packages/hx-library/aaa-verdicts.json — that file is the canonical evidence trail for consumers.

What is verified

Explicit affirmative measurements.

• Contrast (1.4.6 Contrast Enhanced) — measured via the contrast ledger (the committed @helixui/tokens contrast-data module that Storybook imports) plus axe-core color-contrast-enhanced sweep on the rendered audit story DOM. The current ledger records 160 pair-instances all clearing the AAA threshold. Per-component evidence records the foreground / background RGB pair and ratio for canonical 1.4.6 entries; many entries are Not Applicable (component has no text on its own surface) or inherit consumer backgrounds (no fixed pair to record). WCAG 1.4.11 (Non-text Contrast) is the AA-tier UI contrast criterion and is verified separately via the contrast ledger / forced-colors signals — it is not one of the 11 formal AAA criteria measured here.
• Keyboard contracts (2.1.3, APG-keyboard) — for every interactive primitive with an APG pattern, the formal harness verifies the contract by source inspection — string-matching keydown / keyup handlers against the APG-documented key set, plus native delegation where the host element is a real <button> / <input> / <a>. The harness does not synthesize keystrokes against the rendered DOM to confirm activation; that’s covered by per-component Vitest browser tests.
• Focus indicator (2.4.13) — measured against the rendered focus state of the audit story; verdict records the actual outline and box-shadow values.
• Forced-colors — the source CSS is scanned for forbidden patterns (color-bound borders, opacity-based hide-states, non-system color tokens in forced-color modes). The harness does not boot a browser into Windows High Contrast and capture a rendered screenshot; that visual confirmation is informational work tracked under the brand × theme matrix.
• Error prevention (3.3.6) — applies to form-associated input components. Submission triggers (aria-pattern=button) are NA — 3.3.6 is a form-flow contract the consumer app fulfills, not a leaf-component contract. Input components must expose ElementInternals + setValidity() so the consumer’s form gets native form-validity participation; without setValidity, the verdict is Partially Supports.
• The remaining 5 criteria — 1.4.9, 2.3.3, 2.4.12, 2.5.5, 3.2.5 — apply per component class; see the Success Criteria page in Storybook for the per-component applicability table.

What is NOT verified by this cert

Honest limits.

• Non-default story states. A component like hx-button ships 49 stories (variant × tone × size × loading × disabled × icon-only × …). The AAA harness measures the Default story. Variant coverage is asserted separately by the story-audit harness (scripts/audit-stories.mjs) which renders every story and flags blank canvases, contrast failures on rendered text, and axe violations across the whole story surface. The two harnesses together cover the surface; the AAA cert badge itself is scoped to the Default story.
• axe-core ElementInternals coverage gap. axe-core PR #5080 (unmerged) means that ElementInternals-attached ARIA on form-associated components is not visible to axe’s rule engine. Where this matters, the harness uses DOM-level fallback assertions; see axe-core ElementInternals Gap for the documented policy.
• Consumer-fulfilled criteria. The Consumer Obligations page covers 7 partial-applicability AAA SCs (1.3.6, 1.4.8, 2.2.4, 2.2.6, 2.4.10, 3.1.4, 3.3.5) — those depend on consumer composition / content authoring, not the component library, and the cert badge does not assert them on the consumer app’s behalf. See Consumer Obligations for the full contract. Base-level structural SCs (1.3.1 Info & Relationships, 1.3.2 Meaningful Sequence) are Level A engineering targets that the Storybook ledger marks as pass via axe + interaction tests; they sit outside the 11-criterion AAA matrix on this page.
• Live runtime behavior under assistive tech. The harness simulates keyboard and inspects DOM; it does not drive NVDA, JAWS, VoiceOver, TalkBack, or Orca. AT smoke runs are tracked separately and not part of the cert badge.

Where to read the evidence

• Per-component audit files — inside each component directory under packages/hx-library/src/components/<name>/AAA-AUDIT.md — verdict prose, evidence values, citations.
• Verdicts snapshot (committed) — aaa-verdicts.json. The canonical machine-readable verdict surface for every (component × criterion) cell, with evidence strings (text describing the measurement and citation source). This is the AAAConformanceCard data source on every docs page.
• Raw audit JSON (locally regenerable) — .reports/formal-aaa-audit/audit.json and audit.matrix.md are produced by pnpm aaa:audit against a locally running Storybook. They are gitignored and intentionally not linked from these docs — the canonical committed artifact is the verdicts snapshot above. Maintainers regenerate them before a release; consumers can reproduce them locally.
• Story audit (multi-variant) — audit-stories.mjs. Renders every story across every component, screenshots the canvas, runs axe on the rendered DOM, and writes findings as JSONL.

When a third-party VPAT is required

Next steps.

Self-certification is appropriate for an OSS component library shipping under a permissive license; it is not appropriate when an enterprise procurement process requires a VPAT 2.5 attestation signed by an external auditor. If you need that, the harness output here is the starting evidence package — every measurement is reproducible from the repo, every citation links to the W3C source, and every component’s evidence trail is versioned. The shipped VPAT 2.5 v1.0 is the authoritative consumable summary; a third-party auditor signing off on a procurement-grade VPAT would still need to verify the underlying methodology and re-run measurements themselves.