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

Path	Content
repo/aria-spec/index.html	Main ARIA 1.3 specification - roles, states, properties

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

Path	Content
repo/aria-spec/accname/index.html	Accessible Name and Description Computation specification

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

Path	Content
repo/aria-spec/core-aam/index.html	Core Accessibility API Mappings - how ARIA maps to platform APIs
repo/aria-spec/html-aam/index.html	HTML Accessibility API Mappings - HTML element 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

Path	Content
repo/aria-spec/dpub-aria/index.html	Digital Publishing ARIA - roles for digital publications
repo/aria-spec/dpub-aam/index.html	Digital Publishing AAM - mappings for dpub roles
repo/aria-spec/graphics-aria/index.html	Graphics ARIA - roles for graphics and diagrams
repo/aria-spec/graphics-aam/index.html	Graphics AAM - mappings for graphics roles

Format-Specific Mappings

Path	Content
repo/aria-spec/svg-aam/index.html	SVG Accessibility API Mappings
repo/aria-spec/mathml-aam/index.html	MathML Accessibility API Mappings
repo/aria-spec/pdf-aam/index.html	PDF Accessibility API Mappings

Documentation

Path	Content
repo/aria-spec/README.md	Repository overview and contribution guidelines
repo/aria-spec/CONTRIBUTING.md	How to contribute to ARIA specifications

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

Role	Purpose	Key Properties
button	Clickable button	aria-pressed, aria-expanded
link	Hyperlink	aria-expanded
checkbox	Checkable input	aria-checked (required)
radio	Radio button	aria-checked (required)
textbox	Text input	aria-multiline, aria-readonly, aria-required
combobox	Combo box widget	aria-expanded (required), aria-controls
listbox	List of selectable items	aria-multiselectable
option	Selectable option	aria-selected
tab	Tab in a tablist	aria-selected (required)
tabpanel	Container for tab content	aria-labelledby (required)
menu	Menu widget	-
menuitem	Menu item	-
menuitemcheckbox	Checkable menu item	aria-checked (required)
menuitemradio	Radio menu item	aria-checked (required)
dialog	Dialog/modal window	aria-modal, aria-labelledby
alertdialog	Alert dialog	aria-modal, aria-labelledby
slider	Slider control	aria-valuenow (required), aria-valuemin, aria-valuemax
progressbar	Progress indicator	aria-valuenow, aria-valuemin, aria-valuemax

Landmark Roles

Role	Purpose	HTML5 Equivalent
banner	Site header	<header> (when not in article/section)
navigation	Navigation links	<nav>
main	Main content	<main>
complementary	Complementary content	<aside>
contentinfo	Footer information	<footer> (when not in article/section)
search	Search functionality	No equivalent
region	Significant page section	<section> with accessible name
form	Form landmark	<form> with accessible name

Common ARIA Properties

Property	Type	Purpose
aria-label	String	Provides accessible name
aria-labelledby	ID reference(s)	Names element via other element(s)
aria-describedby	ID reference(s)	Provides accessible description
aria-expanded	true/false/undefined	Indicates expanded state
aria-hidden	true/false	Hides content from accessibility tree
aria-live	off/polite/assertive	Indicates live region updates
aria-atomic	true/false	Announces entire region on change
aria-relevant	additions/removals/text/all	What changes to announce
aria-controls	ID reference(s)	Element controlled by this element
aria-owns	ID reference(s)	Parent-child relationship
aria-current	page/step/location/date/time/true/false	Current item in set
aria-disabled	true/false	Indicates disabled state
aria-invalid	true/false/grammar/spelling	Indicates validation state
aria-required	true/false	Indicates required field

Document Structure Roles

Role	Purpose
article	Self-contained composition
document	Document content
feed	Scrollable list of articles
heading	Section heading
img	Image (for grouping elements into single image)
list	List of items
listitem	Item in a list
table	Table structure
row	Table row
cell	Table cell
rowheader	Row header cell
columnheader	Column header cell

Live Region Properties

Property	Values	Purpose
aria-live	off, polite, assertive	Announce updates
aria-atomic	true, false	Announce whole region
aria-relevant	additions, removals, text, all	What to announce
aria-busy	true, false	Region is updating

Digital Publishing Roles (dpub-aria)

Role	Purpose
doc-abstract	Abstract/summary
doc-acknowledgments	Acknowledgments
doc-afterword	Afterword
doc-appendix	Appendix
doc-backlink	Back link
doc-biblioentry	Bibliography entry
doc-bibliography	Bibliography
doc-biblioref	Bibliography reference
doc-chapter	Chapter
doc-colophon	Colophon
doc-conclusion	Conclusion
doc-cover	Cover image
doc-credit	Credit statement
doc-credits	Credits
doc-dedication	Dedication
doc-endnote	Endnote
doc-endnotes	Endnotes collection
doc-epigraph	Epigraph
doc-epilogue	Epilogue
doc-errata	Errata
doc-example	Example
doc-footnote	Footnote
doc-foreword	Foreword
doc-glossary	Glossary
doc-glossref	Glossary reference
doc-index	Index
doc-introduction	Introduction
doc-noteref	Note reference
doc-notice	Notice
doc-pagebreak	Page break
doc-pagelist	Page list
doc-part	Part
doc-preface	Preface
doc-prologue	Prologue
doc-pullquote	Pull quote
doc-qna	Q&A section
doc-subtitle	Subtitle
doc-tip	Tip
doc-toc	Table of contents

Graphics Roles (graphics-aria)

Role	Purpose
graphics-document	Graphics document container
graphics-object	Graphics object
graphics-symbol	Graphics symbol

Attribution

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