Auditing a WordPress media library for accessibility

Auditing a WordPress media library for accessibility is not simply a matter of finding images with an empty Alt Text field and filling every blank with a description.

That approach sounds efficient. It is also wrong.

Some images need meaningful alternative text. Some should deliberately use an empty alt="". Functional images need text that communicates an action or destination rather than their appearance. Complex charts may need information outside the alt attribute entirely. Images containing meaningful text create another category of problems.

And WordPress adds an important complication: the Media Library stores attachment metadata, but accessibility is ultimately determined by how an asset is used on the frontend.

A serious media accessibility audit therefore needs to examine both:

the media asset
+
the context in which it appears

This guide explains how to audit a WordPress Media Library systematically, identify accessibility problems, prioritize fixes and create an editorial workflow that prevents the same problems from accumulating again.

What does a WordPress media accessibility audit actually examine?

A useful audit goes beyond asking:

Does this image have alt text?

Instead, it asks questions such as:

• Is the image informative, decorative or functional?
• Does it contain text that users need to understand?
• Is its alternative text appropriate for its purpose?
• Is the same image used in different contexts?
• Does a linked image communicate its destination?
• Does a chart have an accessible equivalent?
• Are important instructions communicated only visually?
• Are captions being confused with alternative text?
• Are filenames being used as accidental alternatives?
• Are PDFs and other downloadable media accessible?
• Does the rendered frontend markup match the intended metadata?

The objective is not to maximize the number of populated metadata fields.

The objective is to make the information and functionality conveyed by media available to users who cannot perceive it visually in the same way.

Start with WCAG 2.2 Success Criterion 1.1.1

The foundation of an image accessibility audit is WCAG 2.2 Success Criterion 1.1.1: Non-text Content.

Its central principle is that non-text content presented to users should have an appropriate text alternative, with specific handling for situations such as controls, sensory content and decoration.

The W3C Images Tutorial divides common image uses into categories including:

• informative images;
• decorative images;
• functional images;
• images of text;
• complex images;
• groups of images;
• image maps.

That classification is much more useful than a binary:

alt text present
vs.
alt text missing

Understand what WordPress stores

When you upload an image to WordPress, the system creates an attachment record rather than merely copying a file into wp-content/uploads/.

The Media Library exposes information such as:

• file name;
• file type;
• file size;
• dimensions;
• Alt Text;
• Title;
• Caption;
• Description;
• upload date;
• uploader;
• the post or page to which the media is attached, where applicable.

The official WordPress Media Library documentation specifically identifies Alt Text as the field used to describe an image for accessibility.

For a deeper understanding of how WordPress represents media internally, see WordPress Attachment Status and Term Counts, Explained.

Alt Text, Title, Caption and Description are not interchangeable

One of the first things to check during an audit is whether editors understand the purpose of the different fields.

They are not four different places to paste the same sentence.

Alt Text

Alternative text communicates the relevant information or function of an image when the image cannot be perceived visually.

Title

The attachment title is WordPress metadata used for identifying and managing the attachment. Themes or plugins may also display it in particular contexts.

It is not a substitute for appropriate alt text.

Caption

A caption is normally visible content associated with the image.

It may provide attribution, explanation or additional context.

Description

The attachment description is a longer WordPress metadata field whose frontend use depends on the theme, plugin or attachment-page implementation.

Do not copy the attachment title into Alt Text automatically

Consider an attachment named:

IMG_4837.jpg

with the title:

IMG 4837

Automatically producing:

alt="IMG 4837"

does not make the image meaningfully accessible.

It merely converts an internal identifier into audible clutter.

The first audit mistake: treating every blank Alt Text field as an error

An empty alternative text value can be exactly correct.

The W3C recommends a null alternative:

alt=""

for images that are purely decorative and add no information or functionality. This allows assistive technologies to ignore them rather than announcing unnecessary content.

See the W3C guidance on decorative images.

Therefore:

empty alt
≠
automatically inaccessible

Missing alt and intentionally empty alt are conceptually different

These two examples may look similar to an editor but represent different markup:

<img src="team.jpg">

<img src="divider.jpg" alt="">

The first omits the alt attribute.

The second explicitly provides an empty alternative.

For decorative images, the second pattern is generally the appropriate one.

The distinction matters because assistive technologies may handle an image without an alt attribute differently, including potentially exposing its filename.

WordPress introduces another subtlety

The WordPress accessibility handbook notes that when no alt text is stored for an image in the Media Library, WordPress can output an empty alt="" value on the frontend.

That means a database audit alone cannot always distinguish:

intentionally decorative image
from
informative image nobody described

Both may have an empty Media Library field.

This is one reason automated detection can identify candidates but cannot complete the accessibility audit for you.

Classify images before fixing them

A practical audit should assign each important image to a functional category.

Image
│
├── Informative
├── Decorative
├── Functional
├── Image of text
├── Complex
└── Context-dependent

The W3C alt decision tree is particularly useful for making these decisions consistently.

1. Informative images

An informative image communicates information that contributes to understanding the page.

Examples include:

• a photograph identifying a person;
• a product photograph showing a relevant feature;
• a screenshot demonstrating an interface state;
• an illustration explaining a concept;
• a diagram showing a relationship.

These images generally need a text alternative that communicates the essential information relevant to the surrounding content.

Describe purpose, not every visible pixel

Imagine an article about optimizing a WordPress Media Library containing a screenshot of the Media Library in List view.

A poor alt text might be:

Screenshot

A better version could be:

WordPress Media Library in List view showing image,
author and upload-date columns

The second alternative communicates why the screenshot matters.

Context determines what information matters

The same photograph can require different alternative text in different contexts.

Imagine a photograph showing a person standing beside a solar installation.

On a company team page, the important information might be:

Maria Rossi, Head of Engineering

On a solar-installation case study, the relevant information might instead be:

Roof-mounted solar panels installed across the south-facing
section of the warehouse

The pixels have not changed.

The purpose has.

For a dedicated guide to writing these alternatives, see How to Write Good Alt Text.

2. Decorative images

A decorative image does not communicate information needed to understand or use the page.

Examples can include:

• visual flourishes;
• background textures;
• decorative separators;
• stock imagery used only for atmosphere;
• an illustration whose information is already fully communicated by adjacent text.

These should generally be ignored by assistive technologies.

<img src="decorative-wave.svg" alt="">

Do not describe decoration merely because an Alt Text field exists

This is unnecessary:

alt="Abstract blue decorative wave with curved lines"

if the image exists only to decorate a section.

A screen-reader user does not benefit from hearing a guided tour of every ornamental squiggle the design team considered spiritually important.

Decorative images can often live in CSS

Where appropriate, purely decorative visual assets can be implemented as CSS backgrounds instead of semantic content images.

The W3C explicitly identifies CSS as one possible way to handle decorative imagery.

That architectural decision is usually made during development rather than during a Media Library cleanup, but an audit can identify candidates for future refactoring.

3. Functional images

A functional image performs an action or forms part of an interactive control.

Examples include:

• an image used as a link;
• an icon-only button;
• a graphical download control;
• a logo linking to the homepage;
• a search icon acting as a button.

For these images, describing appearance is often less useful than communicating function.

The W3C’s image guidance recommends that functional alternatives communicate what the control does or where it goes.

Describe the destination, not merely the picture

Suppose a shopping-cart icon opens the cart.

Weak:

alt="shopping cart icon"

More useful in the appropriate implementation:

alt="View cart"

The user needs to understand the action.

Audit linked images separately

During the audit, identify images inside:

<a>...<img>...</a>

and ask whether the link has an accessible name without relying on visual interpretation.

If the image sits beside meaningful text inside the same link, repeating that text in the image’s alt value may be unnecessary.

4. Images of text

Images containing readable text deserve special attention.

Examples include:

• promotional banners;
• event posters;
• sale graphics;
• screenshots containing instructions;
• infographics;
• social graphics reused on the website.

WCAG generally favors real text over images of text where the same visual presentation can reasonably be achieved using web technologies.

The W3C guidance on images of text explains why real text is more adaptable to resizing and user presentation preferences.

Check whether important words exist anywhere outside the image

Imagine an image containing:

Summer Sale
30% off until July 31
Use code SUMMER30

If none of that information exists as accessible text elsewhere, a user who cannot perceive the graphic may lose the entire promotion.

Do not cram an entire poster into a tiny alt attribute

If an image contains substantial information, a short alt attribute may not be enough.

Instead:

short identification
+
equivalent information in page content

may provide a better solution.

5. Complex images

Charts, diagrams, maps and infographics can contain far more information than a concise alt attribute can reasonably communicate.

Examples include:

• analytics charts;
• organizational diagrams;
• technical architecture diagrams;
• comparison graphics;
• maps containing meaningful locations;
• data visualizations.

Use short identification plus a fuller equivalent

A chart might use:

alt="Monthly organic search traffic from January to June"

while the surrounding page provides:

• the important conclusion;
• the relevant values;
• a table containing the underlying data;
• or another detailed textual explanation.

The alt attribute should not become a 700-word hostage situation.

Audit screenshots carefully

WordPress documentation and technical blogs often contain many screenshots.

For each screenshot, ask:

What is the reader supposed to learn from this image?

If the screenshot exists to show where a setting is located, the alternative should communicate that relevant information.

If the surrounding instructions already explain everything and the screenshot is merely visual reinforcement, a shorter alternative or decorative treatment may sometimes be appropriate depending on context.

Do not use filenames as alt text

During an audit, flag alternatives such as:

IMG_7284.jpg
DSC_0192
Screenshot-2026-04-18-at-14.33.08
hero-final-v3
AdobeStock_48293829

These usually describe the asset-management process rather than the content or purpose of the image.

WCAG guidance specifically identifies filename-like or placeholder alternatives as a potential failure when they do not provide an actual text alternative.

Flag placeholder alt text

Common low-quality values include:

image
photo
picture
graphic
banner
thumbnail
placeholder
test
photo here

These should not automatically be replaced by a generated description. They should first be reviewed in context.

Usually avoid starting with “image of”

Assistive technology can already expose the element as an image.

Therefore:

Image of a woman using a laptop

can usually become:

Woman using a laptop at a kitchen table

The W3C notes that generic words such as “image”, “icon” and “picture” are usually unnecessary, although identifying the medium can occasionally be meaningful.

Some image types make the medium relevant

There are cases where:

photograph
illustration
painting
diagram
map
screenshot

provides useful context.

For example:

Diagram showing the request flow between WordPress,
the REST API and an external application

Here, identifying the object as a diagram helps explain how the information is structured.

Audit keyword-stuffed alt text

Accessibility audits should also flag alternatives written primarily for obsolete SEO rituals.

For example:

WordPress SEO plugin best WordPress SEO plugin SEO
WordPress plugin WordPress optimization

This is not a meaningful alternative.

Alternative text should communicate the image’s relevant information or function.

Alt text is not an SEO keyword container

Search visibility and accessibility are not enemies, but accessibility should not be degraded in an attempt to manipulate keyword usage.

If a relevant term naturally belongs in the description, use it.

If it does not, do not force it into the field.

Audit repeated alt text across unrelated images

Large WordPress sites often reveal patterns such as:

alt="Our services"
alt="Our services"
alt="Our services"
alt="Our services"

across completely different images.

This can happen because:

• an editor copied metadata;
• an import populated a generic value;
• an automation generated template text;
• a previous SEO workflow reused the page keyword.

Repeated alternatives are not automatically wrong, but they deserve review when different images convey different information.

Audit duplicate assets too

Large Media Libraries frequently contain multiple copies of the same or nearly identical image.

For example:

team.jpg
team-1.jpg
team-final.jpg
team-new.jpg
team-new-final.jpg

Besides making media management mildly hostile to civilization, duplicates can make accessibility maintenance inconsistent.

One copy may have excellent alt text while three others have none.

For broader library maintenance, see Organizing a Large WordPress Media Library.

The same attachment can appear on multiple pages

This is one of the most important WordPress-specific considerations.

An attachment in the Media Library can be reused across:

• posts;
• pages;
• custom post types;
• templates;
• widgets;
• patterns;
• plugin-generated interfaces.

The same physical image may therefore serve different purposes in different locations.

Media Library alt text is a default, not always the final contextual answer

Current WordPress Image block behavior allows alternative text to be set for a particular image instance in page content.

The official WordPress Image block documentation explains that alt text edited in the block applies to that specific page or post, while alternative text stored in the Media Library acts as the default when the image is inserted elsewhere.

This distinction matters enormously during an audit.

Audit usage, not only attachment records

Suppose the Media Library contains:

conference-room.jpg

Alt Text:
People sitting around a conference table

That might be reasonable in one context.

But on a page specifically discussing wheelchair-accessible meeting spaces, the relevant information may be completely different.

Inspecting only the attachment metadata cannot reveal that problem.

Build an attachment-to-content map

For larger sites, a useful audit model is:

Attachment
↓
Where is it used?
↓
What role does it perform there?
↓
What alternative is rendered?
↓
Is that alternative appropriate?

This is more work than exporting a spreadsheet of empty fields.

It is also an actual accessibility audit.

Do not trust “Uploaded to” as a complete usage report

The Media Library can show an attachment relationship to a parent post, but that relationship does not reliably tell you every place where the asset is used.

An image can be referenced through:

• block content;
• post metadata;
• theme options;
• custom fields;
• page builders;
• CSS;
• plugin settings;
• custom database structures.

Therefore:

Unattached
≠
unused

This is especially important before deleting media during an accessibility cleanup.

Do not turn an accessibility audit into a deletion spree

Finding an apparently unused inaccessible image does not mean:

delete immediately

Confirm usage first.

Large libraries benefit from structured maintenance processes, as discussed in Keeping a WordPress Media Library Organized at Scale.

Audit featured images

Featured images deserve their own review because themes can render them differently.

A featured image may appear:

• inside a single post;
• in archive cards;
• in related-content blocks;
• on the homepage;
• inside social components;
• in search results;
• inside custom templates.

The same attachment may therefore appear in several contexts.

Check whether the theme outputs useful markup

Do not assume that correct Media Library metadata guarantees correct frontend HTML.

Inspect the rendered markup.

You may expect:

<img
    src="team.jpg"
    alt="Customer support team working at shared desks"
>

but a custom theme or plugin may produce something else.

Audit images inside links

Pay special attention to card interfaces.

A typical card may contain:

<a href="/services/">
    <img src="services.jpg" alt="...">
    <h3>Our Services</h3>
</a>

If the image and heading are part of the same link, verbose image alt text may cause redundant announcements.

Evaluate the accessible name of the complete interactive element rather than judging the image in isolation.

Audit icon-only controls

Media accessibility is not limited to photographs.

Check graphical controls such as:

• search icons;
• menu icons;
• carousel arrows;
• close buttons;
• download icons;
• social icons;
• play controls;
• zoom controls.

If the control has no visible text, verify that it still has an appropriate accessible name.

SVG requires special attention

SVG can be implemented in many ways:

<img src="icon.svg" alt="...">

inline <svg>...</svg>

CSS background-image

SVG inside a button

The appropriate accessibility treatment depends on implementation and purpose.

An SVG used decoratively should not create unnecessary screen-reader output.

An SVG carrying information or acting as the only label for a control needs an accessible equivalent.

Audit logos

Logos are frequently mishandled.

A site logo linking to the homepage generally needs to make the link’s destination or brand identity understandable.

A practical accessible name might simply be:

TheOneWP

or, depending on the link context:

TheOneWP home

You normally do not need:

Red and blue TheOneWP logo featuring stylized geometric
letters on transparent background

unless those visual details are somehow relevant to the content.

Audit photographs of people

Ask whether identity matters.

On a team page:

Jessica Bianchi, Account Manager

may be more useful than:

Woman smiling in an office

On a generic article where the photograph is purely decorative, neither description may be necessary.

Again, purpose beats pixel inventory.

Audit product images

On ecommerce sites, product images can communicate important purchase information.

Potentially relevant details include:

• product type;
• model;
• view or angle;
• color where relevant;
• configuration;
• a feature specifically being demonstrated.

A gallery containing five views of the same product should not necessarily repeat an identical alternative five times if the different views communicate meaningful distinctions.

Audit before-and-after images

Before-and-after imagery is inherently comparative.

Alternatives should communicate the meaningful difference rather than merely saying:

before image
after image

If the comparison contains important information, that information should also be understandable without relying exclusively on visual inspection.

Audit charts and graphs for color dependence

A chart may technically have alternative text while remaining inaccessible if the only way to distinguish its series is:

red line
vs.
green line

Accessibility auditing therefore extends beyond the alt attribute.

Review:

• labels;
• legends;
• color contrast;
• patterns or other differentiators;
• textual summaries;
• underlying data.

Audit diagrams for information lost outside the image

Suppose a technical architecture diagram communicates:

Browser
↓
CDN
↓
WordPress
↓
Database

If that relationship matters to the explanation, it should be available textually somewhere.

A short alt might identify the diagram, while surrounding text explains the flow.

Audit maps

A map used merely as a decorative location illustration may need little or no alternative description.

A map conveying essential directions, locations or boundaries needs an equivalent way to obtain that information.

For a contact page, this might include a normal textual address and directions rather than forcing a user to interpret a map.

Audit infographics

Infographics are frequent accessibility offenders because they combine:

text
+
numbers
+
>icons
+
charts
+
visual hierarchy

into a single bitmap or SVG.

Do not attempt to solve a complex infographic merely with:

alt="Infographic about WordPress performance"

if the infographic contains information not available elsewhere.

Provide an accessible textual equivalent

Depending on complexity, this may involve:

• a nearby summary;
• a structured list;
• a data table;
• a longer explanation;
• a separate accessible page.

Audit media containing instructions

Screenshots often include arrows, circles and annotations such as:

Click here

Select this option

Enable this toggle

If the surrounding written instructions do not communicate those same actions, the procedure may become inaccessible.

Make the instructions understandable from text first.

Use the screenshot to reinforce them.

Audit images containing error messages

A screenshot showing:

Error establishing a database connection

should not force users to visually read the screenshot to know what error occurred.

Include the relevant message in text.

Audit QR codes

A QR code is functional information.

Do not make scanning the code the only way to reach essential content.

Provide the destination or equivalent action as a normal accessible link where possible.

Audit CAPTCHAs carefully

CAPTCHAs create broader accessibility issues than ordinary images.

WCAG 1.1.1 contains specific provisions for CAPTCHA alternatives.

If a CAPTCHA is used, evaluate whether users have an alternative way to complete the verification using another modality.

Audit PDFs in the Media Library

A WordPress Media Library often contains much more than images.

PDFs may include:

• brochures;
• price lists;
• reports;
• forms;
• manuals;
• menus;
• legal documents;
• downloadable guides.

A media audit should therefore identify important PDFs and assess whether they themselves are accessible.

A descriptive PDF link does not make an inaccessible PDF accessible

Consider:

<a href="annual-report.pdf">
    Download the 2026 annual report
</a>

The link text may be excellent.

But the PDF can still contain:

• scanned images instead of real text;
• missing document structure;
• incorrect reading order;
• unlabeled form fields;
• images without alternatives;
• poor contrast.

The downloadable document requires its own accessibility review.

Audit audio and video too

A Media Library accessibility audit should inventory:

images
PDFs
audio
video
documents

Audio and video raise different requirements involving captions, transcripts, audio descriptions and accessible controls.

Do not label the project “Media Library accessibility complete” after reviewing only JPEG files.

Prioritize by impact

On a site with 20,000 attachments, reviewing everything in arbitrary upload order is rarely efficient.

A better priority model is:

high-traffic content
+
critical user journeys
+
>high-value landing pages
+
frequently reused assets
+
known accessibility failures
+
recent content
+
remaining archive

Start with critical journeys

Review media on pages involved in:

• purchases;
• contact and lead generation;
• account creation;
• checkout;
• booking;
• applications;
• support;
• essential instructions.

An inaccessible decorative image on an old article and an inaccessible image-only checkout control do not deserve equal remediation priority.

Then audit high-traffic content

Analytics can help identify pages where accessibility improvements affect the largest number of visitors.

This does not mean low-traffic content can remain inaccessible forever.

It is simply a sensible way to sequence a large remediation project.

Identify frequently reused attachments

An attachment used in fifty templates may deserve attention before one appearing on an archived page.

Fixing shared components can sometimes resolve many frontend occurrences at once, depending on how their markup is generated.

Create an audit inventory

For a substantial site, track findings systematically.

A useful audit table might contain:

Attachment ID
File name
Media type
Attachment URL
Usage locations
Purpose
Current alt
Recommended alt
Decorative?
Functional?
Contains text?
Complex image?
Priority
Status
Reviewer
Notes

Do not let the spreadsheet become the project

The inventory exists to support remediation.

A beautiful spreadsheet containing 14,000 unresolved accessibility problems is still 14,000 unresolved accessibility problems, merely with excellent column alignment.

Use automated scans for discovery

Automated tools are useful for identifying patterns such as:

• missing alt attributes;
• empty alternatives;
• certain accessible-name problems;
• duplicate IDs;
• some contrast issues;
• structural markup problems.

The W3C’s Easy Checks accessibility review provides a useful starting framework for manual inspection.

But automation cannot decide whether alt text is good

An automated scanner can detect:

alt=""

It cannot reliably decide whether the image is actually decorative.

It can detect:

alt="person standing beside solar panels"

but may not know whether the page needed:

Maria Rossi inspecting damaged solar panel number 14

or no alternative at all.

Accessibility meaning depends on context.

Use AI as an assistant, not as the final accessibility authority

Computer vision can accelerate large media audits by identifying:

• objects;
• people;
• visible text;
• scenes;
• likely image categories.

That can be extremely useful when thousands of legacy attachments have no metadata.

But visual recognition alone does not know why the image appears on the page.

Image recognition answers “what is visible?”

Accessibility frequently asks:

Why is this image here?

Those are different questions.

An AI model might accurately identify:

A woman holding a tablet beside an industrial machine.

But the page might use the image specifically to demonstrate:

The emergency stop control positioned below the display.

The relevant alternative depends on the editorial context.

Review AI-generated alt text

When AI is used to generate alternatives, review for:

• hallucinated details;
• incorrect identities;
• unnecessary physical descriptions;
• irrelevant details;
• missing contextual purpose;
• text visible inside the image;
• keyword stuffing;
• excessive length;
• assumptions about sensitive characteristics.

Never invent identity from appearance

If an image contains a person whose identity is unknown, do not guess.

Similarly, avoid inferring personal characteristics that are not necessary to communicate the image’s purpose.

Bulk generation needs quality control

Suppose an automated system generates 8,000 alternatives overnight.

That may solve:

blank field count

without solving:

accessibility quality

A useful bulk workflow needs review, sampling and escalation rules.

Sample automated output before scaling

For example:

Generate 100 candidates
↓
review manually
↓
identify systematic errors
↓
adjust instructions
↓
repeat
↓
scale only when quality is acceptable

This is considerably safer than letting automation enthusiastically describe every spacer, logo and stock photograph on the website.

Test the frontend, not only wp-admin

The final accessibility experience exists in the rendered page.

After correcting Media Library metadata, inspect representative frontend pages.

Check the actual HTML.

<img src="..." alt="...">

Verify that:

• the intended alt value appears;
• decorative images have appropriate empty alternatives;
• custom components have not removed the attribute;
• page builders are not overriding attachment metadata;
• linked images produce useful accessible names;
• responsive variants remain meaningful.

Inspect accessibility trees when necessary

Browser developer tools can expose the accessibility tree and accessible names calculated for elements.

This is especially useful for:

• icon buttons;
• linked images;
• SVG controls;
• complex components;
• elements using ARIA labels.

Test with keyboard navigation

For interactive media components, verify that users can operate them without a mouse.

Check:

• focus order;
• visible focus;
• keyboard activation;
• carousel controls;
• lightboxes;
• media dialogs;
• playback controls.

An excellent alt attribute cannot rescue a gallery whose controls cannot be reached from the keyboard.

Test with a screen reader

Automated testing is useful, but representative screen-reader testing reveals how the complete interface is actually announced.

Listen for problems such as:

• repetitive alternatives;
• filenames being announced;
• unlabeled controls;
• duplicated link names;
• decorative imagery creating noise;
• important images disappearing from the experience.

Audit responsive behavior

An image component may change between desktop and mobile.

For example:

Desktop:
image + visible text label

Mobile:
icon only

If the text disappears visually on mobile, verify that the control still has an accessible name.

The W3C’s image guidance specifically highlights responsive situations where visual text labels may disappear.

Check lazy-loaded images

Lazy loading itself does not remove the need for accessible markup.

Verify that JavaScript-based lazy-loading systems preserve:

• alt;
• semantic image elements where appropriate;
• accessible names;
• correct focus behavior for interactive media.

Audit lightboxes and galleries

Gallery accessibility involves more than individual thumbnails.

Check whether users can:

• open the gallery with a keyboard;
• understand which image is selected;
• navigate between images;
• close the lightbox;
• retain sensible focus;
• access captions or descriptions;
• avoid keyboard traps.

Thumbnail alt text and full-size image context may differ

A gallery thumbnail may function primarily as a control opening a larger image.

Its accessibility requirements can therefore differ from a standalone informational image.

Review the complete component instead of applying one metadata rule blindly to every generated size.

Do not audit generated WordPress image sizes as separate content

WordPress can generate multiple physical files from one attachment:

photo.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-768x512.jpg

These are normally size variants of the same attachment, not four independent editorial images requiring four separate descriptions.

The accessibility meaning belongs primarily to the image instance and its context.

Media size still affects usability

Accessibility also intersects with performance.

Massive images can create unnecessary transfer costs and poor experiences for users on constrained connections or devices.

Media auditing can therefore include:

• dimensions;
• file size;
• format;
• responsive image behavior;
• unnecessarily large originals;
• generated sizes.

But compression and accessibility are separate dimensions. A perfectly compressed inaccessible infographic remains inaccessible, only faster.

Review the Media Library itself as an editorial interface

Accessibility debt often originates during content production.

If editors cannot easily:

• find existing assets;
• understand filenames;
• identify duplicates;
• review metadata;
• distinguish decorative and informative imagery;

the same mistakes will continue accumulating.

This is why accessibility and library organization overlap with the practices described in Organizing a Large WordPress Media Library and Keeping a WordPress Media Library Organized at Scale.

Create an upload policy

A mature WordPress workflow should define what happens when new media is uploaded.

For example:

Upload asset
↓
give it a meaningful filename where practical
↓
identify intended purpose
↓
write appropriate alternative text if informative
↓
leave decorative alternative intentionally empty
↓
add caption if editorially useful
↓
optimize file
↓
insert into content
↓
review in context

Teach editors when not to write alt text

This is just as important as teaching them how to write it.

If the rule is:

Every Alt Text field must contain something

editors will inevitably create useless alternatives for decorative assets.

A better rule is:

Every image must have an accessibility decision.

That decision may be:

meaningful alt text
or
intentionally decorative

Create a decision process for editors

A simplified editorial decision tree can be:

Does the image communicate information?
│
├── No
│   └── Treat as decorative
│
└── Yes
    │
    ├── Is it a control or link?
    │   └── Describe function/destination
    │
    ├── Is it simple information?
    │   └── Write concise alt text
    │
    └── Is it complex?
        └── Short alt + accessible detailed equivalent

Use the W3C decision tree in editorial documentation

Rather than inventing arbitrary rules, teams can base their internal workflow on the W3C Alt Decision Tree.

This gives editors a repeatable framework instead of asking them to improvise every time they upload an image.

Build accessibility into content review

Before publishing a page, review:

headings
links
forms
media
color
keyboard interaction
content structure

Image accessibility should be part of the publishing workflow rather than an emergency cleanup performed every three years.

Audit existing content in batches

For a large legacy site, divide the project into manageable groups.

For example:

Phase 1
Critical templates and components

Phase 2
Top landing pages

Phase 3
Products and services

Phase 4
High-traffic articles

Phase 5
Recent editorial content

Phase 6
Historical archive

Phase 7
Remaining media and downloadable documents

Track remediation status

Useful statuses might include:

Not reviewed
Needs context review
Needs alt text
Decorative confirmed
Needs long description
Needs frontend fix
Needs document remediation
Fixed
Verified

Notice that:

Alt field populated

is not the same as:

Verified accessible

Separate content problems from implementation problems

An audit will normally uncover both.

Content problem

Image needs better alternative text.

Implementation problem

Theme ignores stored alternative text.

Component problem

Gallery buttons have no accessible names.

Document problem

PDF is an untagged scanned document.

Assign each issue to the appropriate remediation workflow.

Do not make editors fix theme bugs manually

If every image in a custom component loses its alt attribute because of a template bug, fix the template.

Do not ask editors to perform 900 individual metadata rituals that cannot solve the rendering problem.

Likewise, do not solve editorial problems with PHP

If the underlying issue is poor alternative text:

alt="image"

a filter that automatically transforms it into:

alt="image - Example Company"

has merely automated the wrong answer.

Audit custom fields and page builders

WordPress sites frequently store images outside ordinary block content.

Review image fields created by:

• custom-field systems;
• page builders;
• theme options;
• custom post types;
• WooCommerce extensions;
• custom plugins.

Determine where alternative text comes from and how the frontend template outputs it.

Audit hard-coded images

Not every image on a WordPress site exists in the Media Library.

A theme may contain:

/assets/images/logo.svg
/assets/images/decorative-shape.webp
/assets/images/icon-search.svg

A Media Library audit alone will miss these.

For full site accessibility, inspect theme and plugin assets as well.

Audit CSS background images

CSS backgrounds are appropriate for many decorative assets.

They become problematic when they carry information unavailable elsewhere.

The W3C identifies conveying information exclusively through CSS background images as a potential failure of the non-text content requirement.

Audit social graphics reused as website content

Marketing teams often upload graphics originally designed for Instagram or LinkedIn.

These commonly contain substantial embedded text.

When reused on the website, ask whether that information exists in HTML text too.

An image designed for a visual social feed does not automatically become accessible merely because WordPress accepted the upload.

Audit old campaign media

Legacy assets frequently reveal:

• missing alternatives;
• outdated branding;
• text embedded in images;
• duplicate files;
• poor filenames;
• obsolete documents.

Accessibility auditing can therefore overlap with broader media-library housekeeping.

Do not delete history blindly

An old asset may still be:

• embedded in archived content;
• linked externally;
• referenced by a campaign URL;
• used in structured data;
• included in email archives;
• referenced by a custom field.

Confirm dependencies before cleanup.

Accessibility and media organization reinforce each other

A well-organized Media Library makes future accessibility work easier because editors can identify:

• what an asset is;
• where it belongs;
• whether it already exists;
• which version is current;
• which metadata has been reviewed.

A chaotic library makes every future audit slower.

Set a recurring audit schedule

Accessibility should not be treated as a one-time migration project.

Depending on publishing volume, a team might review:

critical templates
→ after major releases

new high-value content
→ during publication review

recent media uploads
→ monthly

broader Media Library
→ quarterly or periodically

The exact cadence matters less than having one.

Measure useful audit metrics

Possible metrics include:

• number of important images reviewed;
• number requiring remediation;
• number confirmed decorative;
• number with missing frontend alternatives;
• number with poor or placeholder alternatives;
• number of inaccessible complex images;
• number of PDFs requiring remediation;
• number of component-level bugs found;
• percentage of priority pages manually verified.

Do not use “percentage of Alt Text fields filled” as your only metric

A site can achieve:

100% populated Alt Text fields

while containing hundreds of descriptions such as:

image
banner
photo
wordpress seo wordpress seo
blue decorative wave

Completion is not quality.

A practical audit workflow

For an established WordPress site, use the following sequence.

1. Inventory media types
↓
2. Identify critical pages and journeys
↓
3. Find images with missing or suspicious alternatives
↓
4. Classify images by purpose
↓
5. Map important attachments to frontend usage
↓
6. Review alt text in context
↓
7. Review decorative treatment
↓
8. Review functional images and controls
↓
9. Review images of text
↓
10. Review complex graphics
↓
11. Review PDFs, audio and video
↓
12. Fix editorial issues
↓
13. Fix theme/plugin rendering issues
↓
14. Test frontend markup
↓
15. Test keyboard and assistive technology
↓
16. Record verification
↓
17. Improve the upload workflow
↓
18. Repeat periodically

A 30-point WordPress media accessibility checklist

1. Inventory the site’s major media types.
2. Prioritize critical user journeys.
3. Identify important images with empty Alt Text fields.
4. Identify placeholder and filename-based alternatives.
5. Identify suspiciously duplicated alt text.
6. Classify informative images.
7. Classify decorative images.
8. Identify functional images.
9. Identify images of text.
10. Identify complex images and charts.
11. Review screenshots containing instructions.
12. Review product imagery.
13. Review featured images.
14. Review logos.
15. Review linked images.
16. Review icon-only controls.
17. Review SVG accessibility.
18. Review maps and QR codes.
19. Review infographics.
20. Review important PDFs.
21. Review audio and video requirements.
22. Map important attachments to actual usage.
23. Do not assume “unattached” means unused.
24. Inspect rendered frontend alt attributes.
25. Inspect accessible names for controls.
26. Test representative components with a keyboard.
27. Test representative pages with assistive technology.
28. Fix implementation problems at component level.
29. Create an accessible media-upload policy.
30. Schedule recurring reviews.

Common audit mistakes

Filling every empty field

Decorative images may correctly need an empty alternative.

Auditing only the Media Library database

Accessibility depends on frontend context and rendered markup.

Using filenames as descriptions

A filename usually identifies a file, not its purpose.

Writing literal visual inventories

Describe relevant information, not every object visible in the frame.

Ignoring functional images

Buttons and links need meaningful accessible names.

Ignoring complex images

A chart may require an accessible textual or tabular equivalent.

Ignoring PDFs

The Media Library contains documents too.

Relying entirely on automated tools

Tools can detect patterns. Human review determines contextual meaning.

Bulk-generating alt text without review

Automation can produce thousands of plausible but contextually wrong descriptions with admirable efficiency.

Fixing metadata when the theme is broken

If frontend templates discard the metadata, fix the implementation.

Deleting apparently unused media

WordPress attachment relationships do not capture every possible reference.

Related guides

• How to Write Good Alt Text
• Organizing a Large WordPress Media Library
• Keeping a WordPress Media Library Organized at Scale
• WordPress Attachment Status and Term Counts, Explained

Final recommendation

When auditing a WordPress media library for accessibility, do not make the number of empty Alt Text fields your definition of success.

Start by understanding what each asset does.

An informative image needs an appropriate text alternative. A decorative image should generally be ignored by assistive technologies. A functional image needs to communicate its function or destination. A complex chart may need an accessible explanation or data equivalent. A PDF, video or audio file requires its own form of accessibility review.

Most importantly, remember that the Media Library is only the storage layer.

The actual accessibility experience exists where the asset is rendered:

Media Library metadata
↓
theme / block / plugin / custom field
↓
rendered HTML
↓
accessibility tree
↓
user experience

That is why a reliable audit combines attachment metadata review with frontend inspection, contextual judgment and representative assistive-technology testing.

Use automated checks to find candidates. Use structured workflows to manage large libraries. Use good alt-text practices for informative images and maintain the library using the principles in Organizing a Large WordPress Media Library.

Then prevent the problem from returning by making accessibility decisions part of the normal upload and publishing workflow.

The goal is not:

Every field contains text.

The goal is:

Every meaningful piece of media information
is available to the people who need it.