Text and markup
| Anchor | What it gives | When it stops working |
|---|---|---|
An h2, h3 heading |
a table of contents inside the page: people scan it “layer cake” style | the heading names a topic, not the point: “Description”, “Other” (Headings say what’s inside) |
| The first words of a line | the eye takes about 11 characters of a list item | the line starts with “In order to”, “In case of”, “Also” (Key word first) |
| A step number | order and place: “I’m on step 3 of 6” | numbering on a list with no order — the reader looks for why |
| Bold | one or two spots per screen that mustn’t be missed | every other sentence in bold (Bold: one or two spots) |
| Numbers | as digits, not words: “14 days”, 3:00, 4.5:1 — the eye catches them even mid-paragraph |
“fourteen days”, “at three in the morning” |
| Inline code | monospace with a background: /srv/backup, docker compose stop — it’s clear this is to be copied |
ordinary words styled as code for looks |
| A link | color and underline — “you can go here” | non-links highlighted in the same color; link text “here” (Link text) |
Blocks
| Anchor | What it gives | When it stops working |
|---|---|---|
| A table | the comparison is visible before reading: rows are things, columns attributes | a one-column table, or one standing in for two sentences |
| A code block | a boundary: inside is what gets copied and run | a command and its output in one block with no marking of which is which |
| A diagram | a path through several links at a glance | arrows without labels; the diagram doesn’t fit on a screen |
| A tag, a format badge | what kind of page it is, before the heading: “Manual”, “Tip” | the tags have no stable meaning: one color means different things |
| A warning | the one thing without which something breaks | five “Important” panels per page — they get skipped, like ads |
| An illustration, a shelf icon | a recognizable place: “I’m on the Docker shelf” | an illustration in every section, unrelated to the text |
| A screenshot | where to click in an interface | a screenshot of code, or of a whole screen without annotation (Code as text) |
Rules for every anchor
| Rule | Why |
|---|---|
| An anchor means the same thing across the page | bold means “important” here and “term” there — the reader stops understanding either |
| One strong anchor per block of meaning is enough | two neighbouring anchors compete, and the eye stops between them |
| An anchor differs from its surroundings in at least one way: size, weight, color, background | a half-tone difference doesn’t show while scanning |
| Color isn’t the only signal | among people of European descent about 8% of men and 0.5% of women distinguish colors less well; WCAG 1.4.1 requires a second signal — an underline, an icon, text |
| What looks like an ad gets skipped | banner blindness: the eye goes around bright frames and panels at the page edge even when what you need is there |
If it doesn’t work
The eye jumps around the page and stops on nothing
- Cause
- There are more anchors than text: bold, color, icons and panels in every paragraph.
- Fix
- Keep one strong anchor per block of meaning: a heading, or a tag, or a number.
Links and important words share one color
- Cause
- The anchor means two things at once — the reader clicks a highlighted word and finds no link.
- Fix
- Color and underline for links only; important things in bold, without color.
Items have icons, but people still confuse them
- Cause
- The icons are decorative and alike: a gear, a star, a check mark — without a label their meaning gets guessed.
- Fix
- An icon goes next to a label and is the same for the same thing across the page; one without meaning gets removed.