Replacement record: Accessible images and media

This record explains how two Drupal 7 theming pages were consolidated into the proposed current documentation page, Accessible images and media. It also provides a short archival notice for each Drupal 7 page.

Pages replaced

Drupal 7 source pages consolidated into the current page
Drupal 7 page	Disposition
Managing images and media for accessibility	Image categories, alternative text, complex images, captions, transcripts, media controls, and autoplay guidance were retained and updated.
Providing Useful Alternative Text for Images	The useful external-resource pointer was replaced with direct, maintainable guidance and current authoritative sources.

What was retained

Alternative text depends on the image's purpose and context.
Decorative images need an empty alternative attribute.
Functional images need text that names the link destination or action.
Complex images need a short alternative and a detailed text equivalent.
Images of text should generally be avoided.
Captions, transcripts, and usable media controls are necessary parts of accessible media.
Important content should not be provided only through CSS background images.

What was updated or added

Verified Drupal 11 behavior

The current page uses Drupal-specific statements only where they were confirmed in Drupal 11 core:

The image field enables the alternative text field and makes it required by default.
The image title field is disabled by default. Core's configuration description says enabling it is not recommended because it can cause screen reader problems.
image.html.twig outputs <img{{ attributes }} />. Theme overrides must preserve the attribute object rather than reconstructing selected attributes.
The Responsive Image module renders one controlling img inside picture. Alternative text stays on the img, not the source elements.

Content-model limitation

The replacement documents a conflict that the old pages missed. Requiring text in Drupal's alternative text field is suitable for informative images, but a decorative image requires the field to produce alt="". A space or filler phrase is not an acceptable workaround. Sites that allow author-selected decorative images need a content model and rendering path that can record and output that decision.

Alternative text by purpose

The replacement gives maintainable guidance for informative, decorative, functional, textual, and complex images. It distinguishes alternative text from captions and states that there is no WCAG 125-character limit.

Current image formats and responsive output

The new page adds CSS background images, SVG, responsive images, and reuse of media items. SVG guidance remains deliberately general because correct implementation depends on whether the SVG is an image source, inline content, a control, or decoration. The page requires testing rather than prescribing one brittle SVG pattern.

Media alternatives mapped to purpose

The old media section grouped captions, transcripts, and descriptions without explaining when each is required. The replacement distinguishes:

captions for meaningful audio in prerecorded synchronized media at WCAG Level A;
captions for meaningful audio in live synchronized media at WCAG Level AA;
transcripts for prerecorded audio-only content at Level A;
audio description for important visual information in prerecorded synchronized media at Level AA; and
descriptive transcripts as broader support for people who cannot use either audio or visual information, with the prerecorded synchronized-media alternative identified as aspirational under an AA target because WCAG places it at Level AAA.

This prevents the common error of presenting captions, transcripts, and audio description as interchangeable.

Media player and motion coverage

The replacement adds keyboard operation, accessible names and states, focus visibility, zoom and reflow, touch and dragging alternatives, captions and audio-description controls, autoplay conditions, moving content, and flashing content. It also makes clear that using a third-party embed does not remove the site's responsibility to test it.

Repeatable testing

The new test list separates checks that tools can perform from judgments that require a person. A tool may detect a missing alt attribute. It cannot determine whether the text communicates the image's purpose or whether a transcript includes the important visual information.

What was removed or corrected

Material removed or corrected and the reason
Old material	Change and reason
Alternative text framed partly as an SEO technique	Rewritten. The primary purpose is to provide an equivalent for people who cannot use the image. Search behavior is not the accessibility requirement.
`alt=" "` presented as equivalent to `alt=""`	Corrected. Decorative images need an empty string with no space. Whitespace is not the intentional empty alternative.
A 125-character threshold for moving descriptions outside `alt`	Removed. WCAG sets no such limit. Alternative text should be concise and appropriate to purpose. Complex information usually belongs in a separate structured description.
The telephone-description test as the main way to write alternative text	Removed. It can prompt excessive visual description and does not reliably identify the image's purpose in context. The replacement asks what information or function would otherwise be lost.
`longdesc` compatibility and deprecation discussion	Removed. The replacement gives current, visible approaches for structured descriptions and associated links without requiring authors to understand the history of an obsolete attribute.
Old examples using a 2009 annual report, a PDF icon, file size, and a `mailto:` link	Removed. They distract from the durable principle that adjacent image and text labels must not create a duplicated or misleading accessible name.
The claim that HTML5 audio and video controls were not interpreted by many assistive technologies	Removed. That compatibility statement is obsolete. Player accessibility must be tested in the selected current implementation.
Adobe Flash requirements and links	Removed. Flash is obsolete and unsupported.
An absolute instruction not to use autoplay	Refined. Avoiding autoplay remains the best default. The replacement also states the applicable requirements when audio or moving content starts automatically.
"Keyboard-only users, mouse-only users, screenreading users, and many others"	Rewritten. The replacement describes the operations and barriers to test rather than assigning people to one device or technology.
A short link list as the complete alternative-text page	Replaced. Several links were old, duplicated, or aimed at static HTML rather than Drupal workflows. The current page contains the essential guidance directly and points to maintained W3C resources.

Content mapping

Where the source material appears in the consolidated page
Current section	Primary source material
Configure Drupal image fields carefully	New Drupal 11 guidance addressing the content-authoring workflow that the old pages only mentioned generally.
Preserve image attributes in Twig	New Drupal 11 theme guidance replacing Drupal 7-era assumptions.
Write alternative text for the image's purpose	Both source pages, consolidated and corrected.
Handle CSS images and SVG	CSS guidance from Managing images and media, expanded for current SVG and responsive-image use.
Provide accessible audio and video	Audio, video, and interactive media section, corrected against current W3C media guidance.
Use an accessible media player	Media-control guidance, expanded for current input, focus, responsive, and third-party player risks.
Test the rendered content	New repeatable review covering images, alternatives, media content, and player behavior.

Copy-ready archival notices

Managing images and media for accessibility

<p><strong>This Drupal 7 page is no longer supported.</strong> See <a href="/docs/getting-started/accessibility/accessible-images-and-media">Accessible images and media</a> for current guidance. Drupal 7 reached end of life on 5 January 2025. See <a href="/about/drupal-7/d7eol/partners">Drupal 7 support options</a> if you still maintain a Drupal 7 site.</p>

Providing Useful Alternative Text for Images

<p><strong>This Drupal 7 page is no longer supported.</strong> See <a href="/docs/getting-started/accessibility/accessible-images-and-media">Accessible images and media</a> for current guidance. Drupal 7 reached end of life on 5 January 2025. See <a href="/about/drupal-7/d7eol/partners">Drupal 7 support options</a> if you still maintain a Drupal 7 site.</p>