Accessibility Field Guide

Developer Component Checklist

A practical checklist for checking custom buttons, links, names, roles, states, keyboard behavior, focus, and ARIA before component issues become review rework.

Photo: A Clipboard with Bond Paper Beside Pen and Laptop via Pexels — https://www.pexels.com/photo/a-clipboard-with-bond-paper-beside-pen-and-laptop-4101346/

View full screen Download image

Use this checklist when a screen includes custom buttons, links, menus, tabs, accordions, dialogs, comboboxes, icon controls, or framework components that hide the actual HTML.

The goal is not to turn every developer into an ARIA expert overnight.

The goal is to catch the common component problems while they are still small enough to fix.

A useful component should answer a few practical questions:

What is it?
What is it called?
What happens when someone activates it?
Can someone use it without a mouse?
Does the visible state match the programmatic state?
Is ARIA describing real behavior, or trying to cover for behavior that is missing?

The common project moment

A team builds or adopts a component because it solves a design or framework problem.

It looks right in the UI. It responds to a click. It may even have an ARIA attribute or two added during development.

But when someone checks it with a keyboard or screen reader, the details do not line up.

The button is really a div. The link acts like a button. The visible label does not match the accessible name. The expanded state changes visually but not programmatically. Focus moves somewhere unexpected. A disabled-looking control still works.

This checklist is for that moment before the component spreads across more screens.

Before choosing the pattern

[ ] The team can explain what the component is supposed to do in plain language.
[ ] The component is needed because a simpler native HTML element or pattern is not enough.
[ ] A native <button>, <a href="...">, input, select, checkbox, radio group, heading, list, or table was considered before a custom pattern.
[ ] The component's behavior is clear before ARIA attributes are added.
[ ] The design does not depend only on hover, color, animation, or pointer movement.
[ ] The component has a clear owner for future fixes, not just a one-time project workaround.

Native element and role checks

[ ] Interactive elements use the closest native HTML element when possible.
[ ] Links navigate to another page, route, file, section, or destination.
[ ] Buttons perform an action in the current page, dialog, form, or workflow.
[ ] Custom controls expose a role only when they actually support the expected behavior for that role.
[ ] A role is not being used because it sounds close enough.
[ ] A clickable div or span has been replaced with a native control unless there is a specific reason not to.
[ ] Disabled controls are actually unavailable to interaction, not only styled to look disabled.

Name and label checks

[ ] Every control has a useful accessible name.
[ ] Visible labels are specific enough to understand before activation.
[ ] Icon-only controls have a name that matches the visible meaning.
[ ] The accessible name does not hide vague visible wording that should be improved.
[ ] Repeated controls such as View, Edit, Download, or Delete include enough surrounding context.
[ ] The visible label and accessible name match when speech input or recognition could be affected.
[ ] Error, required, invalid, expanded, selected, pressed, checked, and busy states are not communicated only through nearby visual styling.

Keyboard and focus checks

[ ] The component can be reached with the keyboard when it is interactive.
[ ] The component can be operated with expected keys for its role.
[ ] Focus is visible when the component receives keyboard focus.
[ ] Focus order follows the visual and workflow order.
[ ] Activating the component does not create a keyboard trap.
[ ] Opening, closing, expanding, collapsing, selecting, or submitting moves focus predictably.
[ ] Focus does not disappear after loading, validation, filtering, or route changes.
[ ] Custom widgets follow the expected keyboard pattern before they are given complex ARIA roles.

State and feedback checks

[ ] Expanded and collapsed states are exposed when content opens or closes.
[ ] Selected, pressed, checked, current, invalid, required, disabled, and busy states stay synchronized with the visual state.
[ ] Loading states and status messages are announced when people need to know the result.
[ ] Validation messages identify the field, the problem, and the recovery path.
[ ] State changes do not rely on color alone.
[ ] The same interaction gives the same feedback across similar components.
[ ] Dynamic changes are tested after the first state, not only on page load.

ARIA checks

[ ] ARIA is used to describe behavior the component actually has.
[ ] ARIA is not being used to pretend keyboard support, focus management, labels, or state updates exist.
[ ] aria-label is not being used as a shortcut around unclear visible text.
[ ] aria-expanded, aria-selected, aria-pressed, aria-checked, aria-invalid, and aria-disabled update when the component changes.
[ ] ARIA relationships such as aria-controls, aria-describedby, or aria-labelledby point to real, relevant content.
[ ] Live regions are used only when the timing and message content help the user.
[ ] The team has checked the relevant ARIA Authoring Practices pattern when using a complex widget such as tabs, accordions, dialogs, or comboboxes.

Handoff and review checks

[ ] The component has been checked in at least one real screen, not only in isolation.
[ ] The design handoff includes labels, states, errors, focus behavior, and interaction notes.
[ ] Acceptance criteria describe expected keyboard behavior and state changes.
[ ] QA has a no-mouse path to test.
[ ] The team knows which component issues are shared design-system issues and which are screen-specific issues.
[ ] Known limitations are documented before external or formal review.
[ ] Fixes are made in the shared component when the same issue can repeat across screens.

Questions teams can ask

During design

What native element or standard pattern is closest to this interaction?
What should someone call this control when they cannot see the visual design?
What states does the component need to show?
What happens after activation?
Where should focus go next?

During development

What HTML is actually rendered?
Can this be reached and operated with the keyboard?
Does the role match the expected behavior?
Are names, roles, states, and values exposed correctly?
Are ARIA attributes updating when the component changes?

During QA or internal review

Can I complete the interaction without a mouse?
Can I tell what the control is, what it is called, and what state it is in?
Does the visible state match what assistive technology receives?
Does anything change visually without being announced or exposed?
Would this issue repeat anywhere else the component is used?

Common trail hazards

Making a custom element look like a button without making it behave like a button.
Using a link for an action because it was easier to style.
Adding aria-label while leaving the visible label unclear.
Setting an ARIA state once and never updating it.
Choosing a complex ARIA role without supporting the expected keyboard behavior.
Fixing one screen while leaving the shared component broken.
Testing only the happy path with a mouse.
Treating a component library as accessible without checking how it is configured in the actual screen.

Small habit

When reviewing a custom component, say this sentence out loud:

This component is a [role], called [name], currently in [state], and it can be operated by [keyboard behavior].

If the sentence is hard to complete, the component probably needs more work before ARIA can describe it accurately.

Native HTML First — for choosing the simplest working element first.
Button vs Link — for matching controls to behavior.
Link Text and Button Labels — for clear visible wording.
Accessible Names — for checking what controls are called.
Name, Role, and Value — for checking the custom-control contract.
ARIA Is Not Duct Tape — for using ARIA to describe real behavior instead of hiding broken behavior.
Accordions — for checking expandable sections, button headers, keyboard behavior, and expanded or collapsed state.
Combobox — for checking autocomplete fields, suggestion popups, selected values, keyboard behavior, focus, and ARIA state.
Tabs — for checking tab labels, selected state, panel relationships, keyboard behavior, focus, and hidden panel content.
Keyboard-Only Navigation — for a no-mouse interaction pass.
Focus Visible and Focus Order — for focus visibility and movement.
Status Messages and Alerts — for feedback after dynamic changes.
WAI-ARIA Authoring Practices Guide — for expected keyboard and interaction patterns when complex ARIA widgets are truly needed.
Accessibility Glossary — for plain-language definitions of common accessibility terms used across this guide.

What to do next

Use this checklist on one shared component before it spreads to more screens.

If the component fails several checks, start with the behavior first: native element, keyboard support, focus behavior, visible label, and state updates.

Then use ARIA only to describe the behavior that is actually there.