---
name: checking-semantic-accessibility
description: Finds accessibility failures that automated linters pass — generic button labels, vague link text, unhelpful alt text, wrong ARIA, and unlabelled form fields. Use after generating any UI, when reviewing components or a diff for accessibility, when axe or eslint-plugin-jsx-a11y reports clean but the interface has not been read, or when the user mentions accessibility, a11y, WCAG, screen readers or assistive technology. Applies to every generated interface, because these failures are invisible to structural tooling.
license: CC0-1.0
---

# Checking semantic accessibility

A CHI 2026 study measured 541 semantic accessibility issues across 300
LLM-generated interfaces — about 1.8 per interface. Every one of them passes
axe-core, because they are semantic failures rather than structural ones. The
element is present, labelled, and focusable. The label just does not mean
anything.

This is why a green accessibility check on agent-generated UI proves very
little on its own.

## The five, by measured frequency

### 1. Generic button labels — 27% of findings

The name has to say what the action does, in isolation, with no surrounding
context.

- Wrong: `Submit`, `OK`, `Click here`, `aria-label="button"`
- Right: `Save changes`, `Delete 3 invoices`, `Send invitation`

An icon-only button needs an accessible name that states the action, not the
icon. `aria-label="trash"` describes the picture; `aria-label="Delete draft"`
describes the action.

### 2. Vague link text — 26%

Link text is read out of context in a links list. "Learn more" appearing
eleven times on a page is eleven identical entries.

- Wrong: `Learn more`, `Read more`, `Here`, `This page`
- Right: `Read the migration guide`, `View billing history`

### 3. Poor alt text — 20%

Describe the content and function, not the file.

- Wrong: `alt="image"`, `alt="screenshot.png"`, `alt="chart"`
- Right: `alt="Revenue rose from 2.1M to 3.4M between Q1 and Q3"`
- Decorative: `alt=""` — explicit and empty, never omitted.

### 4. ARIA misuse — 14%

The first rule of ARIA is not to use it. A `div` with `role="button"` and a
click handler needs keyboard handling, focus management and a tabindex that a
real `button` gives you free. Reach for the native element.

Never put `aria-label` on an element that already has a visible label, unless
the two say the same thing — screen readers announce the aria one and the
sighted user reads the other.

### 5. Generic form labels — 12%

Every field needs a programmatically associated label. Placeholder text is not
a label: it disappears on focus and fails contrast in most implementations.
Error text must be associated too, and must say how to fix the problem.

## How to run this pass

Read the rendered output as text, in order, ignoring the visual layout. Then:

1. List every interactive element and its accessible name. Any name that does
   not state an action is a finding.
2. List every link's text. Any that does not make sense alone is a finding.
3. List every image and its alt. Any that describes the file rather than the
   content is a finding.
4. Check every form control has an associated label, not a placeholder.
5. Check focus order matches visual order.

## What this skill does not cover

Contrast, target size, and structural landmarks. Those are real requirements
and automated tools genuinely do catch them — run the linter for those and
spend your reading on the five above.