ARIA Expert

ARIA Expert

Expert resource for WAI-ARIA (Accessible Rich Internet Applications) specifications and implementation guidance.

Auto-Initialize

Before reading any ARIA files, check if the repo/​aria-spec/ and repo/​apg-repo/ folders exist in this skill directory. If they don't exist, run the setup script:

cd .cursor/​skills/​aria-expert && ./​setup.sh

This clones the official W3C ARIA repository and the ARIA Authoring Practices Guide. Only needs to run once.

Updating Content

To pull the latest ARIA specifications:

cd .cursor/​skills/​aria-expert/​repo/​aria-spec && git pull
cd .cursor/​skills/​aria-expert/​repo/​apg-repo && git pull

Data Source

This skill uses the official W3C ARIA repository and ARIA Authoring Practices Guide (APG) as git submodules. Content is in HTML format (ReSpec specifications).

ARIA Authoring Practices Guide (APG)

| Path | Content | |------|---------|| | repo/​apg-repo/ | ARIA Authoring Practices Guide | | repo/​apg-repo/​content/​patterns/ | Design patterns for common widgets |

Key content in APG:

• 5 Rules of ARIA Use - Fundamental principles (see section below)
• Design Patterns - Complete examples with code for:
  • Accordion, Alert, Breadcrumb, Button, Carousel, Checkbox, Combobox
  • Dialog (Modal), Disclosure, Feed, Grids, Links, Listbox, Menu, Meter
  • Radio Group, Slider, Spinbutton, Switch, Table, Tabs, Toolbar, Tooltip, Tree View
• Keyboard Interaction Patterns - Required keyboard support for each pattern
• Example Implementations - Working code examples
• Landmark Regions - How to use ARIA landmarks effectively

Core ARIA Specification

Key content in index.html:

• All ARIA roles (button, link, tab, tabpanel, dialog, menu, etc.)
• All ARIA states and properties (aria-label, aria-checked, aria-expanded, etc.)
• Widget roles, composite roles, document structure roles
• Landmark roles (banner, navigation, main, complementary, etc.)
• Live region roles and properties
• Relationship attributes (aria-labelledby, aria-describedby, aria-owns, etc.)

Accessible Name and Description Computation

Key content in accname:

• How browsers compute accessible names
• Name calculation algorithm
• Description calculation algorithm
• Text alternative computation
• Hidden vs. visible content in name calculation

Accessibility API Mappings

Key content in AAM specs:

• How ARIA roles map to platform accessibility APIs (MSAA, UIA, ATK, AX API)
• How HTML elements map to accessibility APIs
• Role, state, and property mappings
• Required accessibility tree computations

Specialized ARIA Modules

Format-Specific Mappings

Documentation

How to Answer ARIA Questions

For ARIA Best Practices, Rules, or Principles

Answer directly without searching files - The 5 Rules of ARIA Use are documented in this file above. No need to search the APG repo for these fundamental principles.

For Design Pattern Questions (e.g., "How to build a tabs widget?", "Dialog keyboard interaction")

1. Read the appropriate pattern file in repo/​apg-repo/​content/​patterns/
2. Common patterns:
   • accordion/ - Accordion pattern
   • alert/ - Alert pattern
   • button/ - Button pattern
   • dialog-modal/ - Modal dialog
   • tabs/ - Tabs pattern
   • menu-button/ - Menu button
   • combobox/ - Combobox/​autocomplete
3. Each pattern includes:
   • Keyboard interaction requirements
   • ARIA roles, states, and properties
   • Working code examples

For Role Questions (e.g., "button role", "dialog role", "tablist")

1. Read repo/​aria-spec/​index.html and search for the role name
2. The spec contains:
   • Role definition and purpose
   • Required/​supported states and properties
   • Inherited states and properties
   • Required context (parent/​child roles)
   • Keyboard interaction expectations
   • Examples of proper usage

For State/​Property Questions (e.g., "aria-label", "aria-expanded", "aria-live")

1. Read repo/​aria-spec/​index.html and search for the attribute name
2. The spec contains:
   • Property definition
   • Valid values (true/​false, token list, string, etc.)
   • Which roles support the property
   • Usage examples
   • Relationship to other properties

For Accessible Name Questions

1. Read repo/​aria-spec/​accname/​index.html
2. Search for relevant sections:
   • Name calculation algorithm (step-by-step process)
   • Text alternative computation
   • Hidden content handling
   • Priority of name sources (aria-labelledby, aria-label, alt, etc.)

For API Mapping Questions

1. For ARIA role/​property mappings: Read repo/​aria-spec/​core-aam/​index.html
2. For HTML element mappings: Read repo/​aria-spec/​html-aam/​index.html
3. Search for the specific role or element name
4. The spec shows platform-specific mappings (Windows, macOS, Linux, etc.)

For Digital Publishing Questions

1. Read repo/​aria-spec/​dpub-aria/​index.html
2. Search for roles like: doc-abstract, doc-acknowledgments, doc-bibliography, doc-chapter, etc.

For Graphics Questions

1. Read repo/​aria-spec/​graphics-aria/​index.html
2. Search for roles like: graphics-document, graphics-symbol, graphics-object

5 Rules of ARIA Use

Critical principles for using ARIA correctly (from WAI-ARIA Authoring Practices):

Rule 1: Use Native HTML Semantics When Possible

If you can use a native HTML element or attribute with the semantics and behavior already built in, instead of re-purposing an element and adding ARIA, then do so.

Good: <button>Click me</​button>
Bad: <div role="button" tabindex="0">Click me</​div>

Rule 2: Don't Change Native Semantics

Do not change native semantics, unless you really have to.

Bad: <h1 role="button">Heading button</​h1>
Why: This creates confusion - it looks like a heading but acts like a button.

Rule 3: All Interactive ARIA Controls Must Be Keyboard Accessible

All interactive ARIA controls must be usable with the keyboard. If you create a widget using role="button", role="tab", etc., it must be keyboard accessible.

Required:

• Tab/​Shift+Tab to navigate to controls
• Enter/​Space to activate buttons and links
• Arrow keys for composite widgets (tabs, menus, etc.)
• Escape to close dialogs and menus

Rule 4: Don't Hide Focusable Elements

Do not use role="presentation" or aria-hidden="true" on a focusable element.

Bad: <button aria-hidden="true">Click me</​button>
Why: Screen readers will skip it, but keyboard users can still focus it, creating confusion.

Rule 5: All Interactive Elements Must Have an Accessible Name

All interactive elements must have an accessible name.

Methods to provide accessible names:

• Visible text content: <button>Submit</​button>
• aria-label: <button aria-label="Close dialog">×</​button>
• aria-labelledby: <button aria-labelledby="label-id">×</​button>
• alt text for images: <img src="logo.png" alt="Company name">

Bonus Principle: "No ARIA is Better Than Bad ARIA"

Incorrect ARIA can make accessibility worse for screen reader users than having no ARIA at all. When in doubt, test with real assistive technologies.

---

Quick Reference

Common Widget Roles

Landmark Roles

Common ARIA Properties

Document Structure Roles

Live Region Properties

Digital Publishing Roles (dpub-aria)

Graphics Roles (graphics-aria)

Attribution

This skill uses material from the W3C ARIA Repository. Copyright © W3C® (MIT, ERCIM, Keio, Beihang). See W3C Document License.