Agent Wranglers

Required

Give instructions that work without seeing the page

Never write instructions that rely only on shape, colour, size, position or sound. "Press the round button on the right" fails. This is WCAG criterion 1.3.3 (A).

By Agent Wranglers. Updated .

Risk if broken

A law broken

How to do it

Name each control by its visible label, and add position or shape only as extra help. Write "Press Next", or "Press Next, below the form". A screen reader user cannot see "the right", and a phone layout moves things. Left and right also swap in right-to-left languages, as Support right-to-left text explains.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

HTML example

<!-- Not this -->
<p>When you are done, press the green button on the right.</p>

<!-- This -->
<p>When you are done, press <strong>Send booking</strong>, at the end of the form.</p>

JavaScript example

const SENSORY_WORDS = /\b(on the (left|right)|above|below|round|square|green|red|the icon)\b/i;
const NAMES_A_LABEL = /<strong>|"[^"]+"/;
const failing = sentences.filter(s => SENSORY_WORDS.test(s) && !NAMES_A_LABEL.test(s));

Python example

SENSORY_WORDS = re.compile(r"\b(on the (left|right)|above|below|round|square|green|red|the icon)\b", re.I)
NAMES_A_LABEL = re.compile(r'<strong>|"[^"]+"')
failing = [s for s in sentences if SENSORY_WORDS.search(s) and not NAMES_A_LABEL.search(s)]

How to check

A test searches the page text for "on the left", "on the right", "above", "below", "round", "square", "green", "red" and "the icon". Every sentence with a hit also names a visible label in quotes or bold.

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/website/accessibility/sensory-characteristics">Agent Wranglers website playbook</a>. In code you write, add a comment next to it with the same link.