Accessible WordPress Blocks: An Engineering Checklist

An accessible WordPress block must produce meaningful structure, support keyboard and assistive-technology interaction, communicate state, and remain usable with real content. Passing an automated scan is not enough. Accessibility has to be part of the block contract from design through deprecation.

This engineering guide is part of the enterprise WordPress accessibility governance cluster. It focuses on custom Gutenberg blocks, block variations, interactive components, and editor guardrails.

Accessible Block Engineering at a Glance

Concern	Engineering requirement
Semantics	Use the correct native element and heading structure
Keyboard	Every action works without a pointer
Focus	Visible, logical, and restored after dynamic changes
Name and state	Controls expose accurate accessible names and states
Content	Editor choices cannot easily create invalid output
Responsive use	Zoom, reflow, and text resizing preserve operation
Motion	Animation respects preferences and does not block use
Testing	Automation plus keyboard, screen-reader, zoom, and content tests

Start With the Semantic Contract

Define what the component is before deciding how it looks. A link navigates, a button performs an action, a heading labels a section, a list represents related items, and a table represents data relationships.

• Prefer native HTML elements.
• Do not turn a generic container into a button when a button works.
• Keep heading levels compatible with surrounding content.
• Expose form labels programmatically.
• Use landmarks only where they clarify page structure.
• Add ARIA only when native semantics cannot express the requirement.

The official WordPress accessibility coding standards align WordPress code with WCAG 2.2 Level AA expectations.

Design Keyboard Behavior Before Coding

List every action and its expected keys. Standard controls should use standard browser behavior. Complex widgets should follow a recognized interaction pattern and should not invent surprising shortcuts.

Component	Minimum keyboard behavior
Button	Tab to focus, Enter or Space to activate
Link	Tab to focus, Enter to follow
Disclosure	Activate control, expose expanded state, keep logical focus
Modal	Move focus inside, contain it appropriately, close safely, restore focus
Tabs	Documented arrow-key and activation behavior
Menu	Predictable navigation and escape behavior appropriate to the pattern

Never remove a visible focus indicator without providing an equivalent that works across component backgrounds and states.

Expose Name, Role, Value, and State

Assistive technology needs an accessible name, role, current value where relevant, and state such as expanded, selected, pressed, invalid, or busy. These must update when the visual interface changes.

<button
    type="button"
    aria-expanded="false"
    aria-controls="acme-panel"
>
    Show technical details
</button>

<div id="acme-panel" hidden>
    ...
</div>

The script must update aria-expanded and the hidden state together. ARIA that disagrees with the visual and interactive state creates a new defect.

Engineer Focus for Dynamic Blocks

• Move focus only when the user’s action changes context.
• Restore focus when a modal or temporary workflow closes.
• Do not reset focus after every render.
• Ensure inserted validation messages can be discovered.
• Keep focus order aligned with the visual and reading order.
• Test route-like transitions in interactive WordPress experiences.

Focus management is especially important for modals, drawers, search results, pagination, validation, and blocks built with the WordPress Interactivity API.

Make Editor Controls Produce Safe Output

Block accessibility includes the authoring experience and the content authors create. Limit choices that predictably cause barriers.

Editor risk	Guardrail
Arbitrary heading level	Offer levels allowed by the pattern or explain hierarchy
Text over unknown image	Provide overlay and contrast-safe options
Icon-only control	Require a meaningful accessible label
Autoplay media	Disable by default and require controls
Empty link	Validate destination and link text
Color-only meaning	Provide text, icon, or pattern alternatives

Use block validation, inspector guidance, defaults, and patterns to make the accessible path the easiest path.

Handle Images, Icons, and Media

• Decorative images should have empty alternative text.
• Informative images need alternatives that express purpose in context.
• Linked images need alternatives that describe the destination or action.
• Icons should not be the only source of a control’s name.
• Video needs captions and may need transcripts or audio description.
• Audio needs an appropriate transcript and accessible controls.

Do not derive alternative text blindly from filenames or AI output. Authors remain responsible for meaning in context.

Support Zoom, Reflow, and Content Stress

Test at browser zoom and narrow widths with long headings, translations, large text, empty optional fields, and repeated items. Avoid fixed heights and clipped containers around text.

• Use flexible layout and intrinsic sizing.
• Allow controls to wrap without hiding actions.
• Preserve reading order when columns collapse.
• Do not require horizontal scrolling for normal content.
• Keep sticky interfaces from covering focused elements.
• Test user-generated content beyond the ideal demo.

Respect Motion and Timing Preferences

Animation should not be required to understand or operate a block. Respect reduced-motion preferences, provide pause controls where required, and avoid unexpected movement after content loads.

Timeouts and session warnings must provide enough notice and an accessible way to extend time when the underlying task permits it.

Keep Frontend and Editor Accessibility Separate

A block has two interfaces: the editor experience and the rendered frontend. Test both. An accessible frontend block can still be impossible for an editor using a keyboard or screen reader to configure.

Editor tests	Frontend tests
Block insertion and discovery	Semantic output
Toolbar and inspector controls	Keyboard interaction
Selection and movement	Focus order and management
Validation and instructions	Names, states, and errors
Saved-state clarity	Responsive, zoom, and media behavior

Accessible Block Definition of Done

• Semantic contract documented.
• Keyboard interaction defined and tested.
• Visible focus works in every state.
• Accessible names and states remain synchronized.
• Editor guardrails prevent known failures.
• Content stress and localization tested.
• Zoom, reflow, contrast, and reduced motion verified.
• Automated checks pass.
• Manual assistive-technology testing completed for complex behavior.
• Documentation includes limitations and usage guidance.

Frequently Asked Questions

For program-level ownership and remediation, see Enterprise WordPress Accessibility Governance.