What is the fixing-accessibility skill?
The fixing-accessibility skill is a SKILL.md from the ibelick/ui-skills repo. It gives your coding agent nine ranked rule groups, from accessible names and keyboard access to contrast and motion. Run it on a file and it reports each violation with the exact snippet, a one-line reason and a minimal fix.
fixing-accessibility is an agent skill from the ibelick/ui-skills repo. It is a single SKILL.md that tells your coding agent how to audit HTML and component code for accessibility problems, and how to fix them with small edits.
Its rules are ranked in nine groups by impact. Accessible names, keyboard access and focus handling are marked critical, while media and motion sit near the bottom. The agent works through them in that order.
What changes in your agent's output
- An icon-only button gets an
aria-labeland its decorative SVG getsaria-hidden - A
divwith anonclickbecomes a realbutton - A form error gets an id, and the input points to it with
aria-describedbyandaria-invalid - A dialog traps focus, sets initial focus inside and returns focus to the trigger on close
- Review mode quotes the exact line, gives a one-sentence reason and proposes a concrete fix
Run /fixing-accessibility to apply the rules to all UI work in the conversation, or /fixing-accessibility <file> to review one file. The skill tells the agent not to rewrite large parts of the UI. For animation jank, pair it with fixing-motion-performance.
The nine rule groups
| Priority | Group | Impact |
|---|---|---|
| 1 | Accessible names | Critical |
| 2 | Keyboard access | Critical |
| 3 | Focus and dialogs | Critical |
| 4 | Semantics | High |
| 5 | Forms and errors | High |
| 6 | Announcements | Medium-high |
| 7 | Contrast and states | Medium |
| 8 | Media and motion | Low-medium |
| 9 | Tool boundaries | Critical |
Who it is for
Best for
- Frontend work with new buttons, links, inputs, menus, dialogs, tabs or dropdowns
- Forms with validation, helper text and error states
- Icon-only controls and hover-only interactions
- Reviewing AI-generated components before they ship
Not for
- A formal WCAG conformance report. It is a rule list for an agent and cites no success criteria
- Large refactors or moving to a different UI library. The skill forbids both unless you ask
- Testing a live page with a screen reader. It reviews source files
Use it with UiChemy
If you bring an AI-generated build into WordPress with UiChemy AI to WordPress, run this skill on the markup first. Then check keyboard focus again on the imported Elementor or Gutenberg page, since the skill reviews source, not the converted result.
How to install Fixing Accessibility
git clone https://github.com/ibelick/ui-skills.gitClone the repo
Run the command above. The skill lives in
skills/fixing-accessibilityand is oneSKILL.mdfile.Copy the folder
Copy
skills/fixing-accessibilityinto your agent's skills directory. For Claude Code that is~/.claude/skills/for every project or.claude/skills/inside one project.Apply it
Type
/fixing-accessibilityto apply the rules to the session, or/fixing-accessibility src/components/Dialog.tsxto review a single file.
Check that it loaded
Start a new session and type /fixing-accessibility. With a file path, the agent should return violations with the quoted snippet, a one-line reason and a small fix.
Key features
- Accessible names firstEvery control needs a name. Icon-only buttons need
aria-labeloraria-labelledby, inputs, selects and textareas must be labeled, decorative icons getaria-hidden, and "click here" links are flagged. - Keyboard accessA
divorspanused as a button needs full keyboard support. Everything interactive must be reachable by Tab, focus must be visible,tabindexabove 0 is banned and Escape closes dialogs. - Focus and dialogsModals trap focus while open, set initial focus inside the dialog and restore focus to the trigger on close. Opening a dialog must not scroll the page unexpectedly.
- Native semantics over ARIANative
button,aandinputbeat role-based hacks, and any role used must carry its required attributes. Lists useulorolwithli, headings never skip levels and tables useth. - Form error wiringErrors link to fields with
aria-describedby, invalid fields setaria-invalid, required fields are announced, helper text is tied to its input and a disabled submit explains why. - AnnouncementsCritical form errors use
aria-live, loading states usearia-busyor status text, and toasts are never the only way to show critical information. Expandable controls usearia-expandedandaria-controls. - Contrast and non-color statesText and icons need enough contrast, hover-only interactions need a keyboard equivalent and disabled states cannot rely on color alone. Focus outlines are never removed without a visible replacement.
- Media and motionImages get meaningful or empty alt text, speech in video should have captions,
prefers-reduced-motionis respected for non-essential motion and media with sound should not autoplay. - Tool boundariesChanges stay minimal and unrelated code stays untouched. The agent adds no ARIA where native semantics already solve the problem and migrates no UI library unless requested.
- Review report formatIn file review mode every finding quotes the exact line or snippet, states why it matters in one short sentence and gives a code-level fix. Critical groups are fixed first.
Frequently asked questions
What is the fixing-accessibility skill?
It is a SKILL.md from the ibelick/ui-skills repo that teaches a coding agent to audit HTML and component code for accessibility problems. It covers accessible names, keyboard access, focus and dialogs, semantics, form errors, announcements, contrast and media, and it pushes the agent toward small, targeted fixes instead of rewrites.
How do I install the fixing-accessibility skill?
Clone the ibelick/ui-skills repo with git, then copy the skills/fixing-accessibility folder into your agent's skills directory. In Claude Code that is ~/.claude/skills/ for all projects or .claude/skills/ inside a single project. The folder contains one SKILL.md, so nothing else needs installing.
How do I run fixing-accessibility on one file?
Type /fixing-accessibility followed by the file path. The agent reviews the file against every rule and reports each violation with the exact line or snippet, one short sentence on why it matters and a concrete code-level fix. Without a path, the rules apply to all UI work in the conversation.
Will fixing-accessibility rewrite my UI?
No. The skill says not to rewrite large parts of the UI and to prefer minimal, targeted fixes. It also tells the agent not to refactor unrelated code, not to add ARIA where native HTML already solves the problem and not to migrate UI libraries unless you request it.
Does fixing-accessibility replace testing with a screen reader?
No. It is a source-level rule list the agent applies to code, so it catches missing names, unreachable controls and unlinked errors in markup. It does not run a browser or a screen reader, so you still verify keyboard and focus behavior on the rendered page.
What does the fixing-accessibility skill check first?
Critical groups come first: accessible names, keyboard access, focus and dialogs, and tool boundaries. Semantics and form errors rank high, announcements medium-high, contrast and states medium, and media and motion low-medium. The skill tells the agent to fix critical issues before anything else.
Is the fixing-accessibility skill free to use?
Yes. The ibelick/ui-skills repo is published under the MIT license, so you can use, copy and adapt the skill in your own projects. The skill itself is a plain text SKILL.md file, and installing it means copying one folder from the repository into your agent's skills directory.
Which other skills are in the same repo?
The ibelick/ui-skills repo also holds baseline-ui, create-design-md, fixing-metadata, fixing-motion-performance and improve-ui. Pair this skill with fixing-metadata for titles, canonical and Open Graph tags, fixing-motion-performance for animation jank, or improve-ui to audit a product surface against its own design system. Each skill is a separate folder under skills/, so you can install only the ones you need.