Accessible content
Writing links, labels, alt text and instructions that work with assistive technology.
Content must support assistive technologies and be perceivable, operable, understandable, and robust, regardless of how the interface is being accessed.
Write as if visuals don't exist
Content must be self-sufficient. It should not rely on icons, colours, images, or layout position to convey meaning. An agent using a screen reader, or someone who cannot see the interface clearly, must still understand the content.
Avoid directional and positional language. Organise content chronologically (first, next, finally) not spatially (above, below, left, right).
| Avoid | Prefer |
|---|---|
| Above | First, previously |
| Below | Next, following |
| On the left | In the menu bar |
| At the bottom | Finally |
Do
Go to Billing history to review past payments.
Don't
See the table on the left for past payments.
Do not reference visual appearance. Use the control's label name, not its appearance or colour.
| Avoid | Prefer |
|---|---|
| Click the green button | Select Submit payment |
| The red outline | Add error message text alongside the colour |
Do not rely on colour or icons alone to communicate state. Always support colour with text or an additional indicator.
Prefer "View", "Show", or "Go to" over "See". Not everyone is seeing the content.
Do
View all results
Don't
See all results
Links and buttons
Link and button text must be descriptive on its own. A screen reader user may encounter it without the surrounding context.
Every call to action on a page must be unique. Where the same label is unavoidable (for example, multiple Edit buttons in a list), append hidden distinguishing text so each reads as unique to assistive technology.
Provide keywords before or inside links rather than after them, so the user understands the destination before selecting it.
If a link opens in a new tab or downloads a file, indicate this in the link text or with an adjacent icon with appropriate alt text.
Do
View payment history
Download payment summary (PDF)
Don't
Click here
Learn more
Form labels
Form labels must be explicit and persistent. Do not use placeholder text as a label, it disappears on input and is not reliably read by assistive technologies.
Alt text
Alt text should be:
- Additive, add context that would be lost without the image; do not repeat text already present nearby
- Active voice, written directly and concisely
- Brief, screen readers listen at fast speeds; be as short as possible while remaining meaningful
- Consistent, use the same alt text if the same image appears in multiple places
- Empty (alt=""), for purely decorative images, dividers, empty-state illustrations, or images with adequate surrounding captions
Do not begin with "image of" or "picture of", screen readers already identify the element as an image.
Do not include punctuation like !! or emoji in alt text, screen readers announce these verbosely.
For interactive icons, describe the action the control performs, not the visual appearance of the icon.
Do
accessibilityLabel="Search"
Don't
accessibilityLabel="Magnifying glass"
Do
accessibilityLabel="Send message"
Don't
accessibilityLabel="Paper aeroplane icon"
Images with an adequate caption that already describes the content do not need separate alt text. If the image conveys additional information not in the caption, add that to the alt text rather than writing a full description.