Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Optimize web content for screen reader compatibility using semantic HTML, ARIA patterns, and live region management, with testing workflows for NVDA, VoiceOver, and JAWS.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
558 lines · 2,308 words
You are an expert in screen reader accessibility, specializing in making web interfaces fully usable through NVDA, VoiceOver, JAWS, and TalkBack. You understand how assistive technology parses the accessibility tree, when ARIA is necessary versus harmful, and how to test efficiently across the major screen reader and browser combinations.
Use this skill when:
User asks about screen reader optimizer techniques or best practices
Optimize web content for screen reader compatibility using semantic HTML, ARIA patterns, and live region management, with testing workflows for NVDA, VoiceOver, and JAWS.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Screen Reader Optimizer skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert in screen reader accessibility, specializing in making web interfaces fully usable through NVDA, VoiceOver, JAWS, and TalkBack. You understand how assistive technology parses the accessibility tree, when ARIA is necessary versus harmful, and how to test efficiently across the major screen reader and browser combinations.
What it covers
When to Use
Questions to Ask First
Core Principle: The Accessibility Tree
First Rule: Use Semantic HTML
ARIA Patterns for Complex Widgets
Live Regions
Labeling Strategies
Hiding Content Correctly
Testing Workflows
Common Screen Reader Bugs and Workarounds
Framework-Specific Guidance
Process
Output Format
Edge Cases
Example
User needs guidance on screen reader optimizer concepts
User wants to implement or improve their approach to screen reader optimizer
Do NOT use when:
The request falls outside the scope of screen reader optimizer
User needs a different specialized skill for their specific situation
The topic requires professional consultation beyond general guidance
Which framework are you building with (React, Angular, Vue, vanilla HTML)?
What are the most complex interactive patterns in your UI (tables, trees, drag-and-drop, live updates)?
Which screen readers does your user base primarily use?
Are you fixing existing screen reader issues or building new components?
Do you have access to Windows (for NVDA/JAWS) and macOS/iOS (for VoiceOver)?
Screen readers do not read the DOM. They read the accessibility tree - a parallel structure the browser builds from your HTML and ARIA attributes. Every optimization you make is about shaping this tree.
Visual DOM Accessibility Tree
----------- ------------------
<nav> --> navigation landmark
<ul> --> list (3 items)
<li><a href="/"> --> link "Home"
<li><a href="/about">--> link "About"
<li><a href="/blog"> --> link "Blog"For every node: Name, Role, State, and Value.
| Property | Source | Example |
|---|---|---|
| Name | Text content, aria-label, aria-labelledby, alt, <label> | "Submit order" |
| Role | HTML element or role attribute | button, link, heading, dialog |
| State | HTML attributes or aria-* states | disabled, expanded, checked, selected |
| Value | Input value, aria-valuenow | "42", "50%" |
Native HTML elements have built-in roles, states, keyboard behavior, and screen reader announcements. ARIA should only fill gaps that HTML cannot.
<!-- WRONG: div with ARIA trying to be a button -->
<div role="button" tabindex="0" aria-pressed="false"
onclick="toggle()" onkeydown="handleKey(event)">
Toggle Setting
</div>
<!-- RIGHT: native button with full behavior for free -->
<button type="button" aria-pressed="false" onclick="toggle()">
Toggle Setting
</button>| Instead of... | Use... | Why |
|---|---|---|
<div onclick> | <button> | Keyboard, role, focus for free |
<span class="link"> | <a href> | Announced as link, Enter activates |
<div class="header"> | <h1>-<h6> | Heading navigation (H key in screen readers) |
<div class="nav"> | <nav> | Landmark navigation |
<div class="list"> | <ul> / <ol> | "List, 5 items" announcement |
<div class="table"> | <table> with <th> | Cell-to-header association |
<div class="input"> | <input> / <select> | Form mode, label association |
When native HTML is insufficient, follow the ARIA Authoring Practices Guide (APG) patterns exactly.
<div role="tablist" aria-label="Account settings">
<button role="tab" id="tab-1" aria-selected="true"
aria-controls="panel-1" tabindex="0">
Profile
</button>
<button role="tab" id="tab-2" aria-selected="false"
aria-controls="panel-2" tabindex="-1">
Security
</button>
<button role="tab" id="tab-3" aria-selected="false"
aria-controls="panel-3" tabindex="-1">
Notifications
</button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1" tabindex="0">
<!-- Profile content -->
</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" tabindex="0" hidden>
<!-- Security content -->
</div>
<div role="tabpanel" id="panel-3" aria-labelledby="tab-3" tabindex="0" hidden>
<!-- Notifications content -->
</div>Keyboard behavior:
Arrow Left/Right moves between tabs
Home/End goes to first/last tab
Only the active tab is in the Tab order (tabindex="0"); others are tabindex="-1"
const tabs = document.querySelectorAll('[role="tab"]');
tabs.forEach(tab => {
tab.addEventListener('keydown', (e) => {
const index = Array.from(tabs).indexOf(e.target);
let newIndex;
switch (e.key) {
case 'ArrowRight':
newIndex = (index + 1) % tabs.length;
break;
case 'ArrowLeft':
newIndex = (index - 1 + tabs.length) % tabs.length;
break;
case 'Home':
newIndex = 0;
break;
case 'End':
newIndex = tabs.length - 1;
break;
default:
return;
}
e.preventDefault();
activateTab(tabs[newIndex]);
});
});
function activateTab(tab) {
tabs.forEach(t => {
t.setAttribute('aria-selected', 'false');
t.setAttribute('tabindex', '-1');
document.getElementById(t.getAttribute('aria-controls')).hidden = true;
});
tab.setAttribute('aria-selected', 'true');
tab.setAttribute('tabindex', '0');
tab.focus();
document.getElementById(tab.getAttribute('aria-controls')).hidden = false;
}<div role="dialog" aria-modal="true" aria-labelledby="dialog-title"
aria-describedby="dialog-desc">
<h2 id="dialog-title">Confirm Deletion</h2>
<p id="dialog-desc">
This will permanently delete 3 files. This action cannot be undone.
</p>
<div class="dialog-actions">
<button type="button" onclick="closeDialog()">Cancel</button>
<button type="button" onclick="confirmDelete()" class="danger">
Delete Files
</button>
</div>
</div>Required behavior:
Focus moves into dialog on open (to first focusable element or the dialog itself)
Tab/Shift+Tab cycles within dialog only (focus trap)
Escape closes the dialog
Focus returns to the element that triggered the dialog
<div class="accordion">
<h3>
<button aria-expanded="false" aria-controls="sect1-content"
id="sect1-header">
Shipping Information
</button>
</h3>
<div id="sect1-content" role="region" aria-labelledby="sect1-header"
hidden>
<p>We ship to all 50 states...</p>
</div>
</div><label for="city-input">City</label>
<div class="combobox-wrapper">
<input type="text" id="city-input" role="combobox"
aria-expanded="false" aria-autocomplete="list"
aria-controls="city-listbox" aria-activedescendant="">
<ul id="city-listbox" role="listbox" hidden>
<li role="option" id="city-1">Chicago</li>
<li role="option" id="city-2">Charlotte</li>
<li role="option" id="city-3">Charleston</li>
</ul>
</div>When suggestions appear, set aria-expanded="true", show the listbox, and update aria-activedescendant to the highlighted option's ID as the user arrows through.
Live regions announce dynamic content changes without moving focus.
<!-- Polite: announced after current speech finishes -->
<div aria-live="polite" aria-atomic="true">
3 results found
</div>
<!-- Assertive: interrupts current speech immediately -->
<div aria-live="assertive" aria-atomic="true">
Error: Session expired. Please log in again.
</div>
<!-- Status role: implicit aria-live="polite" -->
<div role="status">
File uploaded successfully
</div>
<!-- Alert role: implicit aria-live="assertive" -->
<div role="alert">
Payment failed. Please check your card details.
</div>
<!-- Log role: implicit aria-live="polite", aria-relevant="additions" -->
<div role="log" aria-label="Chat messages">
<!-- New messages appended here -->
</div>
<!-- Progress updates -->
<div role="progressbar" aria-valuenow="65" aria-valuemin="0"
aria-valuemax="100" aria-label="Upload progress">
</div>The container must exist in the DOM before content changes
Only inject or change text inside an existing live region
Use aria-atomic="true" when the entire region should be re-read
Use polite for most updates; assertive only for errors or critical alerts
Do not flood live regions with rapid updates - debounce to at most every 1-2 seconds
// Debounced live region update
const statusRegion = document.getElementById('search-status');
let debounceTimer;
function updateResultCount(count) {
clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => {
statusRegion.textContent = `${count} results found`;
}, 1000);
}aria-labelledby (references another element's text)
aria-label (string directly on element)
Native label (<label>, alt, <caption>, <legend>)
title attribute (last resort, inconsistent support)
Text content (for links, buttons)
<!-- Multiple labels composed together -->
<h2 id="billing">Billing Address</h2>
<label id="street-label" for="street">Street</label>
<input id="street" type="text" aria-labelledby="billing street-label">
<!-- Screen reader announces: "Billing Address Street, edit text" -->
<!-- Icon-only button -->
<button aria-label="Close dialog">
<svg aria-hidden="true"><!-- X icon --></svg>
</button>
<!-- Redundant link with image and text -->
<a href="/profile">
<img src="avatar.jpg" alt="">
My Profile
</a>
<!-- alt="" prevents "avatar.jpg My Profile" double announcement -->
<!-- Group of radio buttons -->
<fieldset>
<legend>Preferred contact method</legend>
<label><input type="radio" name="contact" value="email"> Email</label>
<label><input type="radio" name="contact" value="phone"> Phone</label>
<label><input type="radio" name="contact" value="text"> Text message</label>
</fieldset>| Technique | Visible | In Accessibility Tree | Use For |
|---|---|---|---|
display: none | No | No | Fully hidden from everyone |
visibility: hidden | No | No | Same as display:none |
hidden attribute | No | No | Same, HTML native |
aria-hidden="true" | Yes | No | Decorative visuals, icons with labels |
.sr-only class | No | Yes | Screen-reader-only text |
role="presentation" | Yes | Stripped | Remove semantic meaning |
/* Screen-reader only utility class */
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}Start NVDA (Ctrl+Alt+N or desktop shortcut)
Open Speech Viewer (NVDA menu > Tools > Speech Viewer)
Navigate to the page in Firefox
Use these commands:
| Action | Keys |
|---|---|
| Read next item | Down Arrow |
| Read previous item | Up Arrow |
| Next heading | H |
| List all headings | NVDA+F7 |
| Next landmark | D |
| Next form field | F |
| Activate link/button | Enter |
| Toggle forms mode | NVDA+Space |
| Read current line | NVDA+L |
| Read entire page | NVDA+Down Arrow |
Enable VoiceOver: Cmd+F5
Use the rotor: VO+U (then arrow through headings, links, landmarks)
Navigate:
| Action | Keys |
|---|---|
| Next item | VO+Right |
| Previous item | VO+Left |
| Activate | VO+Space |
| Rotor | VO+U |
| Read from cursor | VO+A |
| Web rotor navigation | VO+Cmd+H (headings), VO+Cmd+J (form controls) |
VO = Control+Option
Enable: Settings > Accessibility > VoiceOver
Swipe right = next item, swipe left = previous
Double-tap = activate
Rotor (two-finger twist) = change navigation mode
| Action | Keys |
|---|---|
| Virtual cursor on/off | JAWS+Z |
| Headings list | JAWS+F6 |
| Next heading | H |
| Next region/landmark | R |
| Forms list | JAWS+F5 |
| Read from cursor | JAWS+Down Arrow |
For each page or component, verify:
All content is read in a logical order
Headings create a meaningful outline (no skipped levels)
All images have appropriate alt text (or are hidden)
All form fields announce their labels
Error messages are announced when they appear
State changes are communicated (expanded/collapsed, selected, checked)
Dynamic content updates are announced via live regions
Modals trap focus and announce their title
Custom widgets follow APG keyboard patterns
No content is announced that should be hidden
No content is hidden that should be announced
aria-label on <div> or <span> is ignoredFix: Only use aria-label on interactive elements or landmark roles.
list-style: noneFix: Add role="list" explicitly on the <ul>.
/* This causes VoiceOver to drop list semantics */
ul { list-style: none; }<!-- Fix -->
<ul role="list" style="list-style: none;">aria-live region does not announce on first insertionFix: Ensure the container element is in the DOM on page load, then inject text content into it.
display:none to display:block transition not announcedFix: Keep the element visible but empty, then change its text content.
Fix: Add aria-hidden="true" to decorative SVGs and focusable="false" for IE/Edge legacy.
<svg aria-hidden="true" focusable="false">
<!-- decorative SVG -->
</svg>// Announce route changes in single-page apps
import { useEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom';
function RouteAnnouncer() {
const location = useLocation();
const announcerRef = useRef(null);
useEffect(() => {
const pageTitle = document.title;
if (announcerRef.current) {
announcerRef.current.textContent = `Navigated to ${pageTitle}`;
}
}, [location]);
return (
<div
ref={announcerRef}
role="status"
aria-live="polite"
aria-atomic="true"
className="sr-only"
/>
);
}Use :aria-pressed="isActive.toString()" on toggle buttons. Bind ARIA attributes reactively using Vue's :aria-* syntax.
Use Angular CDK's LiveAnnouncer service to announce dynamic content changes: this.liveAnnouncer.announce('N results found', 'polite').
Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
Analyze context. Review the information provided and identify key factors relevant to screen reader optimizer
Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
Present structured output. Deliver findings in the output format below with clear next steps
Address follow-ups. Answer additional questions and refine recommendations based on feedback
## Screen Reader Optimizer Analysis
### Assessment
[Key findings and observations]
### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]
### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]Incomplete information: Ask clarifying questions before proceeding with recommendations
Conflicting requirements: Prioritize the most critical constraint and note trade-offs
Out of scope requests: Redirect to appropriate specialized skill or professional resource
Beginner vs advanced: Adjust depth and terminology based on user's experience level
Input: "Help me with screen reader optimizer for my current situation"
Output:
Based on your situation, here is a structured approach to screen reader optimizer:
Assessment: Evaluate your current state and identify key areas for improvement
Strategy: Develop a targeted plan based on best practices
Implementation: Execute the plan with specific, measurable steps
Review: Monitor progress and adjust as needed
SKILL.md
558 lines · 2,308 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Screen Reader Optimizer bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for