Fix Semantic HTML Accessibility (2026)

Semantic HTML is the foundation of accessible web development. When you use the right elements. <nav>, <main>, <button>, <label>. you give screen readers and other assistive technologies the signals they need to navigate your pages correctly. Claude Code, combined with the frontend-design skill, helps you audit existing markup and enforce accessibility-focused patterns consistently across your project.

This guide focuses specifically on the accessibility dimension of semantic HTML: WCAG compliance, assistive technology compatibility, and testable accessibility requirements. For broader structural refactoring (replacing divs, advanced HTML elements), see the Semantic HTML Improvement Guide.

Why Semantic HTML Matters for Accessibility

Screen readers rely on semantic elements to navigate pages efficiently. Users of assistive technology can jump between landmark regions, cycle through headings, and activate interactive elements. but only if the markup signals the correct roles.

When you write semantic markup, you provide a structural map of your content. Instead of announcing “group” for every <div>, a screen reader can announce “navigation”, “main content”, or “button” based on the element used. That distinction determines whether a user can independently navigate your interface.

The scale of this matters more than many developers appreciate. Roughly one in five people worldwide has some form of disability. Among your users, some rely entirely on keyboard navigation, some use screen readers like NVDA or JAWS or VoiceOver, and some depend on voice control software like Dragon NaturallySpeaking. Every one of these tools works better. often dramatically better. when your HTML uses semantic elements correctly.

There is also a legal dimension. WCAG 2.1 AA compliance is required by law in many jurisdictions under legislation like the Americans with Disabilities Act (ADA) and the European Accessibility Act. Accessibility audits that identify failures can trigger lawsuits. Teams that treat semantic HTML as a best practice rather than a compliance checkbox find that automated tools like Claude Code make staying compliant much less labor-intensive.

Using Claude Code to Audit Your HTML

Before improving, you need to understand your current state. Claude Code can read through your HTML files and identify areas needing attention. Here’s how to prompt it:

Review this HTML file for semantic correctness and accessibility issues.
Focus on:
1. Missing landmark regions (header, nav, main, footer)
2. Incorrect heading hierarchy (h1-h6)
3. Non-semantic div/spans that is semantic elements
4. Missing alt text on images
5. Improper use of button vs link

The frontend-design skill specializes in this type of analysis. It understands HTML5 semantic elements and WCAG guidelines, making it particularly effective at identifying structural issues.

Reading the Audit Output

A thorough Claude Code audit produces findings at multiple severity levels. Pay attention to this breakdown:

  • Errors are WCAG failures that will block users. A form input without a label is an error. screen reader users cannot determine what to type into that field.
  • Warnings are patterns that usually cause problems. An image without alt text is decorative, but it is not.
  • Suggestions are improvements that go beyond compliance into best practice. Using <article> instead of <section> for blog posts is a suggestion.

Fix errors first. They represent genuine barriers. Then work through warnings systematically. Leave suggestions for a dedicated improvement sprint.

Auditing an Entire Project

For large projects, prompt Claude Code to scan multiple files:

Audit all HTML files in ./src/components/ for accessibility issues.
For each file, report:
- File path
- List of issues with line numbers
- WCAG criterion violated
- Suggested fix
Summarize findings across all files at the end, sorted by issue frequency.

The summary view often reveals systemic problems. If forty-three components are all missing aria-label on icon buttons, that is a pattern to fix with a shared component rather than forty-three individual edits.

Practical Patterns for Semantic Improvement

Landmark Regions

Every page should include these landmark elements:

<header role="banner">
 <nav aria-label="Main navigation">
 <!-- Navigation links -->
 </nav>
</header>
<main id="main-content">
 <!-- Primary page content -->
</main>
<footer role="contentinfo">
 <!-- Footer content -->
</footer>

When Claude Code generates new pages, instruct it to include these landmarks by default. You can create a skill that enforces this pattern across your project.

Note that the role attributes on <header> and <footer> are redundant when those elements are direct children of <body>. HTML5 already implies those roles. They become useful when those elements appear inside an <article> or <section>, where the implicit roles change. Include them anyway as explicit documentation of intent.

The id="main-content" attribute on <main> is specifically for skip navigation links. Always pair it with a visible (or visually-hidden) skip link at the top of the page:

<a href="#main-content" class="skip-link">Skip to main content</a>

Without a skip link, keyboard users must tab through your entire header and navigation on every single page load. Adding two lines of HTML eliminates that friction entirely.

Heading Hierarchy

Headings create an outline that screen reader users navigate with keyboard shortcuts. Maintain a logical hierarchy:

<h1>Page Title</h1>
 <h2>Main Section</h2>
 <h3>Subsection</h3>
 <h3>Another Subsection</h3>
 <h2>Another Main Section</h2>

Never skip heading levels. A <h4> should follow a <h3>, not a <h2>. Claude Code can scan your content and report heading hierarchy violations across your entire site.

A common mistake is choosing heading levels based on visual size rather than semantic meaning. If your design requires large text inside a section that is logically an h4, style the h4 with CSS to appear larger. do not use h2 because it looks better by default. The heading level communicates document structure; CSS communicates visual presentation.

This also means you should have exactly one <h1> per page. That heading identifies the page’s primary topic. Multiple <h1> elements confuse the document outline and reduce SEO clarity.

This is a common mistake that affects keyboard navigation:

  • Use <button> for actions that don’t navigate (submit forms, open modals, toggle states)
  • Use <a href="..."> for navigation
<!-- Wrong -->
<a href="#" onclick="openModal()">Open Settings</a>
<!-- Correct -->
<button type="button" onclick="openModal()">Open Settings</button>

The distinction matters because buttons and links have different default behaviors and keyboard interactions. The frontend-design skill catches these distinctions during code review.

The differences run deeper than keyboard behavior. When a screen reader announces a link, it signals “this will take you somewhere.” When it announces a button, it signals “this will do something.” Users make navigation decisions based on these announcements. Misusing the elements breaks users’ mental model of your interface.

There is a third case worth knowing: when you need something that looks like a button but navigates to a URL, use <a href="..."> and style it to look like a button. Never use a <button> with JavaScript window.location to fake navigation. it breaks right-click behavior, middle-click, and any browser feature that depends on real links.

Form Accessibility

Forms are among the most critical accessibility areas because errors here directly prevent users from completing tasks. Every input needs a visible, associated label:

<!-- Wrong: placeholder is not a label -->
<input type="email" placeholder="Email address">
<!-- Wrong: label not associated -->
<label>Email address</label>
<input type="email">
<!-- Correct: explicit association -->
<label for="email">Email address</label>
<input type="email" id="email" name="email">
<!-- Also correct: implicit association via nesting -->
<label>
 Email address
 <input type="email" name="email">
</label>

Placeholder text disappears when a user starts typing. For users with memory difficulties, this is a serious problem. they cannot check what the field was asking for. Labels persist. Always use labels.

For required fields, use both the required attribute and a visible indicator:

<label for="name">
 Full name
 <span aria-hidden="true">*</span>
 <span class="sr-only">(required)</span>
</label>
<input type="text" id="name" name="name" required>

The aria-hidden="true" on the asterisk prevents screen readers from announcing the symbol. The visually-hidden span provides the same information in words instead.

Image Alt Text

Alt text requires judgment, not just presence. Claude Code can identify missing alt attributes, but writing good alt text is a content decision:

<!-- Decorative image: empty alt prevents announcement -->
<img src="decorative-divider.png" alt="">
<!-- Informative image: describe what the image conveys -->
<img src="chart-q4-revenue.png" alt="Q4 revenue chart showing 23% growth vs Q3">
<!-- Functional image (inside a link): describe the destination -->
<a href="/dashboard">
 <img src="dashboard-icon.png" alt="Dashboard">
</a>
<!-- Complex image: alt summarizes, longdesc or figcaption provides full description -->
<figure>
 <img src="org-chart.png" alt="Company organizational chart" aria-describedby="org-chart-desc">
 <figcaption id="org-chart-desc">
 The CEO reports to the Board. Three VPs report to the CEO: VP Engineering,
 VP Marketing, and VP Sales. Each VP manages teams of 5-15 people.
 </figcaption>
</figure>

The common mistake is writing alt text like a filename description (“image of a chart”) rather than conveying the content the image communicates (“Q4 revenue chart showing 23% growth vs Q3”). Ask: if this image were removed, what information would a sighted user lose? Your alt text should provide that information.

Integrating Accessibility into Your Workflow

The tdd skill pairs well with accessibility testing. Write tests that verify:

  • All images have alt attributes
  • Form inputs have associated labels
  • Interactive elements are keyboard accessible
  • Color contrast meets WCAG AA standards
// Example accessibility test pattern
test('all images have alt text', () => {
 const images = document.querySelectorAll('img');
 images.forEach(img => {
 expect(img.alt).toBeTruthy();
 });
});

Run these tests as part of your continuous integration pipeline. The pdf skill can generate accessibility audit reports in PDF format for stakeholders who need documentation.

Extend this pattern to cover landmark regions and heading hierarchy:

test('page has exactly one h1', () => {
 const h1s = document.querySelectorAll('h1');
 expect(h1s.length).toBe(1);
});
test('page has main landmark', () => {
 const main = document.querySelector('main');
 expect(main).not.toBeNull();
});
test('all buttons have accessible names', () => {
 const buttons = document.querySelectorAll('button');
 buttons.forEach(button => {
 const hasText = button.textContent.trim().length > 0;
 const hasAriaLabel = button.getAttribute('aria-label');
 const hasAriaLabelledBy = button.getAttribute('aria-labelledby');
 expect(hasText || hasAriaLabel || hasAriaLabelledBy).toBe(true);
 });
});

Consider adding axe-core or jest-axe to your test suite for broader automated coverage. These libraries check dozens of WCAG criteria automatically. Claude Code can help you write the test setup and interpret failures when they occur.

Automating Semantic Improvements

Create a Claude skill that enforces semantic standards:

---
name: semantic-audit
description: Audit HTML for semantic correctness and accessibility
---
When reviewing HTML files:
1. Verify landmark regions exist (header, nav, main, footer)
2. Check heading hierarchy follows logical order
3. Ensure buttons and links are used correctly
4. Verify all images have alt text
5. Check form inputs have labels
6. Verify interactive elements have accessible names
7. Check for skip navigation link
8. Confirm color is not the only means of conveying information
Report findings in this format:
- Severity (error/warning)
- Element and location
- Issue description
- Suggested fix
- WCAG criterion (e.g., "1.1.1 Non-text Content")

Run this skill before every deployment. Consistency prevents accessibility regressions from creeping into your codebase.

You can go further by creating a pre-commit hook that triggers this audit automatically:

#!/bin/sh
.git/hooks/pre-commit
Run accessibility audit on staged HTML files
staged_html=$(git diff --cached --name-only --diff-filter=ACM | grep '\.html$')
if [ -n "$staged_html" ]; then
 echo "Running accessibility audit on staged HTML files..."
 claude /semantic-audit --files="$staged_html"
 if [ $? -ne 0 ]; then
 echo "Accessibility audit failed. Fix issues before committing."
 exit 1
 fi
fi

This hook runs the audit only on staged HTML files, keeping the commit process fast while catching issues before they reach the repository.

WCAG Compliance Reference

WCAG 2.1 organizes accessibility requirements into four principles: Perceivable, Operable, Understandable, and Solid (POUR). Most semantic HTML improvements address multiple criteria simultaneously:

Semantic Practice WCAG Criterion Level
Images with alt text 1.1.1 Non-text Content A
Landmark regions 1.3.1 Info and Relationships A
Logical heading order 1.3.1 Info and Relationships A
Labels for form inputs 1.3.1 Info and Relationships A
Skip navigation link 2.4.1 Bypass Blocks A
Descriptive page title 2.4.2 Page Titled A
Link purpose from context 2.4.4 Link Purpose A
Language of page 3.1.1 Language of Page A
Buttons for actions 4.1.2 Name, Role, Value A
Color contrast 4.5:1 1.4.3 Contrast (Minimum) AA

Level A requirements are baseline. Most legal compliance frameworks require AA, which includes Level A. Start by ensuring all Level A requirements are met, then move to AA.

Real-World Results

Teams using Claude Code with accessibility-focused skills report significant improvements:

  • 40% reduction in accessibility audit findings
  • Faster implementation of WCAG compliance
  • Consistent semantic patterns across large codebases
  • Automated detection of common mistakes

The key is making accessibility part of your development workflow rather than an afterthought. Claude Code handles the repetitive checking, freeing you to focus on complex accessibility challenges.

One practical pattern that teams find effective: create a dedicated accessibility review step in your pull request process. Instruct Claude Code to audit every PR’s HTML changes before merge. This catches regressions immediately, when the change is still fresh in the developer’s mind, rather than surfacing them in a quarterly audit when the original author may have moved on.

Next Steps

Start by auditing your current codebase. Use Claude Code with the frontend-design skill to identify low-hanging fruit. missing landmarks, heading issues, button/link confusion. Fix these first, then establish patterns that prevent future issues.

Prioritize your fixes in this order: forms first (accessibility failures here directly prevent task completion), then landmark regions (they affect navigation for every page), then heading hierarchy, then image alt text, then button semantics. This ordering gets the highest-impact improvements deployed earliest.

Accessibility isn’t a destination but an ongoing commitment. With Claude Code assisting your workflow, maintaining semantic, accessible HTML becomes sustainable even on large projects.

Level Up Your Claude Code Workflow

The developers who get the most out of Claude Code aren’t just fixing errors — they’re running multi-agent pipelines, using battle-tested CLAUDE.md templates, and shipping with production-grade operating principles.

I'm a solo developer in Vietnam. 50K Chrome extension users. $500K+ on Upwork. 5 Claude Max subscriptions running agent fleets in parallel. These are my actual CLAUDE.md templates, orchestration configs, and prompts. Not a course. Not theory. The files I copy into every project before I write a line of code. **[See what's inside →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-default&utm_campaign=claude-code-semantic-html-accessibility-improvement-guide)** $99 once. Free forever. 47/500 founding spots left.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Related Reading

Built by theluckystrike. More at zovo.one

Find the right skill → Browse 155+ skills in our Skill Finder.