Accessibility & Semantics

warning

Accessibility regressions often come from small markup changes. Test with keyboard-only navigation and verify heading structure after updates.

Accessibility & Semantics Explained

Area	What it means	Example
Semantics	Use correct HTML elements	`<nav>`, `<main>`, `<header>`
Keyboard support	Everything usable without a mouse	focus states, tab order
Skip links	Jump to main content	`<a href="#main">Skip</a>`
Contrast	Text is readable	WCAG contrast checks

Why It Matters

Accessibility improves UX for everyone.
It reduces legal/compliance risk.
It also helps SEO and overall quality.

How It Works

GeneratePress already includes accessibility work. Your child theme should extend it carefully: add small enhancements via hooks and CSS.

Practical Walkthrough

Step 1: Locate GeneratePress Accessibility CSS

locate-accessibility-css.sh
cd /var/www/html/wp-content/themes/generatepress
ls -lah assets/css | grep accessibility || true

wp-content/themes/generatepress-child/inc/hooks.php
<?php

add_action( 'wp_body_open', function() {
    echo '<a class="skip-link" href="#main">Skip to content</a>';
} );

Step 3: Add Focus Styles

wp-content/themes/generatepress-child/assets/css/a11y.css
.skip-link {
  position: absolute;
  left: -9999px;
}

.skip-link:focus {
  left: 16px;
  top: 16px;
  background: #ffffff;
  color: #0f172a;
  padding: 8px 12px;
  border: 2px solid #0f172a;
}

a:focus-visible, button:focus-visible {
  outline: 2px solid #1e3a8a;
  outline-offset: 2px;
}

Step 4: Verify the Target Anchor Exists

Your skip link targets #main. Confirm your theme outputs a main region or an element with that ID.

search-for-main-anchor.sh
cd /var/www/html/wp-content/themes/generatepress
grep -R "id=\"main\"\|<main" -n templates inc/structure 2>/dev/null | head -n 60 || true

Practical Examples

Example 1: Heading Order Rule

Use one H1 per page. In hero sections, ensure the page title does not create a second H1.

Example 2: Icon Buttons Need Text

If you add icon-only buttons, include screen-reader text or aria-label.

Example 3: A Quick Accessibility Checklist

Check	Tool
Keyboard nav	Tab/Shift+Tab
Contrast	Lighthouse / WCAG checker
Headings	Inspect DOM
Focus styles	Visual test

Example 4: Add an ARIA Label to an Icon Link (Pattern)

Icon link pattern
<a href="https://example.com" aria-label="Follow us on Example">
  <span aria-hidden="true">★</span>
</a>

Best Practices

Practice	Why
Test with keyboard only	Finds most issues quickly
Keep focus visible	Users need navigation context
Use semantic HTML	Better assistive tech support
Avoid text-in-images	Accessibility and SEO
Keep interactive targets large	Better mobile usability
Use ARIA sparingly	Prefer native semantics first

Troubleshooting

Symptom	Cause	Fix
Skip link not visible	CSS missing	Add `.skip-link:focus` styles
Focus outline removed	CSS reset	Restore focus-visible outlines
Contrast fails	Off-brand colors	Adjust tokens and re-test

Hands-On

Add a skip link via wp_body_open.
Add focus styles in a11y.css.
Test tab order on mobile and desktop.
Run Lighthouse on one page and note any a11y warnings.

Quick Reference

Task	File
Skip link hook	`inc/hooks.php`
Focus styles	`assets/css/a11y.css`

What's Next

Next: Security & Hardening
Related: Header & Navigation