ARIA & Accessibility Field Guide

01 · Standards baseline

Separate production requirements from guidance and horizon signals

Conformance, implementation guidance, browser mappings, and interoperability evidence answer different questions. Treating them as interchangeable creates false assurance.

What must be correct

ARIA in HTML authoring conformance.
WAI-ARIA 1.2 roles, states, and properties.
WCAG 2.2 as the product acceptance target.

S1 · S2 · S3

How behavior should work

APG patterns for keyboard and focus conventions.
WCAG Understanding and techniques for interpretation.
ACT Rules for automatable assertions.

APG is informative, not a conformance standard or production design system.

What browsers and AT expose

HTML-AAM and Core-AAM mapping specifications.
ARIA-AT support tables and test results.
Product-specific browser and AT evidence.

Support tables guide test priority. They do not replace product testing.

What may change next

WAI-ARIA 1.3 working-draft features.
Continuing HTML-AAM alignment.
Expanding automated AT interoperability coverage.

Track for roadmap planning. Do not silently promote drafts into the production baseline.

Recommended policy

Ship against WCAG 2.2 and ARIA 1.2 conformance. Use APG to define interaction contracts. Use HTML-AAM and ARIA-AT to understand exposure and test risk. Track ARIA 1.3 separately until it advances beyond Working Draft.

ARIA 1.3 horizon watch

The June 2026 Working Draft includes additions such as comment, suggestion, and mark roles, plus properties such as aria-description. These are useful roadmap signals for collaborative editing and richer description models, but draft status and interoperability evidence must remain explicit.

Do not backport draft semantics casually.

Prefer existing native and ARIA 1.2 patterns until browser, accessibility API, assistive-technology, and authoring-rule support is demonstrated for the target environment.

02 · Decision model

Choose semantics before styling

Follow this sequence for every interactive component. A visual design should not determine the role.

Identify the user task

Is the user navigating, submitting, selecting, toggling, expanding, editing, or issuing an application command?

Select native HTML

Prefer button, a, input, select, details, dialog, and table.

Find the semantic gap

Add only the missing name, state, relationship, live announcement, or custom-widget role.

Implement behavior

Match keyboard navigation, focus movement, activation, cancellation, selection, and disabled behavior.

Synchronize state

The visual state, DOM state, ARIA state, and application state must describe the same condition.

Validate with users and tools

Inspect keyboard operation, focus order, announcements, zoom, reflow, contrast, and real assistive technology.

A role is a promise.

role="button" promises button behavior. It does not create Enter or Space activation, focusability, disabled behavior, or form semantics.

03 · Name contract

The accessible name is part of the component API

The name must remain perceivable, stable, localizable, and aligned with visible text. Descriptions supplement the name. They do not repair a missing label.

Preferred naming sources

1
Visible native text
Button text, link text, heading text.
2
Native association
label, legend, caption, alt.
3
aria-labelledby
References visible text already present in the interface.
4
aria-label
Use when a visible label is not practical, such as an icon-only control.

Name invariants

The visible label is contained in the accessible name.
The name describes the action or object, not its appearance.
State does not unexpectedly rewrite the control identity.
Translations preserve the same task and relationship.
Descriptions and errors remain supplemental and specific.

Voice-control risk

If visible text says “Send” but the accessible name begins with “Submit application,” speech users may not be able to activate the control by its visible label.

Visible label

Optional aria-label

Effective source: Visible text
Authoring preview: Save changes
Label alignment: Pass: visible label is contained in the name.

04 · Role cost catalog

Roles by semantic and interaction cost

Search by role, native equivalent, required behavior, category, or review tier. High-cost composite widgets require centralized ownership and assistive-technology evidence.

Showing all roles.

ARIA role catalog with native alternatives and implementation obligations
Role	Category	Native first	Use when	Primary obligation	Review tier
`button`	Widget	`<button>`	A non-native element must act as a button.	Focus, Enter and Space activation, disabled behavior.	Component review
`checkbox`	Widget	`<input type="checkbox">`	A custom binary or tri-state selection is unavoidable.	`aria-checked`, Space activation, label, focus.	Component review
`radio`	Widget	`<input type="radio">`	A custom mutually exclusive option is unavoidable.	Group semantics, checked state, arrow-key model.	Component review
`switch`	Widget	Checkbox or button	The binary state is explicitly understood as on or off.	`aria-checked`, stable label, immediate state change.	Component review
`slider`	Widget	`<input type="range">`	A custom continuous-value control is essential.	Arrow/Home/End keys, min/max/current value, orientation.	Specialist review
`tablist`	Composite	Buttons may be sufficient	Mutually exclusive panels share one local context.	Roving focus, arrow keys, selection and panel linkage.	Specialist review
`menu`	Composite	Disclosure plus links	An application command menu behaves like desktop software.	Managed focus, arrow keys, Escape, type-ahead.	Specialist review
`listbox`	Composite	`<select>`	Native select cannot meet the interaction requirement.	Managed focus, selection, type-ahead, option ownership.	Specialist review
`combobox`	Composite	Input plus datalist/select	An editable or selectable popup requires custom behavior.	Popup state, focus strategy, active option, keyboard model.	Specialist review
`grid`	Composite	`<table>`	Cells are interactive like a spreadsheet.	Two-dimensional focus, row/cell semantics, edit mode.	Specialist review
`main`	Landmark	`<main>`	Normally implicit through native HTML.	One primary main landmark per rendered page.	Native preferred
`navigation`	Landmark	`<nav>`	Identify a significant navigation group.	Distinct labels when multiple navigation landmarks exist.	Native preferred
`search`	Landmark	`<search>` or labelled form	Identify site or application search.	Clear landmark name when multiple search regions exist.	Native preferred
`region`	Landmark	Named `<section>`	Content is a significant navigation destination.	Accessible name and restraint to avoid landmark overload.	Component review
`heading`	Structure	`<h1>`–`<h6>`	Usually only for environments without native headings.	Correct level and document outline.	Native preferred
`list`	Structure	`<ul>` or `<ol>`	Native list markup is unavailable.	Correct list-item ownership and meaningful grouping.	Native preferred
`status`	Live region	No direct equivalent	Routine dynamic information should be announced politely.	Update an existing region; do not move focus.	Component review
`alert`	Live region	No direct equivalent	An urgent condition requires immediate awareness.	Use sparingly; avoid interrupting routine work.	Component review
`dialog`	Window	`<dialog>`	A focused task appears in a separate window context.	Name, initial focus, containment, Escape, focus return.	Component review
`alertdialog`	Window	`<dialog>`	A brief urgent decision requires immediate response.	Concise message, explicit choices, disciplined focus.	Specialist review
`command`	Abstract	Never author directly	Only defines the ARIA ontology.	Do not use abstract roles in content.	Do not author

05 · State model

Names, states, and relationships

Roles answer “what is this?” These attributes communicate identity, condition, and connection.

Common ARIA state and relationship attributes
Attribute	Purpose	Typical use	Critical rule
`aria-labelledby`	Names an element using visible text elsewhere.	Dialog, region, control group.	Prefer visible labels over hidden-only names.
`aria-describedby`	Adds supplementary description.	Help text, constraints, validation explanation.	Do not use description as a substitute for a label.
`aria-expanded`	Reports whether controlled content is open.	Disclosure, accordion, menu button.	Place it on the controlling element and synchronize it.
`aria-controls`	Identifies controlled content.	Disclosure, tabs, accordion.	It describes a relationship; it implements no behavior.
`aria-current`	Marks the current item in a related set.	Page, step, date, location.	Do not confuse current with selected.
`aria-selected`	Marks selection inside a composite widget.	Tab, option, grid cell.	Selection and keyboard focus may be different states.
`aria-pressed`	Reports a toggle-button state.	Bold, mute, pin, favorite.	Keep the button label stable while the state changes.
`aria-checked`	Reports checkbox, radio, or switch state.	Custom selection controls.	Native checked state is preferable when available.
`aria-invalid`	Reports a value that failed validation.	Form field.	Connect the field to a specific error message.
`aria-busy`	Reports that a region is being updated.	Refreshing results or data panels.	Clear it when the update is complete.

Never publish contradictory state.

checked plus aria-checked="false" creates an invalid state model. Native HTML state takes priority.

06 · Focus architecture

Choose one focus model and document its invariants

Keyboard focus, visual selection, virtual cursor position, and application state are related but not interchangeable. Composite widgets fail when those states drift.

Comparison of focus management models
Model	Use for	Core invariant	Primary risk
Native DOM focus	Forms, disclosures, ordinary buttons and links.	Source order matches reading and interaction order.	CSS reordering or hidden overlays obscure the active control.
Roving `tabindex`	Tabs, toolbars, radio groups, menus, trees.	Exactly one managed child is in the sequential Tab order.	Two active Tab stops, stale selection, or focus loss after DOM updates.
`aria-activedescendant`	Comboboxes and large composites where DOM focus stays on a container.	The active descendant exists, is owned correctly, and remains perceptible.	Visual focus and announced focus diverge.
Modal focus scope	Dialogs and blocking workflows.	Initial focus is intentional; background is inert; focus returns logically.	Focus enters hidden content or returns to a removed invoker.
SPA route focus	Client-side navigation and major view changes.	Title, history, focus, and announcement describe the new view.	Content changes visually while screen-reader context remains in the prior view.

Focus not obscured is a layout invariant.

Sticky headers, drawers, banners, and virtual keyboards must not entirely hide the focused component. Test at zoom and narrow viewports, not only at the default desktop canvas.

07 · Native primitives

Modern HTML removes behavior that custom ARIA widgets once had to recreate

Use platform behavior where it fits. Native behavior still requires clear naming, intentional focus, and product-level interoperability testing.

<details> + <summary>

Disclosure

Built-in toggle, focusability, keyboard activation, and expanded-state exposure.

Do not override summary with role="button".

<dialog>

Modal or non-modal window

showModal() creates a modal top-layer context and makes the rest of the document inert.

Still define initial focus, accessible naming, cancellation, and return.

popover

Top-layer disclosure behavior

Provides show/hide, light dismiss, top-layer rendering, and declarative invokers.

Popover behavior does not automatically supply dialog, menu, or tooltip semantics.

inert

Suppress interaction and exposure

Inert content is generally not focusable and is not exposed through accessibility APIs.

Use for temporarily unavailable subtrees, not as a substitute for disabled control semantics.

hidden

Remove inactive content

Use when content should not participate in layout, interaction, or the accessibility tree.

Do not pair with redundant aria-hidden="true".

aria-hidden

Semantic-only suppression

Useful for decorative duplicates that remain visually rendered.

Never apply to focusable content or an ancestor of visible interactive descendants.

08 · Runnable patterns

Interaction contracts in practice

These examples are deliberately small. Each demonstrates the semantic baseline, state owner, keyboard behavior, and focus strategy.

Native foundation: Button plus ordinary links.
State: aria-expanded on the button mirrors hidden on the panel.
Keyboard: Native button activation. Links remain in normal Tab order.
Focus: Remains on the trigger when toggled.

<button
  type="button"
  aria-expanded="false"
  aria-controls="resources-panel"
>
  Resources
</button>

<div id="resources-panel" hidden>
  <a href="/guides">Guides</a>
</div>

Start with the native element and document the remaining semantic gap.

Role structure: tablist owns tab elements; each tab controls a tabpanel.
State: One tab has aria-selected="true"; inactive tabs use tabindex="-1".
Keyboard: Arrow keys, Home, and End use roving focus. This example automatically activates on focus.
Focus: One Tab stop enters the tab list.

Native foundation: <dialog> opened with showModal().
Name: aria-labelledby references the visible heading.
Keyboard: Escape closes. Tab remains within the modal browser context.
Focus: Initial focus moves to the heading; focus returns to the invoker.

No recent status message.

Role: status supplies polite live-region behavior.
Update: Change the text of an existing region after the action.
Focus: Never move focus merely to expose a routine message.

Announce deployment completion

Setting is off.

Foundation: Native button activation plus explicit switch semantics.
State: aria-checked changes; the visible label remains stable.
Keyboard: Enter and Space come from the native button.

09 · Component contract

Make accessibility part of the component API and ownership model

A reusable component is not complete until semantics, naming, state, keyboard, focus, announcements, fallback, testing, and operational ownership are explicit.

Component pattern

Exposure

TypeScript contract schema

type ReviewTier = "native" | "component" | "specialist";

type AccessibilityContract = {
  component: string;
  userTask: string;
  nativeFoundation: string;
  role: string | "implicit";
  nameSource: string;
  states: readonly string[];
  relationships: readonly string[];
  keyboard: readonly string[];
  focus: {
    entry: string;
    movement: string;
    return: string;
  };
  announcements: readonly string[];
  fallback: string;
  testMatrix: readonly string[];
  owner: string;
  reviewTier: ReviewTier;
};

10 · Page structure

Landmarks should reveal the information architecture

Landmarks are navigation destinations, not visual containers. Too many named regions produce a noisy, flat page map.

Recommended shell

One primary <main>.
Significant navigation groups use <nav>.
Multiple navigation landmarks receive distinct names.
Named sections represent meaningful destinations.
A skip link reaches the main content.

Do not create landmark noise

Do not turn every card into a region.
Do not add role="main" to <main>.
Do not use <nav> for every list of links.
Do not leave repeated navigation landmarks unnamed.
Do not rely on headings that describe styling rather than content.

<a class="skip-link" href="#main-content">Skip to main content</a>

<header>…</header>

<nav aria-label="Primary">…</nav>

<main id="main-content">…</main>

<aside aria-labelledby="related-title">
  <h2 id="related-title">Related resources</h2>
</aside>

<footer>…</footer>

11 · Forms

Separate the name, instructions, and error

A field label identifies the control. Help text explains constraints. An error explains what must be corrected.

No validation result.

Name: Visible label associated through for and id.
Description: Help and error text are supplemental descriptions.
State: aria-invalid appears only after failure and is removed after correction.
Focus: Failure returns focus to the first invalid field.

12 · Failure modes

Common ways accessible interfaces regress

These patterns often look correct visually while exposing a broken accessibility model.

`<div role="button">` by default

It recreates behavior the browser already implements. Use a native button.

Site navigation marked as `menu`

An ARIA menu promises a desktop command-menu keyboard model. Ordinary links should remain ordinary links.

Focusable content inside `aria-hidden="true"`

Keyboard focus can enter content that assistive technology cannot perceive.

Static ARIA state

A visual panel opens while aria-expanded remains false. State synchronization is part of the component contract.

Positive `tabindex`

Manual focus ordering becomes fragile as the DOM evolves. Use meaningful source order and roving focus only inside composite widgets.

Routine notices as alerts

role="alert" can interrupt current speech. Use status for ordinary confirmations and progress messages.

Grid semantics for a read-only table

A grid introduces two-dimensional focus and editing expectations. Use native table markup for tabular information.

13 · Validation strategy

Automate detection, not judgment

Automation catches structural defects. Human testing verifies whether the experience is coherent and operable.

Static checks

HTML conformance.
Unsupported ARIA attributes.
Invalid role ownership.
Duplicate IDs.
Missing accessible names.

Browser checks

Keyboard-only operation.
Visible and unobscured focus.
Zoom and narrow reflow.
Reduced motion.
Forced colors and contrast.

Assistive technology

VoiceOver with Safari.
NVDA with Firefox or Chrome.
JAWS where enterprise support requires it.
Voice control for visible label alignment.

Evidence record

Operating system and version.
Browser and version.
Assistive technology and version.
Input method and viewport.
Pass, failure, notes, and reproduction.

Recommended CI sequence

HTML conformance
  ↓
Static accessibility linting
  ↓
axe-core component tests
  ↓
Browser keyboard tests
  ↓
Focus and state assertions
  ↓
Manual assistive-technology testing

Minimum automated ARIA rule set

Minimum automated accessibility assertions
Assertion	Detects	Still requires human review
Role value is valid	Unknown or abstract authored roles.	Whether the role matches the user task.
ARIA attribute is defined and permitted	Typos and unsupported role/attribute combinations.	Whether the attribute communicates useful state.
Required states and properties exist	Incomplete custom-widget semantics.	State synchronization during every transition.
Accessible name is non-empty	Unnamed controls, links, fields, and images.	Name quality, visible-label alignment, and localization.
Hidden content is not focusable	`aria-hidden` conflicts with sequential focus.	Focus recovery and off-screen interaction traps.
ID references resolve	Broken labels, descriptions, controls, and ownership.	Whether the relationship is conceptually correct.

ARIA-AT evidence prioritizes testing; it does not certify the product.

W3C advises teams to perform their own tests across the browser and assistive-technology combinations relevant to the target audience.

When a component requires dedicated review

Require specialized accessibility review for comboboxes, listboxes, menus, trees, grids, rich-text editors, carousels, command palettes, drag-and-drop editors, and interactive canvas or diagram experiences.

14 · Enterprise considerations

Accessibility contracts must survive scale, localization, and asynchronous interfaces

Most production regressions occur at integration boundaries: routing, virtualization, permissions, loading, translation, design-system overrides, and cross-team ownership.

SPA routing

Update the document title and history. Move focus to a meaningful destination when the context changes. Announce asynchronous route completion without duplicating speech.

Loading and streaming

Use stable regions, aria-busy only while updating, and restrained status announcements. Avoid re-announcing the entire surface for incremental updates.

Virtualization

Preserve logical position, focus, selection, and row or set metadata. Never remove the actively focused item without a deterministic recovery path.

Localization and RTL

Localize visible and accessible names together. Mark language changes. Test expansion, pronunciation, bidirectional layouts, and keyboard conventions.

Permissions and disabled state

Distinguish unavailable, hidden, read-only, and disabled. Native disabled changes interaction; aria-disabled only communicates state and requires behavioral enforcement.

Custom elements

Define semantics at the component boundary. Verify label and relationship behavior across shadow roots, browser mappings, and framework hydration.

Telemetry

Track keyboard abandonment, validation loops, focus loss, repeated errors, and inaccessible fallbacks without collecting assistive-technology identity as a proxy for disability.

Ownership

Centralize high-cost composite widgets. Version their contracts, support matrix, evidence, known limitations, and deprecation path.

15 · CSS foundation

Small reset, explicit rhythm, resilient layout

The reset removes inconsistent assumptions. The base and layout layers then restore intentional spacing, focus, overflow, and control geometry.

Included in the reset

Universal border-box sizing.
100% text-size adjustment.
Explicit body and text-element margins.
List removal only for lists explicitly marked role="list".
Responsive block media.
Inherited form typography and color.

Explicitly excluded

appearance: none.
Global focus removal.
Global all: unset.
Unconditional smooth scrolling.
Global animation destruction.
Font-smoothing directives.
html { font-size: 62.5%; }.
Universal word breaking.

@layer reset {
  *, *::before, *::after {
    box-sizing: border-box;
  }

  html {
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
    tab-size: 4;
  }

  body { margin: 0; }

  :where(h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd) {
    margin: 0;
  }

  :where(ul[role="list"], ol[role="list"]) {
    margin: 0;
    padding: 0;
    list-style: none;
  }

  :where(button, input, select, textarea) {
    font: inherit;
    color: inherit;
    letter-spacing: inherit;
  }

  ::file-selector-button { font: inherit; }

  :where(img, picture, video, canvas) {
    display: block;
    max-inline-size: 100%;
  }

  :where(img, video) { block-size: auto; }

  svg { max-inline-size: 100%; }
}

Layout recalibration applied.

This guide uses intrinsic auto-fit grids, min-inline-size: 0, bounded horizontal scrolling for tables and code, safe-area padding, 44-pixel controls, explicit square-button geometry, and one sticky header on mobile.

16 · Delivery gate

Component accessibility checklist

Progress is stored locally in this browser. Use the checklist as a pull-request and design-review contract.

0 of 10 checks complete.

17 · Standards and provenance

Primary source ledger

Claims are separated by authority: normative production standards, informative implementation guidance, mapping drafts, and interoperability evidence.

S1Recommendation · 2026

ARIA in HTML

Author conformance requirements for using WAI-ARIA 1.2 attributes on HTML elements.

S2Recommendation

WAI-ARIA 1.2

Production role, state, property, and semantic model.

S3Recommendation · 2024

WCAG 2.2

Product-level conformance target. Includes focus not obscured, dragging alternatives, target size, redundant entry, and accessible authentication.

S4Informative guidance

ARIA Authoring Practices Guide

Keyboard, focus, naming, landmark, and widget-pattern guidance. Not a normative standard or production design system.

S5Informative guidance

APG Read Me First

Explains why incorrect ARIA can misrepresent the non-visual experience and why native semantics are preferred.

S6W3C Note · 2026

Using ARIA

Native-first authoring rules, keyboard obligations, and prohibitions on hiding focusable content.

S7Working Draft · June 2026

WAI-ARIA 1.3

Horizon specification. Track changes separately from the production baseline.

S8Working Draft · May 2026

HTML Accessibility API Mappings 1.0

Defines how user agents expose HTML semantics through platform accessibility APIs.

S9Interoperability evidence

ARIA-AT support tables

Guides test prioritization. W3C explicitly advises product teams to perform their own testing.

S11Test rules

Accessibility Conformance Testing Rules

Automatable assertions for valid roles, attributes, required states, accessible names, and focusable hidden content.

S12Evaluation guidance

WAI testing and evaluation

Combines automated checks with knowledgeable human and assistive-technology evaluation.

Provenance and methodology

Version: 2.0 · July 21, 2026
Research basis: Primary W3C and WHATWG standards, guidance, mapping specifications, and interoperability evidence.
Method: Normative review, maturity separation, pattern synthesis, implementation rebuild, responsive red-team, and interaction validation.
Artifact model: Self-contained HTML with progressive enhancement, print support, machine-readable metadata, and no external runtime dependencies.

Claim-to-source map

Author conformance: S1, S2, and S6.
Interaction contracts: S4 and S5.
Product acceptance: S3.
Browser exposure: S8 and S10.
Interoperability and test prioritization: S9, S11, and S12.
Horizon planning: S7.

Prepared for the document owner with AI-assisted research and implementation. Linked standards remain the source of truth.

Native HTML first. ARIA closes the gap.

Separate production requirements from guidance and horizon signals

What must be correct

How behavior should work

What browsers and AT expose

What may change next

Choose semantics before styling

Identify the user task

Select native HTML

Find the semantic gap

Implement behavior

Synchronize state

Validate with users and tools

The accessible name is part of the component API

Preferred naming sources

Name invariants

Name-source preview

Roles by semantic and interaction cost

Names, states, and relationships

Choose one focus model and document its invariants

Modern HTML removes behavior that custom ARIA widgets once had to recreate

Disclosure

Modal or non-modal window

Top-layer disclosure behavior

Suppress interaction and exposure

Remove inactive content

Semantic-only suppression

Declarative popover specimen

Interaction contracts in practice

Disclosure navigation

Tabs

Native dialog

Status message

Custom switch

Make accessibility part of the component API and ownership model

Disclosure

Landmarks should reveal the information architecture

Recommended shell

Do not create landmark noise

Separate the name, instructions, and error

Validation example

Common ways accessible interfaces regress

<div role="button"> by default

Site navigation marked as menu

Focusable content inside aria-hidden="true"

Static ARIA state

Positive tabindex

Routine notices as alerts

Grid semantics for a read-only table

Automate detection, not judgment

Static checks

Browser checks

Assistive technology

Evidence record

Accessibility contracts must survive scale, localization, and asynchronous interfaces

SPA routing

Loading and streaming

Virtualization

Localization and RTL

Permissions and disabled state

Custom elements

Telemetry

Ownership

Small reset, explicit rhythm, resilient layout

Included in the reset

Explicitly excluded

Component accessibility checklist

Primary source ledger

Claim-to-source map

`<div role="button">` by default

Site navigation marked as `menu`

Focusable content inside `aria-hidden="true"`

Positive `tabindex`