a11y-annotate

a11y-annotate

How to read, write, and maintain a11y.md — the markdown file that captures composition-level accessibility intent for a page or prototype.

The loop

On every UI turn that touches composition (whether or not this skill is explicitly invoked):

1. Read. Walk from the file being edited up to the repo root. Open every a11y.md found. The union of claims is ground truth.
2. Apply. Make sure new code satisfies every claim relevant to the change. If the code contradicts a rationale-bearing claim the user hasn't asked to change, stop and surface it. Don't silently overwrite.
3. Update. After the change, reflect any new composition-level intent in a11y.md. Preserve every Rationale: line verbatim. Flag claim changes in the turn summary, not just the diff.

Sections

a11y.md has nine sections in fixed order. A minimal WCAG-target header sits above section 1. All sections are always present in every file; no frontmatter, no YAML, no schema.

Empty is meaningful — when a section has no claims for this page, write a single bullet saying so, with a brief reason where helpful:

## Reading order
*Empty when DOM = visual. <visual> → <DOM> for any mismatch.*

- Empty — DOM matches visual.

The bullet signals the section was considered, not forgotten.

The sections layer from wrapper to escape:

• Wrapper: Landmarks.
• Content: Headings, Images.
• Interaction: Forms, Controls.
• Consequences: Live regions.
• Reconciliation: Reading order, Focus (written last; depend on everything above).
• Escape: Notes (last resort).

When writing claims on a new route, don't attempt Reading order or Focus before the sections they integrate have been established.

Header:

**WCAG target:** WCAG 2.2 AA

Each ## header is followed — on the immediately next line, no blank in between — by a one-line italic prompt describing what belongs in the section. The prompts are part of the file format: preserved across edits, kept in empty sections as well as filled ones.