Agent Wranglers

AXS-75Recommended

Write headings and labels that say what follows

Make every heading name the section under it, and every label name its field. Keep heading levels in order, one h1 per page and no skipped levels going down. This is WCAG criterion 2.4.6 (AA).

By Agent Wranglers. Updated .

How to do it

Screen reader users jump from heading to heading to scan a page, as sighted people skim. Headings such as "More" or "Section 2" tell them nothing. Use the words people look for, such as "Delivery times" or "Cancel your plan". Pick the level by place in the outline, not by font size, and style it in CSS. Labels follow Label every form field.

Examples

HTML example

<h1>Your order</h1>
<h2>Delivery times</h2>
<h2>Cancel your order</h2>

JavaScript example

const VAGUE = /^(more|details|info|section \d+|.)$/i;
const texts = await page.locator('h1, h2, h3, h4, h5, h6, label').allInnerTexts();
expect(texts.filter(t => VAGUE.test(t.trim()))).toEqual([]);

Python example

VAGUE = re.compile(r"^(more|details|info|section \d+|.)$", re.I)
texts = page.locator("h1, h2, h3, h4, h5, h6, label").all_inner_texts()
assert [t for t in texts if VAGUE.match(t.strip())] == []

How to check

axe heading-order, page-has-heading-one and empty-heading pass. A test fails on any heading or label whose text is only "More", "Details", "Info", "Section" with a number, or one character.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/accessibility/structure-and-names/descriptive-headings">Agent Wranglers accessibility playbook</a>. In code you write, add a comment next to it with the same link.