How to use the Deprecated ARIA Roles Checker agent skill

What the skill makes the agent do

ARIA roles are labels that tell screen readers what an element is. Some roles have been deprecated as the WAI-ARIA specification evolves, and the skill's source notes that using them can lead to inconsistent behaviour across browsers and screen readers.

When the skill is active, the agent searches your code for deprecated roles and abstract roles that should not appear in HTML. It explains the risks, proposes modern roles or plain native HTML elements as replacements, and checks related keyboard behaviour, focus order and accessible names where relevant.

• Finds deprecated roles such as 'directory' in your markup
• Explains why they can cause inconsistent behaviour
• Suggests modern roles or native HTML elements instead
• Flags related keyboard, focus and accessible-name issues where relevant

Install the skill by downloading the ZIP

Download the aria-deprecated-role ZIP from the skill's page in this directory, then unzip it. The folder contains SKILL.md and references/rule.md.

For a personal install, unzip the skill into ~/.claude/skills/. To limit it to one project, unzip it into the project's .claude/skills/ folder instead.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Single project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need a special command. The skill's description says it applies when reviewing rendered HTML, interactive components or design-system patterns. Ask for a review of the markup in plain words and name the file or component where you can.

Ask for a check, a fix or an explanation. The skill's own sections cover these three tasks: searching for deprecated roles, updating them to modern equivalents or native elements, and explaining the risks.

• "Check the markup in components/Tabs.html for deprecated ARIA roles."
• "Find any role=\"directory\" or other deprecated roles in src/ and suggest replacements."
• "Review this modal for deprecated roles and tell me whether native elements would do the job."
• "Explain why the directory role is a problem and how to fix it."

What a good review should contain

The skill's code review guidance asks the agent to flag exact elements, roles, labels, focus behaviour and keyboard interactions that break the rule. It should also say how to verify the fix with browser accessibility tooling or assistive technology.

The source example shows a modern pattern: a nav with an aria-label of 'Site' and a ul with role="list" are accepted, while a div with role="directory" is the incorrect case. Use the review as a starting list, then confirm the result in your own browser and tools.

• Exact element and location
• The deprecated or abstract role and the suggested replacement
• Related keyboard, focus or accessible-name problems
• How to verify the fix

Safety notes and limits

The skill declares no requirements, runs no scripts and does not use the network. It works from a single checklist rule and does not test real screen-reader output.

The skill's content is brief. Check any role recommendation against the latest WAI-ARIA specification before a release, especially if your project depends on the exact list of current roles.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no
• Does not replace a full accessibility audit or real screen-reader testing

Tips for better results

Give the agent the markup or the component files, not just a topic. Results are more specific when it can see exact elements. Ask it to prefer native HTML before ARIA, which matches the skill's first check.

Treat the output as a list to verify. Re-test keyboard flow and accessible names in a browser after each change.

• Paste or point to the real files
• Ask for native element alternatives first
• Re-test keyboard and focus after changes