Skip to content

Evidence — dialog titles no longer skip heading levels (issue #318)

Seven dialogs titled themselves with a bare <h5 class="modal-title"> / <h5 class="offcanvas-title">, so anyone navigating by heading met a level-5 heading as the dialog's title — on pages that run h1 → h2, a two-level jump (against WCAG best practice and axe's heading-order rule). Six other dialogs already used the correct <h2 class="…-title h5"> form, so the theme contradicted itself half the time. The fix makes all seven match; the .h5 utility reproduces the exact sizing, so the change is deliberately visually inert.

Generated by test/visual/dialog-heading-levels-evidence.mjs against the live dev server. For each of the six live dialogs it opens the dialog, records the heading walk (previous heading in DOM order → dialog title) and the header render in the fixed state, then reproduces the pre-fix state by reverting exactly the diff in the live DOM (<h2 class="…-title h5"> → <h5 class="…-title">, same attributes and children) and records both again. The seventh fixed file, _includes/components/background-customizer.html, is an unrendered include (no page includes it) — fixed for consistency and covered by the markup change itself, not by a screenshot.

  • 01-modals-before-after.png — #siteSearchModal, #cookieSettingsModal, #helpModal: heading walk h2 → h5 (skips 2) becomes h2 → h2; renders byte-identical.
  • 02-offcanvas-before-after.png — #info-section, #sectionSidebar, #adminSidebar: same contract for the offcanvas dialogs.
  • metrics.json — per dialog: before/after heading walk, computed font-size/weight (unchanged 20px/500), and screenshot byte-equality (pixelIdentical: true for all six).

Why axe alone could not prove this: heading-order is a best-practice rule excluded by the suite's wcag2a/wcag2aa tag filter, the dialogs are closed on load so axe never evaluates their headings, and axe never flags a document's first heading — #siteSearchModal and #info-section render theirs ahead of the content. The regression test in test/visual/core/accessibility.spec.js therefore asserts the <h2 class="…-title h5"> contract directly on every dialog, with axe as a second opinion where it can see the walk.