WAI-ARIA Authoring Practices

Standardized blueprints for building accessible custom UI components. Each pattern specifies the expected keyboard interaction model, ARIA roles, states, and properties required for a widget to be understood by assistive technologies.

• Accordion Pattern: Manages expandable sections with proper aria-expanded state toggling
• Combobox Pattern: Defines the complex relationship between a text input and a popup listbox using aria-controls and aria-activedescendant
• Dialog (Modal) Pattern: Establishes focus trapping, aria-modal designation, and aria-labelledby association for overlay windows
• Disclosure Pattern: Provides a lightweight show/hide mechanism distinct from accordion for single-panel visibility toggling

Prescriptive guidance on how custom widgets must respond to keystrokes to mirror native operating system conventions. These models ensure that AI agents simulating user interaction can programmatically navigate complex interfaces.

• Tab/Shift+Tab: Moves focus between interactive elements within the defined tab order
• Arrow Keys: Navigate within composite widgets like listboxes, grids, and tab lists
• Enter/Space: Activates the currently focused control or selects an item
• Escape: Dismisses overlays, closes dialogs, or cancels operations
• Home/End: Moves focus to the first or last item in a container

A taxonomy of roles that programmatically identify the high-level structure of a page. Landmarks create a navigable outline for screen readers and provide AI parsers with a semantic map of content zones.

• banner: The site-wide header, typically containing the logo and primary navigation
• main: The dominant content unique to the current page; only one per document
• complementary: Content that supports the main content but remains independently meaningful
• contentinfo: The site-wide footer with copyright, legal links, and metadata
• navigation: Groups of major navigational links

The algorithm for computing an element's accessible name and accessible description from multiple potential sources. This is the primary mechanism by which AI agents identify and label UI controls.

• aria-labelledby: References other element IDs to compose a name from visible text
• aria-label: Provides a direct string name when no visible label exists
• aria-describedby: Links supplementary descriptive text to a control
• Precedence: aria-labelledby overrides aria-label, which overrides native labeling like <label> elements
• Text Alternative Computation: The browser's formal algorithm that concatenates referenced text nodes into a flat string

Specialized patterns for interactive tabular data structures that go beyond static HTML tables. These patterns enable keyboard navigation across rows and columns while maintaining proper rowheader and columnheader associations.

• Grid Pattern: A composite widget containing a tab container where arrow keys navigate cells, and Enter or F2 activates edit mode within a cell
• Table Pattern: A static data structure with role="table" that preserves header-to-cell relationships via aria-describedby or scope attributes
• Treegrid Pattern: A hierarchical grid combining tree view expand/collapse behavior with tabular column navigation

Techniques for communicating dynamic content changes to assistive technologies without disrupting the user's current focus. This is critical for single-page applications where content updates asynchronously.

• aria-live: Defines a region that announces changes automatically; values include polite (waits for silence) and assertive (interrupts immediately)
• aria-atomic: Controls whether the entire live region or only changed nodes are announced
• aria-relevant: Specifies which types of changes trigger announcements: additions, removals, text, or all
• role="status": An implicit aria-live="polite" region for advisory messages
• role="alert": An implicit aria-live="assertive" region for time-sensitive notifications

A set of predefined roles—including banner, navigation, main, and complementary—added to HTML elements to programmatically identify distinct page regions. Landmarks allow AI agents and assistive technologies to efficiently navigate document structure without parsing visual layout. Each landmark creates a high-level content taxonomy that generative engines use to weight the importance of page sections during extraction.

A Web Components API allowing developers to define new, semantically meaningful HTML tags with encapsulated behavior. When building custom widgets, developers must augment Custom Elements with ARIA roles, states, and properties to remain interpretable by AI agents. The Shadow DOM encapsulation boundary requires explicit declarative techniques—such as aria-labelledby cross-boundary references—to expose internal semantics to the accessibility tree.