accessible-name
Skill0 starsChanged 29 days agoMITView on GitHub
Use when adding or reviewing alt text, icon buttons, links, or form control labels, when a control is announced as "button" or "link", or when a visible label and an aria-label disagree.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- accessible-authenticationSkill
- accessible-formsSkill
- accordion-disclosureSkill
- audit-componentSkill
- carouselSkill
- charts-and-datavizSkill
- combobox-autocompleteSkill
- data-tableSkill
- email-html-accessibilitySkill
- fix-color-contrastSkill
- forced-colors-and-dark-modeSkill
- headings-and-landmarksSkill
- keyboard-focusSkill
- live-regionsSkill
- media-captionsSkill
- menu-buttonSkill
- modal-dialogSkill
- motion-and-animationSkill
- page-title-and-languageSkill
- pagination-and-searchSkill
- pointer-and-gesturesSkill
- predictable-contextSkill
- progress-and-loadingSkill
- screen-reader-test-planSkill
- semantic-htmlSkill
- skip-linksSkill
- svg-and-iconsSkill
- tabsSkill
- tooltip-popoverSkill
- triage-automated-resultsSkill
- wcag22-new-criteriaSkill
- zoom-reflow-text-spacingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 85
Not what attributes are present — what the *result* is.
- Very specific: line 89
Delete redundant attributes.
- Very specific: line 145
titleas the only label: Not reachable by keyboard on most elements, not shown on touch, and truncated in tooltips.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Accessible names and alt text
Criteria: SC 1.1.1 Non-text Content, SC 1.3.1 Info and Relationships, SC 1.3.6 Identify Purpose, SC 2.4.4 Link Purpose (In Context), SC 2.5.3 Label in Name, SC 4.1.2 Name, Role, Value, SC 3.3.2 Labels or Instructions
Where a name is missing, a screen reader announces the role and nothing else — "button", "edit text", "image". Give every control, link and image a name that is announced usefully and that matches what is visible on screen; that is the whole skill.
When to use
- An icon-only button announces as "button".
- A screen reader reads "link link link" or "Read more" ten times.
- Writing
alttext, or reviewing someone else's. - Choosing between
aria-label,aria-labelledby,<label>, andtitle.
The name computation, in order
The first of these that produces text wins. Anything later is only a fallback — never a reason to add an earlier one "as well".
aria-labelledby— points at the element(s) whose text is the name. Use it when the label already exists elsewhere on the page.aria-label— literal text. Use it only when there is nothing visible to reference.- The native source:
<label>for form controls,altfor<img>, text content for<button>and<a>,<legend>for<fieldset>,<caption>for<table>. title— last resort. It is not reliably exposed, is not keyboard-reachable on all elements, and vanishes on touch.placeholder— not a label. It disappears as soon as the user types, so it fails SC 3.3.2 for a field that needs one.
<!-- Best: a real, visible label, referenced implicitly -->
<label for="email">Email</label>
<input id="email" type="email" autocomplete="email">
<!-- Fine when the visible text lives elsewhere and must not be duplicated -->
<h2 id="billing">Billing address</h2>
<fieldset aria-labelledby="billing"> … </fieldset>
<!-- Last resort, and it must match the visible label — see SC 2.5.3 below -->
<button type="button" aria-label="Close"><svg …></svg></button>Label in Name
The accessible name must contain the visible label text, word for word (SC 2.5.3). Someone using voice control says what they see; if they say "click Search" and the accessible name is "Submit", nothing happens.
<!-- Fails SC 2.5.3: the visible word "Search" is not in the name -->
<button aria-label="Submit query">Search</button>
<!-- Passes: the name starts with the visible text -->
<button aria-label="Search products">Search</button>Alt text, as a decision
| The image… | alt should be | Example |
| is decoration (a divider, a background flourish) | alt="" — empty, present, no space | <img src="swoosh.svg" alt=""> |
| is a functional icon inside a link or button | the function, not the shape | <img src="print.svg" alt="Print this page"> |
| conveys information | the content, as a phrase | <img src="chart.png" alt="Revenue rose 18% in Q3"> |
| is complex (a chart, a diagram) | a short alt, plus the detail in nearby text | see the failure modes |
| is an image of text | replace it with real text | — |
| is inside a link whose text already describes it | alt="", so the name is not doubled | <a href="/x"><img alt=""><span>Read the report</span></a> |
The test that decides most cases: would a sighted user lose information if the image were not there? If yes, describe it. If no, empty.
Procedure
- List every
<img>,<svg>,<button>,<a>and form control in the component. - For each, ask what the name currently computes to, using the order above. Not what attributes are present — what the result is.
- Fix, in this preference order: native visible text → real label →
aria-labelledby→aria-label. Prefer the option that keeps one source of truth. - Delete redundant attributes. If a
<button>already contains the word "Save", anaria-label="Save"adds a second thing to keep in sync for no benefit. Identify the purpose of components, icons and regions, not only their content (SC 1.3.6, AAA). A name says what a thing is; purpose says what it is for, and SC 1.3.6 expects the purpose of user-interface components, icons and regions to be programmatically determinable. In practice:
aria-label="Search"rather than a magnifier glyph with no name;<main>rather than an unlabelled<div>; and the same names used consistently across the product (see thepredictable-contextskill). The common failure is an icon that is decorative by accident — the designer knows it means "download", the markup says nothing, and the meaning lives only in the visual.<!-- Fails SC 1.3.6 — purpose is in the glyph only --> <span class="icon icon-download"></span> <!-- Passes — the purpose is in the markup, and the glyph is hidden from AT --> <button type="button" aria-label="Download invoice"> <span class="icon icon-download" aria-hidden="true"></span> </button>
Verify
// In a browser: read the computed name, do not inspect the attributes.
const name = (el) =>
el.getAttribute('aria-label') ||
(el.getAttribute('aria-labelledby')
? el.getAttribute('aria-labelledby').split(/\s+/)
.map((id) => document.getElementById(id)?.textContent?.trim()).join(' ')
: null) ||
el.textContent.trim() ||
el.getAttribute('title') ||
'';
// Every interactive element must yield a non-empty, non-generic string.Then confirm by ear if you can — or by reading the accessible tree in browser
devtools. aria-label="button" passes the code check and fails the human one.
Failure modes
alt="image"/alt="icon"/alt="logo". These describe that an image exists. They pass a linter and mislead a user.- Missing
altversusalt="". An empty alt is correct for decoration; a missing alt makes the screen reader read the filename. Deleting the attribute to "fix" a warning is the wrong direction. - Long alt text on a complex chart. Screen reader users cannot pause inside
an
altstring. Put a one-line summary inaltand the detail in adjacent text that everyone can read. aria-labelon a<div>with no role. A name on a nameless element is ignored. The role has to come first.- Ten "Read more" links. Each name must identify its own target, or none of them is usable out of context (SC 2.4.4).
titleas the only label. Not reachable by keyboard on most elements, not shown on touch, and truncated in tooltips.- Empty name that looks non-empty. An
<a>containing only an<svg>with noalt,aria-label, oraria-hiddencomputes to the file name or to nothing at all.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

