Aller au contenu

Accessible images and media

Images, videos, and audio enrich your content -- but only if everyone can access the information they carry. A screen reader cannot see a photo. A deaf user cannot hear a video's dialogue. An animation can trigger a seizure.

Two guiding principles:

  1. Every piece of visual information needs a text equivalent. If the image communicates something, describe it. If it doesn't, mark it as decorative.
  2. Give users control over media playback. No autoplay with sound, no flashing content, and always provide pause controls.

Alt text for images

The alt attribute provides a text description of an image. Screen readers announce it, search engines index it, and browsers display it when the image fails to load.

To set alt text in Silex:

  1. Select the image
  2. In the Element settings (gear icon), find the alt field
  3. Write a short, descriptive phrase

Writing good alt text

Describe what the image communicates, not what it literally contains.

Image Bad alt text Good alt text
Team photo on an About page "image" "Five team members in the office, smiling"
Screenshot of the editor "screenshot" "The Silex editor showing the Style panel with typography controls"
Logo at the top of the page "logo" "Silex" (the brand name is what it communicates)
Decorative gradient background Any text Empty alt (alt="") -- see Decorative images

Rules:

  • Keep it under 125 characters -- concise but specific
  • Do not start with "image of" or "picture of" -- screen readers already announce "image"
  • Include text visible in the image (signs, buttons, labels)
  • If the image is a link, the alt text should describe the link destination, not the image

Decorative images

Images that add no information -- background textures, decorative dividers, visual flourishes -- should have empty alt text (alt=""). This tells screen readers to skip them entirely.

In Silex, leave the alt field blank for decorative images. Do not omit it -- an empty alt attribute and a missing alt attribute are different. Missing alt causes screen readers to read the file name, which is worse.

Complex images

Charts, diagrams, infographics, and data visualizations need more than a short alt text. Provide:

  1. A brief alt describing the image type and topic ("Bar chart comparing sales by quarter")
  2. A longer description nearby in the page text, or linked from the image

For a chart, the full data should be available as a table elsewhere on the page or behind a link.

Video accessibility

Captions and subtitles

Videos with speech need captions. Captions help deaf and hard-of-hearing users, but also users in noisy environments, non-native speakers, and anyone who prefers reading.

If you embed videos from YouTube or Vimeo, use their built-in captioning tools. If you use self-hosted <video> elements, add a <track> element with a WebVTT caption file via the Custom code block.

Transcripts

Provide a text transcript for any video or audio content. A transcript is a complete text version of the spoken content, placed on the page below the media or linked nearby.

No autoplay with sound

Autoplaying media with sound is disorienting for screen reader users (their screen reader's audio competes with the video's audio) and annoying for everyone else.

If you use autoplay on a video, it must be muted by default. Provide controls so users can unmute when ready.

Audio accessibility

Audio content (podcasts, sound clips) needs a transcript. Place it on the same page or link to it directly below the audio player.

Animation and motion

Flashing content

Content that flashes more than three times per second can trigger seizures in people with photosensitive epilepsy. This is a WCAG Level A requirement -- the highest priority level.

Do not create content that flashes rapidly. This includes animated GIFs, auto-playing videos, and CSS animations with rapid color changes.

Reduced motion

Some users experience nausea or disorientation from animations. CSS provides prefers-reduced-motion, a media query that detects when users have requested reduced motion in their operating system.

If you add CSS animations via Custom code, wrap them:

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

This disables animations for users who request it while keeping them for everyone else.

Practical example: accessible hero section with image and video

You are building a hero section with a background image and an embedded video.

  1. Background image: This is decorative (the text overlay carries the message). Set alt text to empty.
  2. Video: Embed from YouTube with captions enabled.
  3. Use the Map block to embed the YouTube iframe
  4. Ensure the YouTube video has captions uploaded
  5. Add a link below: "Read the transcript" pointing to a transcript section on the page
  6. Text overlay: Ensure sufficient contrast between the text and the image behind it. Add a dark overlay if needed (see Colors and backgrounds).

Common mistakes

  • Missing alt text. Every <img> needs an alt attribute -- either descriptive text or empty for decorative images.
  • Alt text that says "image" or the file name. IMG_4392.jpg tells the user nothing. Describe what the image communicates.
  • Autoplay video with sound. Mute by default and provide controls.
  • No captions on video with speech. Captions are not optional -- they are required for AA compliance.
  • No transcript for audio content. Podcasts and sound clips need text equivalents.
  • Animated GIFs that flash rapidly. Check the frame rate. If it flashes more than 3 times per second, remove it.

Learn more

Reference: WCAG media requirements summary
Criterion Level Requirement
1.1.1 Non-text Content A All images have alt text (or are marked decorative)
1.2.1 Audio-only and Video-only A Provide transcript for audio-only, transcript or audio description for video-only
1.2.2 Captions (Prerecorded) A Captions on all prerecorded video with audio
1.2.3 Audio Description A Audio description or text alternative for prerecorded video
1.2.5 Audio Description (Prerecorded) AA Audio description for all prerecorded video
2.3.1 Three Flashes or Below A No content flashes more than 3 times per second

Quiz

Q1: An image shows a bar chart of quarterly sales. What should the alt text be?

  • A) "chart"
  • B) "Bar chart showing Q1 at 50k, Q2 at 75k, Q3 at 60k, Q4 at 90k"
  • C) "Bar chart comparing quarterly sales -- see data table below"
Answer

C) "Bar chart comparing quarterly sales -- see data table below" -- Alt text should be concise. For complex images, provide a brief description and point to a full text equivalent (a data table) elsewhere on the page.

Q2: A decorative wave divider separates two sections. What should its alt text be?

  • A) "wave divider"
  • B) "decorative image"
  • C) Empty (alt="")
Answer

C) Empty (alt="") -- Decorative images that add no information should have empty alt text. This tells screen readers to skip them.

Q3: Your hero section has a video that autoplays. A screen reader user visits the page and hears both their screen reader and the video audio at the same time. What went wrong?

  • A) The video should be muted by default
  • B) The video needs captions
  • C) The video should be smaller
Answer

A) The video should be muted by default -- Autoplaying media with sound interferes with screen readers. Always mute autoplay video and provide controls for the user to unmute.

Edit this page on GitLab