Start with the HTML element before adding a role
A native <button> already exposes button semantics and supports activation with the keyboard. A <nav> identifies a navigation landmark, while a properly associated <label> names its form control. Adding role="button" to a generic <div> does not automatically supply keyboard support, focus management, or expected behavior.
Choose the correct HTML element first. Add ARIA when the interface needs information that HTML does not supply by itself, such as whether a disclosure is expanded or whether a toggle button is pressed. An accessibility checker may flag an explicit role as redundant, but redundant and invalid are different problems: some redundancy is merely unnecessary, while conflicting semantics can mislead assistive technologies.
Inspect the markup that users actually receive
For a simple static component, checking its HTML snippet may be sufficient to find misspelled attributes or invalid values. For a JavaScript-driven interface, the initial page source can be incomplete. A menu might begin with aria-expanded="false" and change to true only after a click.
Use the input method available in the checker interface above. If it accepts a snippet, include the control and its referenced target element together. If it supports URL inspection, remember that authenticated pages, client-rendered components, and changing states may not be fully represented by a single request. Do not assume a successful static check covers every interaction.
Read ARIA issues in four passes
- Attribute and role names: Confirm that names such as
aria-labelledby are spelled correctly and that any explicit role is recognized. A typo may cause a browser to ignore the intended semantics.
- Values: Check each attribute against its permitted value type. For an open or closed disclosure,
aria-expanded should be true or false, not open or maybe. The attribute also defines an undefined state for nonexpandable elements. Other attributes accept tokens, numbers, or ID references.
- Role compatibility: Ask whether that attribute makes sense for the element’s implicit or explicit role. Some roles require a particular state, while other elements must not be given certain names or roles.
- Relationships and behavior: Follow IDs referenced by
aria-labelledby, aria-describedby, and aria-controls. Verify that the target exists, IDs are unique, and the control behaves as its announced state implies.
Not every tool implements all four checks. Treat the displayed findings as evidence to investigate, not as proof that every other ARIA requirement passed.
Common ARIA attributes and what they communicate
These descriptions summarize typical uses. The correct application always depends on the element, its role, and the current WAI-ARIA and ARIA-in-HTML requirements.
Worked example: repair a disclosure that announces the wrong state
Consider a custom control intended to reveal shipping details. The following markup has an invalid expanded value and uses a generic element that lacks native button interaction:
<div role="button" aria-expanded="maybe" aria-controls="shipping-details">
Show shipping details
</div>
<div id="shipping-details" hidden>Delivery options appear here.</div>
Start with a real button and a valid initial state:
<button type="button" aria-expanded="false" aria-controls="shipping-details">
Show shipping details
</button>
<div id="shipping-details" hidden>Delivery options appear here.</div>
This correction is only the starting markup. The application must still reveal the content when activated, set aria-expanded to true, and reverse both changes when the region closes. A native button provides Enter and Space activation, but its event handling must actually implement the disclosure behavior. A static validator cannot confirm that those updates happen.
Check references, hidden content, and accessible names
An ID reference can look syntactically valid while pointing to nothing. For example, aria-labelledby="dialog-title" is only useful when the expected element with that ID is present in the same document context. Duplicate IDs also make naming relationships unreliable. Inspect the actual rendered document when components generate IDs dynamically.
Be particularly careful with aria-hidden="true". Hiding a decorative icon from assistive technology can be appropriate. Applying it to a container holding a keyboard-focusable link or button is not. The hidden control might still receive keyboard focus even though its semantics have been removed from the accessibility tree.
Names require judgment as well as syntax. An icon-only button may need a meaningful accessible name; a visible text button often already has one. Adding an unrelated aria-label can override what a screen reader announces. Review form-control naming separately with the Form Label Checker.
Test dynamic components beyond the first scan
Custom tabs, dialogs, menus, accordions, and comboboxes need more than valid attribute values. Their keyboard patterns, focus behavior, and state changes must remain synchronized. A tab can correctly declare aria-selected="true" yet fail to move focus or display the selected panel. A dialog can carry aria-modal="true" while leaving focus outside the dialog.
Operate each component with a keyboard. Open and close it, change selections, dismiss it, and inspect the updated DOM. Then test relevant browser and screen-reader combinations. For page-level semantics, pair this review with the HTML Landmark Checker and Heading Structure Checker.
What a successful ARIA check does not establish
A clean attribute report does not establish conformance with WCAG, prove that a screen reader announces the right thing, or demonstrate usable keyboard navigation. Automated rules are especially good at finding recognizable mistakes such as unknown attribute names, invalid values, and some missing required states. They are less able to judge whether an interaction makes sense or whether a label communicates the user’s intended action.
Accessibility also includes contrast, visible focus, touch targets, alternative text, and error recovery. Those problems can exist even when the ARIA markup is technically correct. Treat automated checking as an early review stage, followed by manual interaction and assistive-technology testing.
Use ARIA reviews in a WordPress publishing workflow
On WordPress sites, review new blocks, navigation menus, search widgets, popup plugins, and custom interactive features after installation or major updates. Theme and plugin scripts can add or change ARIA attributes after the original HTML loads. Test the actual page and its open, closed, loading, and error states rather than relying only on a block’s source markup.
Keep a short record of the problematic component, its original HTML, the change made, and the manual test result. Recheck the component whenever a theme update or custom JavaScript revision changes its behavior. This makes accessibility fixes more dependable than resolving warnings once and assuming they will remain correct.
Frequently asked ARIA questions
Does every interactive element need an ARIA role?
No. Native HTML elements already supply many roles and built-in behaviors. Use appropriate HTML before adding ARIA.
Is aria-label the same as a visible label?
No. It provides an accessible name in supported contexts but does not create visible text. Where practical, meaningful visible labels make interfaces easier to understand for more users.
Can an ARIA checker confirm WCAG 2.2 compliance?
No. ARIA validation covers only a portion of accessibility. WCAG evaluation requires reviewing relevant success criteria and testing actual interactions.
Why might a valid ARIA attribute still cause problems?
Its value may be valid while the state is stale, the name is misleading, the element’s role is inappropriate, or the required keyboard behavior is missing.
