# good-a11y

> Accessibility guides for coding agents, each with a live demo, and a checker that finds accessibility issues on one page.

Every page is also served as Markdown: send `Accept: text/markdown`. Agents run the guides and the checker locally with `npx -y github:vojtaholik/good-a11y`.

## When to use

Use good-a11y before you write or change UI: forms and validation, dialogs and popovers, menus, tabs, accordions, comboboxes, custom selects, navigation and skip links, route changes in single-page apps, toasts and status messages, icon buttons, focus styles, motion and images, in any framework.

1. `npx -y github:vojtaholik/good-a11y search "<2-5 words>"` finds the guide for the task, for example `search "modal dialog focus"`.
2. `npx -y github:vojtaholik/good-a11y retrieve <id>` prints it. Follow every DO and DO NOT while you build.
3. `npx -y github:vojtaholik/good-a11y check <url>` checks your running page, localhost included, in your own Chrome. Fix each issue with the guide it names, then check again.

Do not use it for backend code, build configuration, or copy edits that add no markup.

## Agents

- [good-a11y skill](https://good-a11y.com/skills/good-a11y/SKILL.md): triggers and the search, retrieve, build and check loop
- [Check a page](https://good-a11y.com/check): what the checker tests, per WCAG success criterion
- [About](https://good-a11y.com/about): who makes good-a11y and how the guides are tested
- [Privacy](https://good-a11y.com/privacy): what the checker stores and for how long

## Guides

- [Combobox and autocomplete](https://good-a11y.com/guides/combobox-autocomplete): 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/guides/confirm-before-purchase): 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/guides/custom-select): 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/guides/dialog-modal): Build an accessible modal dialog or popup with focus trap, Escape to close and focus return
- [Disclosure and accordion](https://good-a11y.com/guides/disclosure-accordion): Build an accessible show/hide toggle, FAQ accordion or expandable section with aria-expanded
- [Visible focus styles](https://good-a11y.com/guides/focus-visible): 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/guides/form-errors-validation): Show accessible form validation errors with aria-invalid, aria-describedby, an error summary and focus on submit
- [Icon-only buttons](https://good-a11y.com/guides/icon-buttons): 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/guides/image-alt): Decide alt text for images, decorative images, image links, logos, icons, charts and inline SVG
- [Input purpose and autofill](https://good-a11y.com/guides/input-purpose): 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/guides/menu-button): 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/guides/reduced-motion): Respect prefers-reduced-motion in CSS and JavaScript animations, and give carousels and autoplay a pause control
- [Redundant entry](https://good-a11y.com/guides/redundant-entry): 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/guides/required-and-hints): 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/guides/sign-in-without-puzzles): 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/guides/skip-link-landmarks): 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/guides/spa-route-change): 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/guides/status-messages-toast): 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/guides/swipe-and-drag): 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/guides/tabs): Build accessible tabs with tablist, tab and tabpanel roles, roving tabindex and arrow key navigation
- [Time limits and timeout warnings](https://good-a11y.com/guides/timeouts-and-warnings): Cart holds, reservations, session timeouts, auto sign-out and countdowns. Warn before time runs out and let people extend it with one simple action