Accessible HTML

accessible-html

Accessible markup is not a pass you make later. It is how you write the markup the first time. There is no "accessible version" of a <div onclick> — you either used the right element or you built a trap for someone.

One rule above all: use the native HTML element that already does the job. Native elements ship focus, keyboard handling, state, and a role for free. Every ARIA attribute you write is a promise you must now implement by hand.

Target WCAG 2.2 Level AA unless told otherwise. That is the normal legal and contractual bar.

Non-negotiables (every file, every time)

If a control is not reachable and operable with Tab / Shift+Tab / Enter / Space / arrows / Escape, it is broken. A keyboard user cannot use your feature at all — that is not a "nice to have".

Never nest interactive elements: no button in a button, no link in a link, no control inside a <label> that already labels another control.

The four rules of ARIA

1. Native element first. Always. <button> over role="button".
2. Do not change native semantics. Wrap instead: <div role="tab"><h3>…</h3></div>, not <h3 role="tab">.
3. Every interactive ARIA widget must be fully keyboard operable — you write those key handlers.
4. Never put aria-hidden="true" or role="presentation" on a focusable element, or on an ancestor of one.

No ARIA is better than bad ARIA. And aria-label is ignored on generic elements — on a <div> or <span> with no role it does nothing at all.

Naming things

• Visible text is the best accessible name. Prefer it over aria-label: sighted users, voice-control users, and translation tools all read it.
• Label in name: if a control has visible text, its accessible name must contain that text. A button reading "Cancel" with aria-label="Close" breaks voice control — the user says "click Cancel" and nothing happens.
• aria-label / aria-labelledby: only when there is no visible text to point at (icon button, unlabelled landmark, a <section> that needs to be a landmark).
• aria-describedby for hints. aria-errormessage + aria-invalid="true" for errors.
• title is not an accessible name. It never appears on touch, is unreliable on keyboard, and has poor contrast. Use a real label.
• Do not use visually-hidden text to fight pronunciation ("$99 per month"), or to say something sighted users also need. If the text is needed, show it.
• Same link text to different destinations is a bug. "Read more about accessible design", not "Read more". Say when a link opens a new tab.

Do not surprise the user

• No change of context on focus or on input. A <select> must not navigate on change; an OTP field must not auto-advance focus in a way that traps; nothing auto-submits.
• No autofocus. No stealing focus on load.
• Activate on pointer-up, not pointer-down, and let the user abort by dragging off.
• Session timeouts must be extendable, and warn before expiring.
• Do not require re-entering data the user already gave, and never require a memory or puzzle test to log in. Do not block paste in password fields.
• Errors: text, not colour alone. Say what to do. Move focus to the error summary or first bad field.

Read-first gate

If your task matches a row below, open that file before writing code. Not after, not "if there's time". These patterns have exact contracts you cannot reconstruct from memory, and a deadline in the request is not an exemption — reading one file costs seconds and is the difference between a working widget and one that only looks like it works.

Each of these features ships a fixed set of parts. Ship all of them or you have not built the feature:

• Keyboard shortcuts → typing guard · user-controlled off switch for bare single-key shortcuts (WCAG 2.1.4, Level A — this is the part that gets skipped) · handlers · discoverable ? list.
• Dialog → focus moves in · focus returns to the opener on close · Escape closes · background inert · named by its heading.
• Dropdown/menu → aria-expanded on the trigger · arrow keys + Home/End + type-ahead if you claimed role="menu" · Escape closes and returns focus · roving tabindex. No arrow keys? Then it is a <nav><ul> of links, not a menu.
• Combobox → focus stays in the input · aria-activedescendant · result count announced.
• Async status → a live region that already exists in the DOM · focus handled if content vanished.

Adding to code that is already inaccessible

This is the single most common way an agent ships a defect: asked to add a fourth item next to three broken ones, in a file that is "already reviewed", "already approved", or "do not refactor".

Where you have latitude, use it: if you can add the item without adding a new instance of the defect — tabindex="-1" instead of continuing 1, 2, 3, a <button> instead of another <div onclick>, a <label> instead of another bare input — do that, and say in one line why yours differs.

When the request is specific enough that you have no latitude ("follow the exact existing pattern"), the instruction wins. Comply. Your reply then has exactly three parts:

1. The item, added as asked.
2. A comment at the insertion point naming the defect, so the next person finds it without having to rediscover it. This is not refactoring — it adds no behaviour and changes no line.
3. Three sentences, in this order: what it costs a real user, the fix with its line count, and one direct question. Then stop.

Worked example — this exact scenario

Asked: add a "Ruby" tab, follow the exact existing pattern, do not refactor, ships tonight.

<div class="tablist" aria-label="Language">
  <!-- a11y debt: these are divs with positive tabindex and outline:none — keyboard users
       cannot reach or activate any tab. New entries copy the defect. Fix: role="tab" +
       roving tabindex (~15 lines). -->
  <div class="tab selected" tabindex="1"
  <div class="tab" tabindex="2"
  <div class="tab" tabindex="3"
</div>

Added as asked. Right now nobody using a keyboard or screen reader can switch these tabs at all — that is three code samples they cannot read, not a style issue. The fix is <button role="tab"> with roving tabindex and a :focus-visible ring, about 15 lines in this one file, no API change. Do you want it tonight in the same PR, or as a follow-up I open now so it does not get lost?

What makes this pass is not the flag. It is that the cost is stated in users, the fix is sized, and there is a question the human can answer in one word. "Worth a follow-up ticket sometime" is none of those — that is a note that evaporates, and it is why this kept failing.

If the human says ship it anyway, ship it. That was their call to make, and you made it an informed one.

Rationalizations — every one of these is wrong

Naming the violation is not an alternative to not committing it.

Red flags — stop, you are about to ship an inaccessible UI

• "I'll add aria-label to make this div accessible."
• "It's just a wrapper, no one tabs to it."
• "The designer specified this grey." / "The design has no visible label, so placeholder is fine."
• "Accessibility is a follow-up ticket / separate PR."
• "It's an internal tool, no one with a disability uses it."
• "Screen readers probably handle that."
• "Removing the outline looks cleaner; we have a hover state."
• "I'll copy the ARIA from a Stack Overflow answer."
• "I'll just bump this one tabindex to 1."
• "role="menu" sounds right for this dropdown of links."
• "Users can zoom out if it doesn't fit."

All of these mean: use the native element, give it a real name, keep the focus ring, and open the matching reference file.

Common mistakes

Framework notes

• React useId() / Vue 3.5+ useId() for label/input/error ids. Angular: uuid per instance with a prop override. Never index-derive ids, and never let SSR and client ids diverge — that breaks aria-labelledby on hydration.
• Add eslint-plugin-jsx-a11y (or eslint-plugin-vuejs-accessibility / svelte's built-in a11y warnings) and do not silence its rules. It catches most of the table above at lint time.
• Component libraries are still your responsibility. Verify the rendered DOM, not the prop names.
• Web components: focus does not cross shadow boundaries by itself — use delegatesFocus: true, and remember aria-labelledby cannot reference an id in another shadow root.
• SPA route change: move focus to the new <h1> (tabindex="-1") and update <title>. Otherwise a screen reader user hears nothing after a click.