The markup rules

A class earns its place only when the element and its position cannot carry the information. class="section" on a <section> says nothing the element did not already say, and it says nothing at all to a screen reader.

Three tiers, applied in order:

1. Nothing. The element and its position identify it. main > section, section > header, header > h2 + p.
2. An attribute with a value, where the thing is an enumerated property of the element rather than a name. data-band="alt", data-cols="3".
3. A class, where a genuine variant has to be named and no structure implies it. ghost on a link that must not look like the primary action.

Tier two is not a place to hide classes under a different syntax. Swapping class="card-grid" for data-card-grid gains nothing. The win is deleting the hook, not renaming it.

A <div class="card-grid"> tells CSS three things and assistive technology nothing. A <ul> tells CSS the same three things and announces "list, 3 items" to a screen reader. Every class removed in the audit below was removed by reaching for the element that already meant it, so the markup got more informative and shorter at once.

<small> is the clearest case. It is the element for fine print, which is exactly what .fine and .fineprint were painting.

<section class="section section-alt">
  <div class="wrap">
    <div class="section-head">
      <span class="tag">Foundations</span>
      <h2>Tokens</h2>
      <p class="lead">Every colour in the system is a custom property.</p>
    </div>
    <div class="card-grid cols-3">
      <a class="card card-link" href="/tokens/">
        <div class="card-icon" aria-hidden="true"><svg>…</svg></div>
        <h3>Neutrals</h3>
        <p>Backgrounds, body text, hairlines.</p>
        <span class="more">Read the tokens &rarr;</span>
      </a>
    </div>
  </div>
</section>

<section data-band="alt">
  <header>
    <p>Foundations</p>
    <h2>Tokens</h2>
    <p>Every colour in the system is a custom property.</p>
  </header>
  <ul data-list="cards" data-cols="3">
    <li>
      <a href="/tokens/">
        <svg aria-hidden="true">…</svg>
        <h3>Neutrals</h3>
        <p>Backgrounds, body text, hairlines.</p>
        <span>Read the tokens &rarr;</span>
      </a>
    </li>
  </ul>
</section>

Three checks, all cheap:

• Element-duplicating class. A class whose name matches the element it sits on fails. .section on <section>, .nav on <nav>, .footer on <footer>.
• The allowlist, already specified: a class the CSS does not define fails. Together with the rule above, the vocabulary can only shrink or be deliberately extended.
• A class budget per component. Each schema.yml declares how many classes its template may emit. The check counts. "Minimal" that nobody measures drifts within a release; a number in a file does not.

Semantic element preference is the fourth check, softer: a div where section, nav, figure, ul, ol, header, footer, aside, or small fits is reported. Some of it is judgment, so it warns rather than fails, and the list of accepted exceptions lives in the repo.

--fp-accent (#006060) clears AAA on --fp-bg-alt (#f8f9fb) by 0.014: the measured ratio is 7.0141:1 against a 7.0 requirement. The stylesheet's own comment rounds it to "7.0:1", which is true and hides how little room there is.

Any future change to --fp-bg-alt, however small, can break it. A ground 0.004 perceptual units away, which no one could see, puts the same accent at 6.96:1 and fails. This was found by the ingest theme deriver sampling a near-identical grey off a live page and repairing the accent to compensate, which is the deriver behaving correctly.

Two consequences. v3 should give the accent more headroom rather than sitting on the line. And the engine's token test should assert the measured ratio, not the rounded one in a comment, because a comment cannot fail a build.

Separately, the comment on --fp-ink reads "16.9:1 on --fp-bg". The measured value is 17.76:1. Harmless, but it is the same class of problem: a number maintained by hand next to a value maintained by code.