accessibility-implementation

Cross-cutting accessibility guidance for design, implementation, and review. Apply the parts relevant to the current task; no agent-specific hooks are required.

When to load

• Designer — producing a Design Spec with any user-facing UI
• Implementer — implementing components, pages, forms, or interactive flows
• Reviewer — auditing a PR that touches HTML, JSX, or any UI code
• Problem — investigating a reported a11y incident

The 8 non-negotiables

1. Use native <dialog> + showModal(). You get focus trap, Escape, and inert background for free. Do not build a modal from <div> unless you have a reason that survives a 5-minute audit. (Native <dialog> has implicit modal semantics — do NOT add aria-modal='true'; the browser handles it.)

2. Focus management is non-negotiable. On open, focus moves into the dialog (capture document.activeElement). On close, it returns to the trigger. A modal that drops focus on close is broken for keyboard users, even if it "looks fine."

3. Never autoFocus a destructive action. Delete, Remove, Reset must focus Cancel, the dialog itself, or nothing. autoFocusing Delete means a screen-reader user who hits Enter reflexively destroys their data. Destructive buttons must specify the object: "Delete account" not "Delete".

4. ARIA fills gaps semantic HTML cannot. aria-labelledby and aria-describedby on dialogs. aria-live for state changes. aria-expanded for disclosure widgets. If semantic HTML covers it, do not add ARIA.