feat(skill): add accessibility reference

[dylan-isaac]

Closes #118.

Summary

Adds accessibility guidance to the Arrow agent skill — minimalist shape per the "keep token count low" request in the issue thread. Also documents the Arrow template-parser rule for dynamic attribute ids, which is load-bearing for ARIA wiring.

Commits

1. feat(skill): add accessibility reference — references/accessibility.md (new, 24 lines), two examples in references/examples.md, and a rule of thumb in SKILL.md.
2. docs(skill): note attribute-slot rule in api.md — documents Invalid HTML position and the precompute fix.
3. docs(skill): close a11y gaps from testing — APG tabs keyboard handler + imperative-DOM bridge examples; reactive-list callable wrap and event-handler typing bullets in api.md.

Total: ~120 lines across 4 files.

Divergence from the issue proposal

The original proposal asked for references/patterns/ with per-widget docs (accordion, tabs, dialog, disclosure, menu). I prototyped that shape (~1,000 lines, 9 files) and decided against it:

• Per-pattern files largely re-author WAI-ARIA APG content, which drifts over time and bloats the skill.
• A principles file + APG link achieves "accessible by default" at <10% of the token cost.
• Arrow-specific value sits in gotchas and native-first reminders, not in reproducing WAI-ARIA.

Arrow-specific content

Enumerated ARIA vs setAttr. packages/core/src/dom.ts:16-18 removes an attribute when an expression returns JS false. Correct for boolean HTML attrs, wrong for aria-expanded / aria-pressed / aria-selected / aria-checked / aria-current where absence ≠ "false". Called out with ✅/❌ examples.

Native-first reminders. <details>, <dialog>, <input type="checkbox" role="switch">.

APG keyboard handler example. Concrete tabs example showing roving tabindex (strings), Arrow/Home/End keys, and queueMicrotask for post-update focus. Closes the gap where "implement the keyboard section" as guidance alone produced partial output.

Imperative DOM bridge. Arrow has no ref primitive; the skill now documents watch() + querySelector as the reactive → imperative pattern. Load-bearing for native <dialog>, <video>, <canvas>, focus management.

Attribute-slot rule (api.md). ARIA wiring is almost entirely dynamic id attributes — aria-controls="panel-${id}", aria-labelledby="header-${id}", id="tab-${key}". Arrow's template parser requires attribute expressions to be the entire value; partial interpolation throws Invalid HTML position. Accessibility doc tells agents which attributes to use; api.md rule tells them how to build the id strings without crashing.

Event handler typing (api.md). ArrowExpression (packages/core/src/html.ts:75) accepts EventListener or (e: InputEvent) => void. Narrower signatures like (e: KeyboardEvent) => void fail typecheck — documented with the widen + cast fix, essential for APG keyboard handlers.

Reactive list callable wrap (api.md). ${() => items.map(...)} is required for dynamic lists. Every ARIA list (tabs, combobox options, rows) hits this.

Testing

Generated 5 scenarios (disclosure, dialog, tabs, status, todos) with fresh subagents — once without the skill, once with it injected. Deltas:

Scenario	Without skill	With skill
Disclosure	String(state.open) works	explicit ternary, works
Dialog	<div role="dialog">, no focus trap	native <dialog> + showModal()
Tabs	roles only	roles + roving tabindex + .key() (still no kbd)
Status	redundant aria-live	clean role="status"
Todos	.key() + aria-label	identical

The tabs gap (no keyboard handler) and the dialog "no ref primitive" question both surfaced here — addressed by commit 3.

Validation

Ran a fresh Claude Code session in a new directory with the skill available. Generated implementations of the same 5 scenarios. Every load-bearing claim from this PR shows up in the output: native <dialog> with watch()+getElementById bridge, APG tabs with Arrow/Home/End + queueMicrotask focus, reactive aria-* as strings, EventListener typing with inline cast, precomputed id strings.

Test plan

• pnpm test — 245 passed
• Reviewer: sanity-check the single-file shape vs. per-pattern files — happy to add targeted pattern docs (e.g., references/patterns/combobox.md) if specific widgets need deeper Arrow-specific coverage