docs: ACCESSIBILITY.md — the specs every package answers to

[ivanbanov]

Dunky is substrate-agnostic, but its accessibility contract shouldn't be invented per package. This adds ACCESSIBILITY.md at the root: the external specs that bind every primitive, how a reference enters a package, and what a non-web substrate is allowed to do differently.

Why the web specs, for a substrate-agnostic repo

Behavior is modeled once in packages/core/<name> and every substrate inherits it. That only works with a single external definition of what the behavior is — otherwise each host drifts toward whatever its platform makes easy. The W3C specs are that definition: normative, stable, already mapped onto the native platform accessibility APIs by Core-AAM, and the documents our consumers audit against.

So the core machine speaks in ARIA terms and holds itself to WCAG; a binding translates those terms into its host's API. Translation may change the words, never the behavior — a host that forces a behavioral difference sends the decision back into the core machine, per the existing Boundaries rule.

What's in it

• The primary references: WCAG 2.2, WAI-ARIA 1.2, UAAG 2.0, ATAG 2.0, with WCAG 3.0 explicitly direction-only. Plus the supporting set that keeps coming up: APG (advisory), Accname, WCAG2ICT, ARIA in HTML.
• Two version notes, so they aren't re-litigated per package: WAI-ARIA is pinned to 1.2 (1.1 is superseded; 1.3 is a draft), and WCAG 2.2 is a Recommendation, not a candidate one.
• How a package references a spec: a ## Reference section in its SPEC.md linking the exact sections it relies on — core/dialog and dom/utils/focus-trap already do this. The API is cross-matched against it during RECONCILE; where the API and a normative spec disagree, the API is the bug unless the deviation is justified in that package's SPEC.
• Non-web substrates: three tiers — mapping (free), extra instruction (documented in the substrate's own spec), and override (must record the rule, what happens instead, why the host forces it, and what the user still gets). An override reinterprets a mechanism; a different decision is a core change. Terminal UIs get called out as the sharpest case: no ARIA, no accessibility tree, no normative spec.
• Verifying: which layer tests which claim — core semantics, substrate translation, device/browser for what a mocked host can't reach.

AGENTS.md gains a four-line ## Accessibility section pointing at it. Deliberately just a pointer — nothing from the doc is restated, so there's one home for the rules.

Stacked

First of two. #41 builds on this branch and is the first fix found by applying the doc to existing code.

🤖 Generated with Claude Code