---
name: good-a11y
description: MANDATORY before you write or change UI. Use whenever you build or edit HTML, components, forms, dialogs, menus, tabs, navigation, focus handling, ARIA, motion or images, in any framework, even if nobody mentions accessibility.
---

# good-a11y

Accessibility guides for the things agents get wrong, and a checker for your own page. Run every command as `npx -y github:vojtaholik/good-a11y <command>`.

Use it for: forms and validation, dialogs and popovers, menus, tabs, accordions, comboboxes, custom selects, navigation and skip links, route changes, toasts, icon buttons, focus styles, motion, images.

Do not use it for: backend code, build config, copy edits with no markup, styling that adds no interactive element.

## The loop

1. `search "<2-5 words>"` names the task, such as `search "modal dialog focus"`. It prints `[{id, description}]`.
2. `retrieve "<id>[,<id>]"` prints the guides. When it prints a file path, read that file.
3. Build with them. Follow every DO and DO NOT.
4. `check <url>` on your running page, `localhost` included. `check` needs a local server and Chrome. When your sandbox blocks them (`listen EPERM`, or `check` says a sandbox is blocking it), ask the user to run the server and `check` outside the sandbox, for example by approving the command to run unsandboxed. Do not skip the check silently.
5. Fix each issue it lists with the guide it names, then check again.

`list` prints every guide.

## In your answer

End with:

### Accessibility guidance used

- `<guide id>`: what it changed in your code
- `check`: its verdict, or why you could not run it

## References

Each guide, the same text `retrieve` prints:

- [Combobox and autocomplete](https://good-a11y.com/skills/good-a11y/references/combobox-autocomplete.md): Build an accessible autocomplete, typeahead, searchable picker (country, city) or search suggestions input with role combobox, listbox and aria-activedescendant
- [Confirm before a purchase or booking](https://good-a11y.com/skills/good-a11y/references/confirm-before-purchase.md): One-click buy, "Buy now", instant booking, payment, subscription and delete actions need a review and confirm step or a way to cancel or undo afterwards
- [Custom select vs native select](https://good-a11y.com/skills/good-a11y/references/custom-select.md): Style a dropdown select accessibly with native select, appearance base-select, or a select-only combobox when custom is required
- [Modal dialog](https://good-a11y.com/skills/good-a11y/references/dialog-modal.md): Build an accessible modal dialog or popup with focus trap, Escape to close and focus return
- [Disclosure and accordion](https://good-a11y.com/skills/good-a11y/references/disclosure-accordion.md): Build an accessible show/hide toggle, FAQ accordion or expandable section with aria-expanded
- [Visible focus styles](https://good-a11y.com/skills/good-a11y/references/focus-visible.md): Style a visible keyboard focus indicator with focus-visible and outline that is never removed or hidden under sticky headers
- [Form errors and validation](https://good-a11y.com/skills/good-a11y/references/form-errors-validation.md): Show accessible form validation errors with aria-invalid, aria-describedby, an error summary and focus on submit
- [Icon-only buttons](https://good-a11y.com/skills/good-a11y/references/icon-buttons.md): Give icon-only buttons and SVG icon links an accessible name, toggle state with aria-pressed and a big enough target
- [Image alt text decisions](https://good-a11y.com/skills/good-a11y/references/image-alt.md): Decide alt text for images, decorative images, image links, logos, icons, charts and inline SVG
- [Input purpose and autofill](https://good-a11y.com/skills/good-a11y/references/input-purpose.md): Give name, email, phone, address, payment and account fields the exact autocomplete tokens so browsers, password managers and assistive tools fill and label them
- [Menu button](https://good-a11y.com/skills/good-a11y/references/menu-button.md): Build an accessible actions dropdown menu button with role menu, arrow keys and Escape, or a nav dropdown without it
- [Reduced motion and moving content](https://good-a11y.com/skills/good-a11y/references/reduced-motion.md): Respect prefers-reduced-motion in CSS and JavaScript animations, and give carousels and autoplay a pause control
- [Redundant entry](https://good-a11y.com/skills/good-a11y/references/redundant-entry.md): Never make people type the same details twice in one process; prefill or offer "same as delivery address" for billing, invoice and later steps
- [Labels, required fields and hints](https://good-a11y.com/skills/good-a11y/references/required-and-hints.md): Label form inputs, mark required fields and attach hint text with label, required, aria-describedby and autocomplete
- [Sign-in without puzzles](https://good-a11y.com/skills/good-a11y/references/sign-in-without-puzzles.md): Sign-in, login, CAPTCHA and bot checks. No typing distorted letters, solving puzzles or remembering codes to get in; allow paste and password managers
- [Skip link and landmarks](https://good-a11y.com/skills/good-a11y/references/skip-link-landmarks.md): Add a skip to main content link and page landmarks (header, nav, main, footer) with correct labels and heading structure
- [Route change in single-page apps](https://good-a11y.com/skills/good-a11y/references/spa-route-change.md): Manage focus, page title and announcements on client-side route changes in a React, Vue or SPA router
- [Status messages and toasts](https://good-a11y.com/skills/good-a11y/references/status-messages-toast.md): Announce toasts, snackbars, "added to cart" and save confirmations to screen readers with role status, aria-live and no focus move
- [Swipe and drag alternatives](https://good-a11y.com/skills/good-a11y/references/swipe-and-drag.md): Swipe to delete, drag to reorder, sliders, carousels and drag-and-drop need a single click or tap alternative, and a swipe must be cancellable before release
- [Tabs](https://good-a11y.com/skills/good-a11y/references/tabs.md): Build accessible tabs with tablist, tab and tabpanel roles, roving tabindex and arrow key navigation
- [Time limits and timeout warnings](https://good-a11y.com/skills/good-a11y/references/timeouts-and-warnings.md): Cart holds, reservations, session timeouts, auto sign-out and countdowns. Warn before time runs out and let people extend it with one simple action