skills / design

fixing-accessibility

what it does

Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance.

Verified Before and after: 2 models 1 try per case View source Download .zip

Compare the answers

Answers from Claude Sonnet 5.5 and GPT-6.1 Sol · try 1 of 1

Same request, same model, once with the skill and once without. Read both and judge for yourself.

“Can you check this toolbar for accessibility problems?”

Source material given with the request

<div class="toolbar"> <div class="btn" onclick="saveDoc()">Save</div> <button onclick="deleteDoc()"><svg viewBox="0 0 24 24"><path d="M3 6h18M8 6V4h8v2m-9 0v14h10V6"/></svg></button> <button onclick="share()"><svg viewBox="0 0 24 24"><path d="M4 12v8h16v-8M12 3v13M7 8l5-5 5 5"/></svg> Share</button> <a href="/help/editor">Click here</a> to learn about the editor. </div>
with the skill
# Accessibility review: toolbar I found 4 violations (plus one optional improvement), ordered by priority. ## 1. Div used as a button (keyboard access, critical) ```html <div class="btn" onclick="saveDoc()">Save</div> ``` **Why it matters:** A `div` isn't focusable and doesn't respond to Enter/Space, so keyboard and screen reader users can't use it. **Fix:** Use a native button. Keep the class so styling carries over. ```html <button type="button" class="btn" onclick="saveDoc()">Save</button> ``` If the `.btn` styles assume a div, you may need to reset default button styles (border, background, font). Don't add `role`/`tabindex` hacks.
Show the rest (70 more lines)
## 2. Icon-only Delete button has no accessible name (critical) ```html <button onclick="deleteDoc()"><svg viewBox="0 0 24 24"><path d="M3 6h18M8 6V4h8v2m-9 0v14h10V6"/></svg></button> ``` **Why it matters:** Screen readers announce this as just "button", so users can't tell it deletes the document. **Fix:** Add an `aria-label` and hide the decorative SVG. ```html <button type="button" onclick="deleteDoc()" aria-label="Delete document"> <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 6h18M8 6V4h8v2m-9 0v14h10V6"/></svg> </button> ``` ## 3. Decorative icon in the Share button isn't hidden (names, minor) ```html <button onclick="share()"><svg viewBox="0 0 24 24">...</svg> Share</button> ``` **Why it matters:** The button already has a name ("Share") from its text, but the unhidden SVG can add noise for some assistive tech. **Fix:** ```html <button type="button" onclick="share()"> <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 12v8h16v-8M12 3v13M7 8l5-5 5 5"/></svg> Share </button> ``` ## 4. Non-descriptive link text (names, critical) ```html <a href="/help/editor">Click here</a> to learn about the editor. ``` **Why it matters:** Screen reader users often browse a list of links out of context, where "Click here" says nothing about the destination. **Fix:** Put the descriptive words inside the link. ```html Learn about the editor in the <a href="/help/editor">editor help guide</a>. ``` ## Optional improvements - **`type="button"`:** I added it to all buttons. It's not an a11y violation by itself, but it prevents accidental form submission if the toolbar is ever placed inside a `<form>`. - **Focus visibility:** Your snippet has no CSS, so I can't verify this. Make sure `.btn`/`button` styles don't have `outline: none` without a visible `:focus-visible` replacement. - **Toolbar semantics:** I'd leave `class="toolbar"` as is. Adding `role="toolbar"` would require arrow-key navigation (roving tabindex), which is more than this simple set of controls needs. A plain group of buttons is fine. ## Corrected snippet ```html <div class="toolbar"> <button type="button" class="btn" onclick="saveDoc()">Save</button> <button type="button" onclick="deleteDoc()" aria-label="Delete document"> <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M3 6h18M8 6V4h8v2m-9 0v14h10V6"/></svg> </button> <button type="button" onclick="share()"> <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 12v8h16v-8M12 3v13M7 8l5-5 5 5"/></svg> Share </button> Learn about the editor in the <a href="/help/editor">editor help guide</a>. </div> ``` One more consideration: `deleteDoc()` is destructive. If it doesn't already confirm with the user, consider a confirmation dialog. If you add one, follow the dialog rules: trap focus, close on Escape, and restore focus to the Delete button.
without
# Accessibility review ## Problems **1. Save is a `<div>`, not a button (critical)** `<div class="btn" onclick>` isn't focusable, has no role, and doesn't respond to Enter or Space. Keyboard and screen reader users can't use it (WCAG 2.1.1, 4.1.2). Use a real `<button>`. **2. Delete button has no accessible name (critical)** It contains only an SVG, so a screen reader announces just "button". Add an `aria-label` or visually hidden text (WCAG 4.1.2, 1.1.1). Since it's destructive, also consider a confirmation or undo. **3. Link text "Click here" is not descriptive (serious)** Out of context, such as in a screen reader's links list, it says nothing about the destination (WCAG 2.4.4). The link also covers only part of the sentence. Make the link text meaningful. **4. Decorative SVGs aren't hidden from assistive tech (minor)** In the Share button the icon is redundant next to the text. Add `aria-hidden="true"` and `focusable="false"` so it isn't announced or focusable in older browsers. **5. Icons may not render or adapt to high-contrast mode (functional/minor)** The paths are open strokes with no `stroke` or `fill` set, so they will likely be invisible (default is black fill, no stroke). Use `stroke="currentColor" fill="none"` so the icons render and follow text color, including in forced-colors mode. Icon contrast should be at least 3:1 (WCAG 1.4.11). **6. Toolbar container has no semantics (minor)**
Show the rest (37 more lines)
A plain `<div>` doesn't tell users it's a group of controls. If you add `role="toolbar"`, you must also implement arrow-key navigation with roving tabindex. Otherwise, `role="group"` with a label is simpler. The help link and sentence also don't belong inside the toolbar. ## Things to verify in your CSS - A visible focus indicator exists (don't use `outline: none` without a replacement; use `:focus-visible`). - Targets are at least 24×24 CSS px (WCAG 2.5.8), ideally larger. The icon-only button is the most at risk. - Text and icon colors meet contrast requirements. ## Suggested fix ```html <div class="toolbar" role="group" aria-label="Document actions"> <button type="button" class="btn" id="save">Save</button> <button type="button" id="delete" aria-label="Delete document"> <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2"> <path d="M3 6h18M8 6V4h8v2m-9 0v14h10V6"/> </svg> </button> <button type="button" id="share"> <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2"> <path d="M4 12v8h16v-8M12 3v13M7 8l5-5 5 5"/> </svg> Share </button> </div> <p> <a href="/help/editor">Learn about the editor</a> </p> ``` Then attach handlers with `addEventListener('click', ...)` instead of inline `onclick`. This isn't strictly an accessibility requirement, but it's cleaner and works well with CSP. If you want a true ARIA toolbar (`role="toolbar"`), I can show the roving-tabindex and arrow-key script.

Answers are shown exactly as the model wrote them, from the first try, and nothing is picked by hand.

The models

2 models

Claude Sonnet 5.5

made by Anthropic

claude-sonnet-5-5 · revision not reported by the provider

1 try per case · tested 3 Nov 2026

GPT-6.1 Sol

made by OpenAI

gpt-6.1-sol · revision not reported by the provider

1 try per case · tested 3 Nov 2026

The tasks

written by Carte Blanche
accordion-minimal-fix

“Fix the accessibility issue in this accordion. Please keep the change small, we can't refactor this component right now.”

contrast-and-focus-css

“Accessibility audit on our marketing site CSS, please.”

custom-modal-focus

“Here's our custom modal. Keyboard users say it's hard to use. What's wrong and how do I fix it?”

signup-form-errors

“Our signup form fails accessibility review. What needs fixing?”

toolbar-names-and-buttons

“Can you check this toolbar for accessibility problems?”

Install

Download the .zip and unzip it. Put its files, in a folder named fixing-accessibility, here:

Claude Code~/.claude/skills/Every project. For one project only, use .claude/skills/ inside it.
Codex~/.agents/skills/Every project. For one repository only, use .agents/skills/ inside it.
Cursor~/.cursor/skills/Cursor also reads the Claude Code and Codex folders above.

Then start a new session and ask for what the skill does. Other agents that read SKILL.md have their own skills folder; check their docs.

Coming after launch: get skills from inside your agent, no download needed.