Accessibility as a First Class Citizen

Accessibility works best when it is part of the theme system from the beginning.

Boilerplate does not treat accessibility as a final checklist item. It is spread through the parts users actually touch: navigation, sidebars, search forms, comments, pagination, color mode controls, link states, focus states, and screen-reader text.

Navigation needs real structure

WordPress menus need help to behave like Bootstrap 5 navigation. Boilerplate’s navwalker outputs Bootstrap-compatible menu markup while preserving WordPress menu control.

The navbar also avoids hiding while dropdowns are expanded, using Bootstrap’s accessible expanded state as part of the sticky-nav behavior. That keeps scroll behavior from fighting active navigation.

Files: lib/bootstrap_navwalker.php, assets/js/theme.js, assets/sass/parent_theme/layout/navbar.scss

Controls need labels

Icon-only controls still need names.

Boilerplate’s navbar search and color mode controls use accessible labels, titles, hidden text, and ARIA-aware updates. The color mode toggle updates its label as the target mode changes, so the control describes the action the user can take next.

Files: lib/navbar_special_items.php, assets/js/color_mode.js, searchform.php

Forms need boring correctness

Accessible forms are not fancy. They need labels, required states, visible structure, and predictable controls.

Boilerplate uses hidden labels where visual labels are not desired, required attributes where fields are required, Bootstrap form markup for consistent layout, and clear alert roles for comment feedback and moderation states.

Files: searchform.php, partials/comments/form.php, partials/comments/alert_disabled.php, partials/comments/alert_moderation.php

Hover and focus states are part of accessibility

Links and controls should visibly react when hovered, focused, or active.

Boilerplate routes link states through the theme color system and keeps focus/hover behavior explicit across navbars, pagination, post meta, widgets, comments, buttons, and form controls. This matters in both light and dark modes.

Files: assets/sass/parent_theme/global.scss, assets/sass/parent_theme/bootstrap/overrides.scss, assets/sass/parent_theme/layout/navbar.scss

Pagination needs keyboard clarity

Pagination is a common place for themes to look fine visually but feel weak for keyboard users.

Boilerplate gives pagination clear active, disabled, hover, focus, and focus-visible states. The goal is simple: users should know what page they are on, what controls are available, and where keyboard focus currently lives.

Files: pagination helper functions, partials/posts/page_links.php, pagination SASS

Comments need interaction support

Comment systems are interactive. Reply links, cloned forms, moderation messages, and direct comment anchors all need careful handling.

Boilerplate’s WordPress JavaScript handles comment reply behavior, moves focus into the reply textarea, and compensates for the admin bar when jumping to comment anchors or moderation messages.

Files: comments.php, partials/comments/*, assets/js/wordpress.js