Guide · Agent skill
How to use the aria-text agent skill: avoid focusable elements in role=text
Updated · written with AI from the project's own documentation and checked against our catalogue data
The aria-text skill is a set of instructions that teaches an AI agent one accessibility rule: a container marked role="text" makes screen readers treat everything inside it as plain text, so buttons and links nested there can disappear for people using assistive technology. This guide explains what the skill does, how to install it, how to ask for a review, and where its limits are. You do not need prior experience with agent skills to follow it.
Avoid Focusable Inside role=textthedaviddias/Front-End-Checklist · MIT Download the skill Quick start
- 1Download the ZIP. Get the aria-text ZIP from the skill's page on the directory.
- 2Unzip into the skills folder. Extract it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 3Or upload in the Claude apps. Open Settings, go to Capabilities, and upload the skill under Skills.
- 4Send markup for review. Paste HTML or a component and ask the agent to check for role=text containers with interactive children.
- 5Apply the fix. Remove role="text" or move the links and buttons outside the container, as the agent suggests.
- 6Verify manually. Test with the keyboard and a screen reader, since the skill does not run an audit tool.
What the aria-text skill makes the agent do
When you ask the agent to review HTML or component markup, the skill tells it to look for elements with role="text" that contain focusable children such as links, buttons or inputs. When it finds one, it explains why this breaks access, because the container flattens its contents into a single string of text.
The suggested fix is either to remove role="text" from the container or to move the interactive elements outside it. The skill also asks the agent to check native semantics first and, where relevant, to look at keyboard behaviour, focus flow, accessible names and screen-reader output.
- Flags role="text" containers that hold links, buttons or inputs
- Explains how the role overrides the semantics of descendant elements
- Suggests removing the role or moving the interactive elements out
Install the aria-text skill
Download the aria-text ZIP from the skill's page in the directory. Unzip it into one of the following locations, depending on how you want to use it.
For your own user account, unzip it into ~/.claude/skills/. To share it with one project, unzip it into the .claude/skills/ folder inside that project. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal use: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Files included in the skill
The skill contains two files. SKILL.md holds the main instructions, including the check, fix and explain steps and a quick reference. references/rule.md holds fuller guidance with a code example showing a correct simple text container and two incorrect ones: a div with role="text" wrapping a link, and one wrapping a submit button.
The skill does not run scripts and does not use the network, so it works entirely from its text.
- SKILL.md: main instructions and quick reference
- references/rule.md: detailed rule page with HTML examples
Trigger the skill with natural requests
You do not need a special command. Describe what you want reviewed in plain language, and mention rendered HTML, a component or a design-system pattern. The skill matches requests about role="text" and focusable content inside it.
Paste the markup into the chat or point the agent at the file. Asking for a review of the rendered output works better than asking only about the source, because the skill's guidance refers to rendered markup and focus behaviour.
- "Review this component for role=text problems with buttons or links inside."
- "Check this design-system card: are any interactive elements hidden from screen readers?"
- "Does this rendered HTML put links inside a role=text container?"
Read the results and verify them
Expect the agent to name the exact element, explain the problem and propose a change. Treat its answer as a starting point. The skill gives guidance from its text only and does not run an audit tool, so you should confirm each finding by hand.
Use browser accessibility tooling and test with a real screen reader and keyboard. Check that the interactive element can be reached with Tab and activated, and that its accessible name is announced.
- Tab through the component and confirm every control receives focus
- Activate each control with the keyboard
- Listen to the output of a screen reader for the component
What people use it for
- Reviewing a product card where a link or button sits inside a role="text" wrapper
- Auditing a shared design-system component before it ships to several teams
- Teaching students how ARIA roles change what assistive technology exposes
Frequently asked questions
How do I install the aria-text skill?
Download the ZIP from the skill's page, then unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
Does aria-text need any requirements or extra software?
The skill lists no requirements. It does not run scripts and does not use the network, so it works from its text alone. You still need a way to test your own pages, such as a keyboard and a screen reader.
Is the aria-text skill free to use?
The skill is released under the MIT licence. The source does not list pricing for it, so check the directory page for any terms that apply to your use.
Why is a button inside role="text" a problem?
The role makes screen readers treat the whole container as one string of text, so the button or link inside can be hidden from people using assistive technology. They may be unable to focus or activate it.
Can the skill replace a screen reader test?
No. The skill only gives guidance from its text and does not run an audit tool. Verify findings with browser accessibility tools and a real screen reader.
What should I do if the agent finds a problem?
Either remove role="text" from the container or move the interactive elements outside it. Then retest with the keyboard and a screen reader to confirm the fix.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use aria-text if you review component markup or design-system code and want a focused check for links and buttons hidden inside role="text" containers. Skip it if your project has no interactive content or no HTML to review, or if you need a full audit tool, since the skill only covers this one rule and must be verified manually.
Download the skill