Claude Skills Guide

Claude Code Semantic HTML Accessibility Improvement Guide

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.

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 could be 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.

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.

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.

This is a common mistake that affects keyboard 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.

Integrating Accessibility into Your Workflow

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

// 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.

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

Report findings in this format:
- Severity (error/warning)
- Element and location
- Issue description
- Suggested fix

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

Real-World Results

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

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.

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.

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.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides