Accessibility API (hedron_core.a11y)¶
Stability
Classifications for this surface are recorded in STABILITY.md.
hedron-core is Stable in the coordinated 1.0 inventory; API compatibility level
for this surface is still typically beta.
Status: Introduced in 0.19 (v0.19.0); available on the current 1.1.x train
Import from hedron_core.a11y. Adopter guide: Accessibility ·
Narrative: What's new in 0.19.
Owning RFCs (GitHub): 0051– 0055 (umbrella 0023).
These APIs record obligations and evidence. They do not auto-claim WCAG, legal compliance, certification, or VPAT/ACR.
Profile (PROFILE-019)¶
| Symbol | Role |
|---|---|
AccessibilityProfile |
Pinned normative baseline (WCAG 2.2 A/AA, WAI-ARIA 1.2, ACT/axe pins) |
ACCESSIBILITY_PROFILE |
Default instance (profile_id="hedron-a11y-0.19") |
ClaimBoundary |
Explicit non-goals (forbids_auto_wcag_conformance, …) |
from hedron_core.a11y import ACCESSIBILITY_PROFILE
profile = ACCESSIBILITY_PROFILE.as_dict()
assert profile["claim_boundaries"]["empty_scan_is_not_accessible"]
Contract (CONTRACT-019)¶
| Symbol | Role |
|---|---|
AccessibilityContract |
Leaf/package obligations (semantics, keyboard, focus, limitations, waivers) |
AccessibilityContractCatalog |
Registry-backed catalog; seed_reviewed_contracts for curated set; ensure_registry() fills unreviewed stubs |
REQUIRED_REVIEWED_CONTRACTS |
Curated components that must ship reviewed=True at cut |
default_contract / reviewed_contract / seed_reviewed_contracts |
Helpers |
contract_for_registered |
Lookup for a registered component name |
AccessibilityContract.implies_application_conformance() is always False. Only names in
REQUIRED_REVIEWED_CONTRACTS must ship reviewed=True at cut; other registry components may
remain stubs until reviewed.
from hedron_core.a11y import AccessibilityContractCatalog, seed_reviewed_contracts
catalog = AccessibilityContractCatalog()
seed_reviewed_contracts(catalog)
catalog.ensure_registry() # optional: fill remaining registry stubs
page = catalog.contracts["Page"]
assert page.reviewed
assert not page.implies_application_conformance()
Scenario (TEST-019)¶
| Symbol | Role |
|---|---|
AccessibilityScenario |
Named steps, covers, engine versions, findings |
AccessibilityFinding |
Rule/impact/message with automatic / semi-automatic / manual status |
AccessibilityTreeNode |
Role/name/tag/state node |
snapshot_accessibility_tree |
Markup heuristic from HTML — not a browser AT tree |
axe_to_sarif |
Convert axe-style findings to SARIF (level mapped from axe impact) |
AccessibilityScenario.summarize() returns accessible: False always; with no findings
status is "incomplete" (“not evidence of accessibility”). Prefer Playwright
get_by_role for live AT-019 evidence.
Governance (GOVERN-019)¶
| Symbol | Role |
|---|---|
Waiver |
Owned, dated waiver (validated() rejects expired / incomplete) |
EvidenceInventory |
Contracts, automation results, human AT rows, waivers, limitations |
HumanAtRecord |
Redacted human AT ledger row (0.21 / D-052); redacted must be boolean True; gate/task IDs must be string arrays |
AccessibilityStatement |
Human-approved statement template; requires approved_by to export() |
refuse_auto_conformance_claim |
Raises HED-A11Y-0011 for automatic claim kinds |
from hedron_core.a11y import AccessibilityStatement, HumanAtRecord
statement = AccessibilityStatement(
scope="Internal admin app (authenticated)",
contact="a11y@example.com",
approved_by="release-owner",
)
payload = statement.export() # conformance_claim is always None
Human AT protocol and ledger templates: docs/acceptance/human-at/ (phase 0.21 engineering-complete / sessions outstanding).
Surfaces (INTERACT / MEDIA / COG / I18N helpers)¶
| Symbol | Role |
|---|---|
validate_page_structure |
Title / lang / landmarks / headings / skip-link smoke report |
StructureReport |
Result of structural validation (ok when issues empty) |
TargetSpacingPolicy |
WCAG 2.2 target size / spacing guidance |
MediaTrackContract |
Caption / transcript / audio-description obligations |
CognitivePreferences |
Authoring prefs (reduced motion, density, …); does not judge prose |
Errors¶
| Code / condition | Behavior |
|---|---|
HED-A11Y-0010 |
Expired waiver |
HED-A11Y-0011 |
Automatic conformance / legal / certification / VPAT claim refused |
HED-A11Y-0012 |
Statement export() without approved_by |
Invalid Waiver, HumanAtRecord, or media track fields |
ValueError; serialized booleans and arrays are type-checked without truthiness/string iteration |
Related product surfaces¶
| Surface | Notes |
|---|---|
Explorer /hedron-explorer/a11y |
Review workspace (hedron[dev]) — Explorer |
Page(scripts=) |
Allowlisted same-origin PE scripts — Page |
| Landmarks | Safe exports + safe attrs — Landmarks |
hedron.testing.browser |
Playwright / axe helpers — Testing |
AT-019 |
Automated three-engine matrix Verified on 0.19; human AT → 0.21 (D-052 engineering-complete / sessions outstanding) |