d5DetectabilityOperational debt — how invisible misuse is to your safety net
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.
e3EffortRemediation debt — work required to fix once spotted
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.
b5BurdenStructural debt — long-term weight of choosing wrong
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.
t7TrapCognitive debt — how counter-intuitive correct behaviour is
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.
About DEBT scoring →
scored by claude-sonnet-4-6 · 2026-05-08 · reviewed by human
Also Known As
semantic HTMLsemantic elementsHTML5 semantics
TL;DR
Using HTML elements for their intended meaning — <article>, <nav>, <main>, <time> — improving accessibility, SEO, and code clarity.
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
✗ Semantic HTML elements are just visual styling hints for browsers. Semantic elements (header, nav, main, article, section) carry meaning for screen readers, search engine crawlers, and browser reader modes — they provide structural accessibility information that div and span cannot convey.
Why It Matters
Semantic HTML elements (header, nav, main, article, section, footer) communicate page structure to browsers, search engines, and assistive technology — divs communicate nothing.
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
💡 Note
Screen readers announce landmarks — <nav>, <main>, <aside> — letting users jump directly to content. Divs are anonymous; they convey nothing.
🧱FUNDAMENTALS— new to this? Start with the ground floor.
CSSfrontendThe language that styles web pages: rules match HTML elements with selectors and apply declarations like color, size, spacing, and layout.
Most "CSS is fighting me" moments are really the cascade working as designed — a more specific selector elsewhere is winning. Understanding specificity turns debugging from guesswork (!important everywhere) into reading.
💡 When a style refuses to apply, open DevTools → Styles panel: the crossed-out rule shows you exactly which selector is beating yours.
ElementfrontendAn element is a single building block of a webpage, created by an HTML tag that defines a piece of content or structure like a paragraph, image, or button.
Everything visible on a webpage is an element. Understanding elements is the foundation for writing HTML, styling with CSS, and manipulating pages with JavaScript.
💡 Every opening tag needs a matching closing tag unless it's explicitly self-closing like img, br, or input.
FrontendfrontendThe frontend is the part of a website or application that users see and interact with directly in their browser—buttons, text, images, and forms.
Every user interaction starts at the frontend. Understanding this layer helps you build interfaces people actually want to use and debug issues that only appear in the browser.
💡 If you can see it or click it, it's frontend; if it stores data or makes decisions you shouldn't expose, that belongs on the backend.
HTMLfrontendThe markup language that defines the structure and meaning of web content — elements like <h1>, <p>, and <form> wrapped in angle-bracket tags.
HTML is the skeleton every other web technology hangs on. Using the right element gives you keyboard support, screen-reader announcements, and SEO for free; using <div> for everything means rebuilding all of that by hand in JavaScript.
💡 Before reaching for a <div>, ask: is there an element whose NAME says what this is? There usually is.
Replace generic <div> and <span> with semantic elements: <nav>, <main>, <article>, <section>, <aside>, <header>, <footer> — one change that improves accessibility, SEO, and readability
