Semantic HTML
debt(d5/e3/b5/t7)
Closest to 'specialist tool catches it' (d5). The detection_hints list Lighthouse, axe, and WAVE — all specialist accessibility/audit tools that flag missing landmark elements and semantic structure issues. These are not default linters but purpose-built tools a developer must consciously run, so this sits at d5 rather than d3.
Closest to 'simple parameterised fix' (e3). The quick_fix describes replacing generic <div>/<span> with semantic elements — a mechanical substitution pattern. It's more than a single-line patch (it may span the HTML template) but is a straightforward find-and-replace within one component or template file, not a cross-cutting refactor.
Closest to 'persistent productivity tax' (b5). Semantic HTML applies broadly across all web contexts (applies_to: web) and touches accessibility, SEO, and maintainability tags. A codebase built entirely on divs requires ongoing attention as every new feature must also avoid semantic elements — it slows multiple work streams (accessibility reviews, SEO audits, screen-reader testing) without being fully architectural.
Closest to 'serious trap' (t7). The misconception field explicitly states that developers believe semantic elements are 'just visual styling hints' — meaning they think divs are functionally equivalent. This contradicts how many devs reason about HTML (if it looks right, it is right), and the gap between appearance and structural meaning is non-obvious. This is a documented, widespread wrong mental model that contradicts cross-domain expectations, placing it at t7.
Also Known As
TL;DR
Explanation
Semantic HTML uses elements that communicate meaning to browsers, screen readers, and search engines rather than just controlling visual presentation. Structural: <header>, <main>, <footer>, <nav>, <aside>, <section>, <article>. Inline: <time datetime='2024-01-15'>, <address>, <abbr>, <cite>, <mark>, <del>, <ins>. Forms: <label for='id'> correctly associates labels; <fieldset> and <legend> group related inputs. Headings (h1–h6) create a document outline. Benefits: screen readers use landmark roles from semantic elements for navigation (jumping to main content); search engines weight heading and article content higher; developers understand intent without reading CSS class names. Avoid <div> and <span> soup — reach for the right element first.
Common Misconception
Why It Matters
Common Mistakes
- Using div for everything instead of semantic elements — screen readers and search engines lose structure.
- Using heading levels for visual styling rather than document hierarchy — h3 because 'it looks right'.
- Not using nav for navigation, main for primary content, or aside for secondary content.
- Nesting block elements inside inline elements — invalid HTML that breaks rendering.
Code Examples
<div class="header">
<div class="nav">
<div class="nav-item"><a href="/">Home</a></div>
</div>
</div>
<div class="content">
<div class="article">
<div class="article-title">My Post</div>
</div>
</div><header>
<nav>
<ul>
<li><a href="/">Home</a></li>
</ul>
</nav>
</header>
<main>
<article>
<h1>My Post</h1>
<time datetime="2024-03-01">1 March 2024</time>
</article>
</main>