Accessibility basics

An accessible website is one that works for people using a keyboard instead of a mouse, a screen reader instead of a screen, or simply a phone in bright sunlight. Most of it is ordinary good practice that also makes your site clearer for everyone.

ClickWhale handles some of this for you. The rest is in the content you write.

What ClickWhale already does

You don't have to arrange any of this:

• The page declares its language, taken from the page's own language. Screen readers use it to choose a pronunciation, so a Dutch page is read in Dutch.
• Links that open in a new window say so, with a note that only screen readers hear. This applies to buttons, images, clickable columns and clickable grid cells.
• The cookie dialog, the mobile menu and the gallery's enlarge view are keyboard-operable. Opening one moves focus into it, Tab and Shift+Tab stay inside it rather than wandering off behind it, Escape closes it, and focus returns to whatever you opened it from. Escape on the cookie dialog counts as rejecting everything, which is the privacy-safe answer.
• Tab bars are a real tabs control. The row of labels is one Tab stop, arrow keys move along it, Home and End jump to the ends, and Enter or Space opens a tab. Screen readers are told which tab is selected and which panel it controls.
• Form errors are announced, not just shown in red.
• Decorative icons are hidden from screen readers, so a menu isn't read out as a stream of icon names.
• Scroll animations respect the visitor's reduced-motion setting. Someone who has asked their device for less movement gets less movement, without you doing anything.

What's up to you

1. Alt text on images

Alt text is the sentence a screen reader says in place of a picture, and what a browser shows if the image fails to load.

The Image element has no alt text. There is no field for it, and it renders no alt attribute.

Where alt text does exist is the photo slider and the photo gallery, through Edit metadata on the selected element. Both also have a Description, which renders as a visible caption under the image.

So, practically:

• For a picture that carries meaning (a product, a person, a diagram, a photo you'd describe to someone on the phone) use a photo slider or a photo gallery, even for a single image, so it can have alt text.
• For a picture that's purely decorative (a background texture, a divider) the Image element is fine. Decorative images are supposed to have empty alt text anyway.
• Never put text you need people to read inside an image. Nobody can select it, search it, translate it or hear it. Put it in a Text element over a background image instead.

Writing good alt text: describe what matters about the picture in a sentence, in context. Not "image", "photo", or the file name. If the image is a link, describe where the link goes rather than what the picture shows.

2. Heading order

Headings are how a screen-reader user skims a page. Most will pull up a list of them and jump. That only works if they describe the structure.

• One H1 per page, and it should say what the page is about.
• Don't skip levels. H2 under H1, H3 under H2. An H3 directly under an H1 reads as a missing section.
• Never pick a heading level for its size. Choose the level that's structurally right, then style it. That's what display sets are for. See Reusable styling.

The text editor offers heading levels 1 to 4, plus paragraph. See Writing and formatting text.

3. Colour contrast

Text needs to stand out from what's behind it. The usual target is a contrast ratio of 4.5:1 for body text and 3:1 for large text (roughly 24px, or 19px bold).

• Mid-grey text on white is the most common failure.
• Don't use colour as the only signal. A link that's only distinguishable by being blue is invisible to someone who can't see the difference: underlines, weight or an icon carry it too.
• Check your dark mode separately if you have one. It's a completely different set of colours, and an unset dark colour renders as white. See Dark mode.

Any free online contrast checker will take two hex values and tell you the ratio. Your colours are in Design → Colours. See The colour palette.

4. Link and button text

The text of a link should make sense read on its own, because that's how it will be encountered.

This matters most for the read-more buttons on a blog overview, where a screen reader user hears "read more, read more, read more". The button text is yours to change. See Adding a blog to your website.

5. Forms

• Every field needs a label, and ClickWhale gives each one a label field. Fill it in rather than relying on a placeholder.
• Say what's required in the label rather than only marking it with a colour or a star.
• Keep it short. Every field is work for everyone, and more so for someone using a switch or voice control.

See Creating a form.

6. Video

• Captions matter more than anything else on this list for video, and they're supplied by the video itself. Add them on YouTube, or burn them into a file before uploading.
• Don't autoplay with sound. Browsers block it anyway, which is why autoplay forces muting.
• Don't rely on a video to convey something essential without the same information in text nearby.

See Putting a video on a page.

Checking a page

1. Put your mouse away. Press Tab from the top of the page. Can you reach every link, button and form field, and can you always see where you are?
2. Open the mobile menu and the cookie dialog with the keyboard. Does Escape close them?
3. Look at the page in bright light, or turn your screen brightness down. Is any text hard to read?
4. Read the link texts aloud, out of context. Do they still mean anything?
5. Check the headings are in order: no skipped levels, one H1.
6. Ask whether any picture on the page carries information that isn't also in the text.

Common issues