What is the better-accessibility skill?
The better-accessibility skill is one folder in Jakub Krehel's skills repo. It reviews and fixes keyboard and focus behavior, ARIA, accessible names, forms, announcements, motion and zoom against WCAG 2.2. Each finding names the criterion it breaks or a task a user cannot finish, and fixes use your project's own styling system.
Better-accessibility reviews a project in two walks. The first is keyboard only, where every flow must finish without a mouse. The second is screen reader, where every control announces a name, a role and its state.
It prefers the platform default over a custom rebuild and removes ARIA before adding it. A finding must cite a WCAG 2.2 Level A or AA criterion by number, or a concrete task an assistive technology user cannot complete.
What it checks and fixes
- Native elements first: button for actions, a with href for navigation, never a div with onClick.
- Focus: :focus-visible rings, no outline removal without a verified replacement, and focused elements never hidden behind sticky headers.
- Dialogs: prefer dialog with showModal(), move focus in on open and return it to the trigger on close.
- Forms: real labels, autocomplete tokens, no blocked paste, errors tied to fields with aria-describedby.
- Motion and zoom: prefers-reduced-motion, a pause control after 5 seconds, 200 percent resize and reflow at 320px.
What changes in the report
Findings are grouped under the principle they violate, one row per root cause, with a severity, a path and line, the before and after code and the reason. The report ends with Block when any HIGH remains and Approve otherwise.
Who it is for
Best for
- Auditing a form, dialog, menu or full flow before release.
- Catching missing accessible names, missing focus indicators and pointer-only paths, which the skill rates HIGH on sight.
- Teams that want findings tied to WCAG criteria instead of opinions.
Not for
- Measuring contrast values. The skill hands that to better-colors and only decides which requirement applies.
- Rewriting error or label wording, which belongs to better-writing in the same repo.
- Related: web-quality-audit and web-accessibility-skill.
Use it with UiChemy
Run the review on the front end code your agent produced, fix the High items, then bring the page into WordPress with UiChemy Figma to WordPress or AI to WordPress. Click Get Started on uichemy.com.
How to install Better Accessibility Skill: WCAG 2.2 Review and Fixes
git clone https://github.com/jakubkrehel/skills.gitClone the repository
Run
git clone https://github.com/jakubkrehel/skills.git. The skill sits in the skills/better-accessibility folder.Copy the skill folder
Copy skills/better-accessibility into the folder your agent loads skills from. Keep the reference files beside SKILL.md, because the skill links to focus-and-keyboard.md, forms.md and others.
Or use the Claude Code plugin
In Claude Code, run
/plugin marketplace add jakubkrehel/skillsand then/plugin install interfaces@interfaces, the commands the README documents.Ask for a review
Point the agent at a form, dialog or page and ask for an accessibility review. Ask it to fix the findings if you want edits, since a review alone is read only.
Check that it loaded
Ask for a review of one small component. The answer should be a findings table with severity, location, before, after and why, ending in Block or Approve, with unrun checks marked Not verified.
Key features
- Two walk review methodThe agent checks a keyboard only pass and then a screen reader pass, so every control is tested for reachability, name, role and state.
- Criteria, not conventionsA finding cites a WCAG 2.2 Level A or AA criterion. AAA criteria, APG conventions and the larger target sizes are recommendations and never HIGH.
- Visible focus rulesStyle :focus-visible instead of bare :focus, avoid outline none without a replacement, and give a custom ring 3 to 1 contrast against adjacent colors.
- Dialog focus handlingPrefer the native dialog element with showModal(). Otherwise set inert on the background, move focus inside on open and restore it to the trigger on close.
- Hit area and drag rulesThe WCAG 2.5.8 baseline is a 24 by 24 CSS pixel target. Larger targets are aims, and every drag interaction needs a single pointer alternative.
- Form labeling and errorsEvery input gets a label, a valid autocomplete token and the right type. Validate on submit, mark aria-invalid and focus the first invalid field.
- Live region guidanceUse aria-describedby for field errors, role status for polite updates and role alert only for urgent errors that are not tied to a control.
- Reduced motion and timersWrap motion in a no-preference media query, replace slides with crossfades, and give anything moving for over 5 seconds a visible pause control.
- Zoom and reflowText must survive 200 percent resize and the page must reflow at 320px width. Remove maximum-scale=1 and user-scalable=no from the viewport meta.
- Pattern checklist and verdictA before you finish table flags patterns such as div onClick and positive tabindex values. The report ends with Block or Approve, and unrun checks are marked Not verified.
Frequently asked questions
What is the better-accessibility skill?
It is a skill in Jakub Krehel's skills repository that reviews and fixes keyboard and focus behavior, ARIA, accessible names, forms, screen reader announcements, motion and zoom against WCAG 2.2. It reports each failure with the criterion it breaks and writes fixes in the styling system your project already uses.
How do I install better-accessibility?
Clone jakubkrehel/skills and copy skills/better-accessibility, with its reference files, into the folder your agent loads skills from. In Claude Code you can instead run the plugin marketplace add and plugin install commands from the README. Then ask for an accessibility review of a named file or flow.
Does it measure color contrast?
It decides which contrast requirement applies, such as 4.5 to 1 for text and 3 to 1 for large text and UI boundaries. Measuring the rendered pair belongs to better-colors, and when a pair fails the skill reports the pair and the criterion it misses without changing the colors.
Which AI coding agents can use better-accessibility?
The repository README documents a Claude Code plugin install, and the skill folder includes an agents/openai.yaml file. For other agents, copy the folder to wherever that agent loads skills. The README does not list other agents, so confirm that your agent reads SKILL.md folders.
What severity levels does it use?
HIGH prevents a task, hides content from assistive technology or creates a systemic failure. MEDIUM makes an interaction meaningfully harder. LOW is isolated polish. A missing accessible name, missing focus indicator or pointer path with no keyboard path is HIGH on sight.
How is it different from better-interface?
Better-accessibility owns one domain and goes deep on it. Better-interface combines every better skill into a single review across accessibility, layout, writing, typography, color and UI polish. Run the focused skill for an accessibility pass and the combined one for a full interface verdict.
Can it replace an automated accessibility scanner?
No. Without a browser it checks names, handlers, focus styles, motion guards and label bindings in code. With a browser it can tab the flow, read the accessibility tree and run an automated audit. Anything it could not run is reported as Not verified. Related: fixing-accessibility.