Claude Skills Guide

Claude Code Semantic HTML Improvement Guide

Many codebases accumulate <div> soup over time — wrappers, containers, and sections that could all be expressed with purpose-built HTML elements. Claude Code offers practical workflows to audit and refactor that structural debt, whether you’re working on a new project or cleaning up legacy markup.

This guide covers the structural side of semantic HTML: replacing generic containers, fixing heading hierarchies, using advanced elements like <details> and <figure>, and integrating audits into your development workflow. For accessibility-specific concerns — WCAG compliance, ARIA, screen reader testing — see the Semantic HTML Accessibility Guide.

Why Semantic HTML Matters

Search engines rely on semantic markup to understand page content. When you use <article> instead of <div>, you signal that content stands independently. When you use <nav>, crawlers recognize navigation regions without needing to infer from class names.

Beyond SEO, semantic HTML improves maintainability. Code becomes self-documenting when elements communicate their purpose through tag names rather than classes like header-section or content-wrapper. Developers reading the codebase later understand intent without hunting through stylesheets.

Using Claude Code to Audit HTML Structure

Before improving semantics, you need a clear picture of your current markup. Claude Code can analyze your HTML files and identify areas needing attention.

Create a skill that focuses on HTML auditing, or use Claude Code directly to examine your files:

Analyze the semantic HTML structure in this file. Identify:
1. Divs that could be replaced with semantic elements (article, section, nav, aside, main)
2. Missing landmark roles
3. Heading hierarchy issues (skipped levels, multiple h1s)
4. Lists that should use ul/ol/li
5. Buttons styled as links or vice versa

This analysis reveals patterns across your codebase. Many projects show the same recurring issues—developers reaching for <div> when more specific elements exist.

Refactoring Patterns for Better Semantics

Once you identify problems, systematic refactoring improves markup quality. Claude Code excels at mechanical transformations that follow consistent rules.

Replacing Generic Containers

The most common issue involves <div> elements used for structural purposes. Convert these to semantic equivalents:

When refactoring, preserve any existing classes or IDs. Semantic elements accept the same attributes as <div>, so the transformation is purely structural:

<!-- Before -->
<div class="sidebar">
  <div class="widget">...</div>
</div>

<!-- After -->
<aside class="sidebar">
  <div class="widget">...</div>
</aside>

Fixing Heading Hierarchy

Heading levels must follow logical sequence. Skipping from <h1> to <h3> confuses screen reader users who navigate by headings. Claude Code can renumber headings while preserving visual styling:

<!-- Before -->
<h1 class="page-title">Main Title</h1>
<div class="subtitle">Subtitle text</div>
<h3 class="section-header">Section One</h3>

<!-- After -->
<h1 class="page-title">Main Title</h1>
<p class="subtitle">Subtitle text</p>
<h2 class="section-header">Section One</h2>

The frontend-design skill provides additional context for heading decisions in component-based architectures where heading levels must reset within sections.

Integrating HTML Improvements into Development Workflow

Semantic improvements work best when integrated into your regular workflow rather than addressed in large refactoring sessions.

Pre-Commit Analysis

Add HTML semantic audits to your pre-commit checks. Create a Claude skill that validates semantic structure before code reaches the repository. This prevents semantic debt from accumulating in the first place.

Documentation Generation

When improving semantics, document the changes. The supermemory skill helps maintain a searchable knowledge base of semantic patterns used across your projects. Link semantic decisions to accessibility requirements and browser behavior.

Testing Accessibility

Combine semantic improvements with automated testing. The tdd skill works well for accessibility test suites that verify:

Working with Generated Content

Claude Code frequently generates HTML when building documentation, email templates, or marketing pages. Review this output for semantic quality rather than accepting it blindly.

Generated content often defaults to <div> for flexibility, but you can guide Claude toward better choices:

Create a pricing table section. Use semantic table elements (table, caption, th, td, tr) rather than divs. Include proper scope attributes on header cells. Use section for the overall container and h2 for the section title.

This specificity produces cleaner output that requires less manual refinement.

Advanced Semantic Patterns

Once you master basic semantic elements, consider advanced patterns that further improve structure.

The Details and Summary Elements

These elements create native accordions without JavaScript:

<details>
  <summary>Click to expand</summary>
  <p>Hidden content revealed on interaction.</p>
</details>

Claude Code can identify JavaScript accordions that could use this simpler approach.

Figure and Figcaption

Images with captions deserve <figure> and <figcaption>:

<figure>
  <img src="chart.png" alt="Sales growth chart">
  <figcaption>Figure 1: Quarterly revenue growth 2024-2025</figcaption>
</figure>

The alt text becomes unnecessary when figcaption provides context, since screen readers announce both.

Time and Data Elements

Machine-readable content benefits from semantic time marking:

<time datetime="2026-03-14">March 14, 2026</time>
<data value="42">Forty-two</data>

These elements aid date parsing and localization.

Maintaining Semantic Quality

Improvement requires ongoing attention. Establish conventions your team follows:

  1. Default to semantic elements—divs should be the exception, not the default
  2. Use ARIA roles only when native HTML cannot express the semantics
  3. Validate HTML in code review using automated tools
  4. Document semantic patterns in your component library

The pdf skill can generate accessibility documentation from your HTML audits, creating reports your team references during development.

Conclusion

Semantic HTML improvement with Claude Code combines systematic analysis with targeted refactoring. Audit your markup regularly, fix heading hierarchies, replace generic containers with semantic elements, and integrate these checks into your development workflow.

Good semantics pay dividends in accessibility, SEO, and maintainability. Start with a single file, establish patterns, and expand the practice across your projects.

Built by theluckystrike — More at zovo.one

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides