| name | web-a11y-authoring |
| description | Builds accessible pages and components with semantic HTML, correct names/roles/states, keyboard support, focus management, links, images, SVG, media, and native controls first. Use when implementing or refactoring frontend UI. |
Web A11y Authoring
Core Rules
For concrete markup patterns, see PATTERNS.md.
- Prefer native HTML controls before ARIA or custom widgets.
- Use links for navigation and buttons for actions.
- Ensure every interactive control has a clear accessible name.
- Keep DOM order aligned with reading and interaction order.
- Preserve visible focus and keyboard operation for every interaction.
- Use ARIA only to supplement semantics that cannot be expressed natively.
- Classify images, icons, and SVG as decorative, informative, or functional.
- Communicate unusual link behavior before activation.
Authoring Checklist
Authoring checklist
- [ ] Page has meaningful title, language, landmarks, and heading structure
- [ ] Controls expose role, name, state, and value correctly
- [ ] Interactions work with keyboard alone
- [ ] Focus is visible, logical, and intentionally managed
- [ ] Hidden content is not accidentally focusable or announced
- [ ] Native control behavior is preserved under custom styling
- [ ] Links describe destination/action, including downloads and context changes
- [ ] Images, SVG, and icons have appropriate text alternatives or are hidden correctly
- [ ] Audio/video has controls and alternatives such as captions or transcripts when needed
Common Patterns
- Toggle button: native
button with synchronized state such as aria-pressed.
- Disclosure: button with synchronized
aria-expanded and hidden content state.
- Dialog: intentional initial focus, contained interaction while open, focus restored on close.
- Icon-only control: visible or programmatic accessible name that describes the action.
- Download/file link: link text includes action, target, file type, and size when useful.
- Functional image/SVG: accessible name describes the action or destination.
- Decorative image/SVG: removed from the accessibility tree without hiding useful text.
- Media: avoid disruptive autoplay, provide controls, and include captions/transcripts when content requires them.
Output
Describe semantic choices, ARIA states used, non-text content decisions, keyboard behavior, and manual test plan.
