Semantic HTML: why div soup costs you machine readability

A div means nothing. That is not a criticism, it is the specification: it is a generic container, defined as having no semantics at all. A nav means this is navigation. A table means these cells relate to those headers. The name is metadata that travels with the content for free.

Which is why the difference only shows up when something tries to consume the page programmatically. A browser needs no help drawing boxes. A screen reader building a landmark list, a reader-mode extracting an article, or a retrieval pipeline deciding which part of the document is content rather than chrome, all need to know what the boxes are.

You do not need to re-architect a codebase. In practice five swaps cover the majority of the gap, and none of them changes a single pixel once your existing classes come along for the ride.

<div class="page">
  <div class="top">
    <div class="logo">Acme</div>
    <div class="links">
      <div class="link"><a href="/docs">Docs</a></div>
      <div class="link"><a href="/pricing">Pricing</a></div>
    </div>
  </div>

  <div class="content">
    <div class="title">Choosing a widget</div>
    <div class="para">Three things matter.</div>
    <div class="items">
      <div class="item">Bore diameter</div>
      <div class="item">Pressure rating</div>
    </div>
  </div>

  <div class="bottom">© Acme</div>
</div>

<!-- Same classes, same CSS, same rendering.
     Every element now says what it is. -->
<header class="top">
  <div class="logo">Acme</div>
  <nav class="links" aria-label="Main">
    <ul>
      <li class="link"><a href="/docs">Docs</a></li>
      <li class="link"><a href="/pricing">Pricing</a></li>
    </ul>
  </nav>
</header>

<main class="content">
  <article>
    <h1 class="title">Choosing a widget</h1>
    <p class="para">Three things matter.</p>
    <ul class="items">
      <li class="item">Bore diameter</li>
      <li class="item">Pressure rating</li>
    </ul>
  </article>
</main>

<footer class="bottom">© Acme</footer>

The five: a container becomes header, main or footer when that is what it is; a group of links becomes nav wrapping a ul; a repeated set of siblings becomes a list; a styled title becomes a heading; and a paragraph of prose becomes a p. Note that mainshould appear once, and that a list restores the "2 of 5" announcement a screen reader gives, which a stack of divs cannot.

Most of this defect is not authored by hand, it is inherited. A design system component named Stack or Box renders a div by definition, and a page assembled entirely from primitives is a page with no semantics regardless of how careful the author was.

The pattern that fixes it at the root is an escape hatch on the primitive rather than a rule for authors to remember:

// One prop turns a layout primitive into whatever the
// content actually is. Default stays a div, so nothing
// existing changes, and correctness becomes available
// instead of forbidden.
export function Stack({ as: Tag = 'div', gap = 4, children, ...rest }) {
  return (
    <Tag className={`flex flex-col gap-${gap}`} {...rest}>
      {children}
    </Tag>
  )
}

// <Stack as="nav" aria-label="Main">…</Stack>
// <Stack as="ul">…</Stack>

Headless component libraries are the other common source, and they usually get this right: a listbox or a menu emits the roles it needs. The gap is almost always the layout layer, not the interactive one.

Because the content is present and readable. A model fetching a page of div soup still gets all of your text; what it loses is the map, so it has to infer structure from formatting rather than read it from the markup. Inference degrades quality, it does not prevent it.

The reason it is not Refinement is that there is a named group of people for whom this is not a degradation at all. A screen reader user on a page with no landmarks and no lists has lost the ability to navigate it, which is a present, concrete harm rather than a hypothetical ranking cost. The scale treats that as Important on its own, before any search argument is added.

Open the accessibility tree and look for the landmark list. You want to see banner, navigation, main and contentinfo, in that order, with your content inside main. That view is the derived outline from the diagram at the top of this page, which is the thing consumers of your markup actually receive.

Then re-crawl for the aggregate, since the useful answer is which templates are still generic rather than whether one page is fixed. Expect the ratio to move template by template: this defect lives in layout components, so one edit tends to fix a whole section of the site at once.