How to write good alt text

How to write good alt text starts with a deceptively simple question: what does someone need to understand from this image if they cannot see it?

The answer is not always a literal description of everything visible in the picture.

Sometimes the right alternative text describes an object. Sometimes it identifies a person. Sometimes it explains an action, destination or result. Sometimes a complex image needs additional text outside the alt attribute. And sometimes the correct alt text is deliberately empty.

That is why good alt text cannot be reduced to:

Describe what you see.

A better principle is:

Communicate what the image means
in this particular context.

This guide explains how to write useful alternative text for WordPress images, when to leave alt text empty, how context changes the correct description, what to do with screenshots, products, charts, logos and linked images, and how to review AI-generated alt text before using it.

What is alt text?

Alternative text is a textual alternative for non-text content such as an image.

In ordinary HTML, it is provided through the alt attribute:

<img
    src="wordpress-dashboard.jpg"
    alt="WordPress dashboard showing the Posts screen"
>

The purpose is not to create a hidden caption.

It is to provide an alternative way to understand the relevant information or function of the image.

The accessibility foundation comes from WCAG 2.2 Success Criterion 1.1.1: Non-text Content, which requires appropriate text alternatives for non-text content while defining different treatment for controls, sensory content, decoration and other cases.

Why alt text matters

Images communicate information visually.

That information may not be available to someone who:

• uses a screen reader;
• cannot see the image clearly;
• has disabled image loading;
• is using a text-oriented interface;
• encounters an image that failed to load.

Good alternative text preserves the useful information rather than merely acknowledging that an image exists.

Alt text is not an image inventory

Consider a photograph showing a developer sitting at a desk with a laptop, coffee mug, notebook, phone, plant, keyboard and external monitor.

A literal description could be:

A person sitting in a black chair at a wooden desk
with a silver laptop, black monitor, white coffee mug,
green plant, notebook, phone and keyboard.

That may be accurate.

It may also be completely irrelevant.

If the article is explaining remote WordPress development, something like this may be more useful:

Developer working on a WordPress site from a home office

The objective is not to prove that you successfully located every object in the photograph.

The central rule: describe purpose in context

The W3C Images Tutorial emphasizes that appropriate alternatives depend on how an image is being used.

This is the single most important concept in alt-text writing.

The same image can legitimately need different alternative text on different pages.

The same photograph can have different alt text

Imagine a photograph showing a woman standing beside a rooftop solar installation.

On a company team page

The purpose may be identifying the employee:

Maria Rossi, Head of Engineering

On a solar installation case study

The relevant information may instead be:

Solar panels installed across the south-facing warehouse roof

On a decorative homepage section

If the image contributes no information and merely provides atmosphere, the appropriate alternative may be:

alt=""

Same image.

Three different purposes.

Three different accessibility decisions.

Do not ask only “What is in the image?”

Ask:

Why did we put this image here?

Then:

What information would disappear
if the image were unavailable?

The answer usually points toward the appropriate alternative.

Classify the image before writing anything

The W3C divides images into several functional categories, including:

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

The W3C Alt Decision Tree provides a useful framework for deciding which treatment an image needs.

1. Informative images

An informative image communicates information that contributes to understanding the surrounding content.

Examples include:

• a photograph identifying a person;
• a product image showing a feature;
• a screenshot demonstrating a setting;
• an illustration explaining a concept;
• a photograph documenting an event;
• a diagram showing a relationship.

These images generally need meaningful alternative text.

Describe the essential information

Suppose an article discusses the WordPress Site Health screen.

The screenshot shows many interface elements, but the article is specifically explaining the site’s PHP version.

Weak:

WordPress screenshot

Better:

WordPress Site Health Info screen showing PHP version 8.3

The better alternative communicates the information the screenshot exists to demonstrate.

Do not describe irrelevant visual details

Suppose the screenshot also contains:

• a dark admin sidebar;
• the WordPress logo;
• several menu items;
• a browser toolbar;
• three unrelated settings.

If none of those details matter to the explanation, they do not need to appear in the alt text.

Good alt text is selective

Writing alt text is an editing task.

You are deciding:

important information
vs.
visual noise

That distinction is more useful than trying to create a complete verbal reconstruction of the image.

2. Decorative images

Some images contribute visual styling but no information.

Examples may include:

• abstract background shapes;
• decorative separators;
• ornamental illustrations;
• stock photography used purely for atmosphere;
• visual flourishes around a heading.

For these images, adding descriptive alt text can make the experience worse.

Decorative images normally need an empty alternative

The W3C guidance for decorative images recommends using a null alternative for images that do not communicate meaningful information:

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

This allows assistive technologies to ignore the image.

Empty alt text is not automatically missing alt text

These are different:

<img src="photo.jpg">

and:

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

The first image has no alt attribute.

The second explicitly declares an empty alternative.

For an intentionally decorative image, the second can be correct.

Do not fill every WordPress Alt Text field merely because it is empty

This is one of the most common mistakes in large accessibility cleanups.

An editor sees:

Alt Text:
[                     ]

and assumes something must be entered.

Not necessarily.

The right question is whether the image communicates information.

For a complete workflow for reviewing an existing library, see Auditing a WordPress Media Library for Accessibility.

3. Functional images

A functional image performs an action or acts as part of a control.

Examples include:

• an image used as a link;
• a graphical download button;
• a search icon;
• a logo linking to the homepage;
• an image used to open a larger gallery view.

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

The W3C provides specific guidance for functional images.

Describe what the control does

Suppose a magnifying-glass image submits a search form.

Weak:

alt="magnifying glass"

Better:

alt="Search"

The second tells the user what happens when the control is activated.

Linked images need contextual review

Consider:

<a href="/pricing/">
    <img src="pricing-card.jpg" alt="...">
</a>

If the image is the only content inside the link, its alternative may need to communicate the destination:

View pricing plans

Simply describing the pixels may leave the purpose of the link unclear.

But avoid duplicate link text

Now consider:

<a href="/pricing/">
    <img src="pricing-card.jpg" alt="">
    <span>View pricing plans</span>
</a>

If the visible text already provides the accessible name and the image contributes no additional information, an empty image alternative may avoid redundant announcements.

4. Images of text

Some images contain text that users need to understand.

Examples include:

• sale banners;
• event posters;
• social graphics;
• promotional cards;
• screenshots;
• infographics.

The W3C’s images-of-text guidance explains that real text should generally be preferred where the same presentation can reasonably be achieved with web technologies.

If the image contains essential text, make that information available

Suppose a promotional graphic contains:

Summer Sale
30% off
Ends July 31
Code: SUMMER30

An alternative such as:

Summer sale banner

loses most of the important information.

But stuffing the entire campaign into a huge alt attribute may not be the best solution either.

Prefer real HTML text for important information

A stronger implementation could provide:

<img
    src="summer-sale.jpg"
    alt=""
>

<h2>Summer Sale</h2>
<p>Save 30% until July 31 with code SUMMER30.</p>

Now the promotional information is available as actual text rather than trapped inside an image.

5. Complex images

Complex images include:

• charts;
• graphs;
• maps;
• technical diagrams;
• infographics;
• visualizations containing substantial data.

A normal alt attribute may not be capable of communicating everything these images contain.

Use alt text to identify the image, then provide the detail elsewhere

For a chart:

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

may identify the subject.

The surrounding content can then explain:

Organic traffic increased from 12,400 visits in January
to 19,800 in June, with the largest month-over-month
increase occurring between March and April.

Or provide a data table containing the actual values.

Do not turn alt text into an essay

There is no benefit in squeezing a complex visualization into an enormous attribute simply because the field technically accepts more characters.

Use the surrounding document structure.

6. Photographs of people

When a photograph contains a person, ask whether their identity matters.

Team page

Jessica Bianchi, Account Manager

Conference report

Maria Rossi presenting the accessibility workshop at WordCamp

Decorative office photograph

alt=""

The presence of a human face does not automatically require a physical description.

Avoid unnecessary assumptions about people

Do not infer characteristics that you do not know and that are not relevant to the image’s purpose.

For example, avoid guessing:

• identity;
• age;
• ethnicity;
• health status;
• relationships;
• emotions;
• professions.

Describe what is necessary and supported by the context.

Do not guess emotions from facial expressions

An image may appear to show someone:

happy
angry
worried
confused

but unless that interpretation is important and well-supported, more neutral language is usually safer.

Instead of:

Frustrated developer staring angrily at broken code

you might write:

Developer reviewing an error message on a laptop

7. Product images

Product images often communicate information that affects a purchasing decision.

Relevant details may include:

• product type;
• model;
• variant;
• color where relevant;
• view or angle;
• a specific product feature.

Make product alternatives distinguish useful variations

Suppose a gallery contains:

front view
side view
back view
detail of connector panel

Repeating:

Black wireless speaker

four times does not communicate what each image contributes.

Better alternatives might be:

Black wireless speaker, front view

Black wireless speaker, side view

Black wireless speaker, rear view

Black wireless speaker rear panel showing USB-C
and auxiliary inputs

Do not turn product alt text into keyword stuffing

This:

best wireless speaker black wireless speaker Bluetooth
speaker cheap wireless speaker buy wireless speaker

is not useful alternative text.

It is merely keyword stuffing wearing an accessibility badge.

8. Screenshots

Screenshots are extremely common in WordPress tutorials.

The useful alternative depends on why the screenshot is included.

Suppose a screenshot shows the Permalink settings screen.

Weak:

WordPress settings screenshot

Better:

WordPress Permalink Settings with Post name selected

Describe the relevant state

If the screenshot demonstrates:

Settings → Permalinks → Post name

that state matters more than the browser color, sidebar position or monitor dimensions.

Instructions should still exist in text

Do not make a screenshot the only place where a user can learn:

Click Settings, choose Permalinks and select Post name.

Write those instructions in the page content.

Then the screenshot becomes supporting visual information rather than the sole source of the procedure.

9. Logos

For a company logo, the organization name is often sufficient:

alt="TheOneWP"

If the logo functions as a homepage link and no other link text exists, the context may justify:

alt="TheOneWP home"

Usually avoid visual descriptions such as:

Red and blue geometric logo with stylized letters

unless those visual characteristics are relevant to the content.

10. Icons

Decorative icons generally do not need to be announced.

A checkmark beside:

Backup completed successfully

may be decorative because the adjacent text already communicates the status.

An icon-only button, however, needs an accessible name.

Alt text is not always the mechanism for icons

Inline SVGs, icon fonts and CSS icons may require other accessibility techniques.

The broader principle remains:

Can a non-visual user understand
the information or action?

11. Maps

A map may communicate:

• an address;
• a route;
• several locations;
• a geographic boundary;
• data associated with regions.

A simple:

alt="Map"

usually contributes very little.

If the map merely supports a contact page, ensure that the actual address exists as text.

If it communicates complex geographic information, provide an appropriate textual equivalent.

12. Charts and graphs

Do not attempt to list every data point in the alt attribute.

Identify the chart:

Organic traffic by month from January to June

Then provide the important trend or underlying data in nearby text or a table.

Describe the conclusion when it matters

If the chart exists specifically to demonstrate that conversions doubled, the surrounding text should make that conclusion explicit.

The reader should not have to see the line rising to obtain the argument.

13. Infographics

Infographics often combine:

• headings;
• statistics;
• icons;
• charts;
• illustrations;
• relationships.

They are therefore poor candidates for a single short alt attribute.

Provide a concise identification and make the important information available in normal page content.

14. QR codes

A QR code usually represents an action or destination.

Do not provide only:

alt="QR code"

if the code is the only way to access important content.

Provide the destination as a normal link whenever possible.

15. Before-and-after images

The point of these images is comparison.

Alternatives such as:

Before image
After image

identify sequence but not the meaningful change.

Where practical, communicate the relevant difference.

For example:

Before optimization: product image with a visible gray background

After optimization: product isolated on a transparent background

16. Diagrams

A diagram may be simple enough for concise alt text:

Request flow from browser to CDN, WordPress and database

But if relationships between components are essential, explain those relationships in the surrounding content too.

17. Image galleries

Gallery alternatives should help users distinguish images where those differences matter.

Repeating:

Gallery image
Gallery image
Gallery image
Gallery image

provides almost no information.

But repeating a lengthy product name unnecessarily for twenty decorative angles can also create noise.

Write according to what each image contributes.

How long should alt text be?

There is no universal character limit that makes alt text automatically good or bad.

The correct length depends on the information required.

Good alternatives are usually concise because irrelevant detail makes the experience harder to understand.

But:

shorter
≠
automatically better

Write as much as necessary and no more

Compare:

Dog

with:

Golden retriever carrying a red rescue dummy from the water

If the article discusses water-rescue training, the second description communicates relevant information.

If the image is decorative, even the first is unnecessary.

There is no magical 125-character law

You may encounter advice saying alt text must always remain below a particular character count.

Conciseness is valuable, but accessibility decisions should not be driven by an arbitrary number detached from context.

When an image requires a substantial explanation, the better solution is often a concise alt plus a detailed textual equivalent elsewhere.

Should alt text start with “image of” or “picture of”?

Usually, no.

Assistive technology can normally identify an image as an image.

Instead of:

Image of a WordPress developer using a laptop

write:

WordPress developer reviewing plugin settings on a laptop

But sometimes the medium itself matters

There are cases where identifying something as a:

photograph
painting
illustration
diagram
screenshot
map

provides useful information.

For example:

Screenshot of the WordPress Site Health screen showing two critical issues

Here, knowing that the image is a screenshot helps explain its role.

Should alt text include punctuation?

Write natural text.

Punctuation can help assistive technology produce sensible pauses, particularly when alternatives contain more than a few words.

You do not need unusual formatting simply because the text lives inside an HTML attribute.

Should alt text use complete sentences?

Not necessarily.

This can be perfectly appropriate:

WordPress Media Library in grid view

So can:

The WordPress Media Library displays 24 uploaded images in grid view.

Choose whichever communicates the information naturally and efficiently.

Avoid redundant phrases

Weak:

Photo image picture of a laptop computer

Better:

Laptop displaying the WordPress block editor

Avoid filenames

These are not meaningful alternatives:

IMG_4928.jpg

DSC_0291

Screenshot-2026-06-22.png

hero-image-final-v4.webp

A filename describes storage, not meaning.

Avoid generic placeholders

Flag alternatives such as:

image
photo
picture
graphic
banner
thumbnail
icon
test
placeholder

They rarely communicate useful information.

Avoid repeating the caption unnecessarily

If a visible caption already communicates exactly the same information, duplicating it word-for-word in the alt attribute may cause repetitive output.

Evaluate the image and caption together.

They can serve different purposes:

Alt:
what the image communicates

Caption:
visible contextual or editorial information

Alt text and captions are not interchangeable

A caption may provide:

• credit;
• date;
• commentary;
• source;
• additional explanation.

Alternative text should provide the appropriate alternative for the image itself.

Alt text and attachment titles are not interchangeable either

WordPress may create an attachment title from the filename.

For example:

File:
wordpress-dashboard-final.jpg

Attachment title:
wordpress dashboard final

Copying that automatically into Alt Text is not an accessibility strategy.

Where alt text lives in WordPress

WordPress provides an Alt Text field for image attachments in the Media Library.

The official Media Library documentation describes the field as alternative text used for accessibility.

When editing an image attachment, you may also see:

• Title;
• Caption;
• Description;
• Alt Text.

Each has a different purpose.

The Media Library value is not always the final contextual value

An attachment may be reused in multiple places.

For example:

team-photo.jpg

could appear on:

• the homepage;
• an About page;
• a recruitment article;
• a company-history page.

Those contexts may require different alternatives.

The WordPress Image block can use context-specific alternative text

The official WordPress Image block documentation explains how alternative text can be edited for an image in the block editor.

This makes it possible to adapt the alternative to a particular content context rather than assuming one Media Library description is perfect everywhere.

Do not assume “unattached” means irrelevant

An attachment can be referenced through:

• blocks;
• custom fields;
• page builders;
• theme settings;
• custom code;
• plugin interfaces.

This matters when reviewing or cleaning media metadata.

For a broader systematic process, use Auditing a WordPress Media Library for Accessibility.

Alt text and SEO

Alternative text can help search systems understand images and their relationship to surrounding content.

Google’s Google Images SEO documentation recommends descriptive alt text while emphasizing useful, contextually relevant content.

But accessibility should not be sacrificed to keyword manipulation.

Do not write alt text for a search engine instead of a person

Bad:

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

Better:

WordPress SEO analysis panel showing title and meta description checks

If the relevant keyphrase naturally describes the image, including it can be perfectly appropriate.

Forcing it into unrelated images is not.

Context naturally creates relevant terminology

If an article is genuinely about:

WordPress backup restoration

and the screenshot shows that workflow, an alternative such as:

WordPress backup restore screen with database and uploads selected

uses relevant terminology naturally.

No keyword-stuffing ceremony is required.

Do not use identical alt text for every image on a page

A common SEO-driven mistake is assigning the page keyphrase to every image:

WordPress security
WordPress security
WordPress security
WordPress security

Those images probably do not all communicate exactly the same thing.

Write each alternative according to its own purpose.

Good alt text examples

Example 1: team portrait

Weak:

Woman smiling

Better on a team page:

Laura Bianchi, Customer Support Manager

Example 2: tutorial screenshot

Weak:

Screenshot

Better:

WordPress Plugins screen with TheOneWP activated

Example 3: ecommerce product

Weak:

Shoe

Better:

Black leather Oxford shoe, side view

Example 4: decorative hero photograph

Weak:

Beautiful modern office with people working

Better when the image is purely decorative:

alt=""

Example 5: graph

Weak:

Graph

Better:

Monthly conversion rate from January to June

Then explain the important trend in surrounding text.

Example 6: linked logo

Weak:

Red and blue logo

Better where it is the only content in a homepage link:

TheOneWP home

Example 7: icon button

Weak:

Magnifying glass icon

Better:

Search

Example 8: technical diagram

Weak:

Diagram

Better:

Request flow from browser through CDN to WordPress and the database

Example 9: chart showing a conclusion

Weak:

Traffic chart

Better:

Organic search traffic increasing from January to June

Provide exact data separately if those values matter.

Example 10: screenshot with error

Weak:

WordPress error

Better:

WordPress displaying an "Error establishing a database connection" message

How to write alt text step by step

A reliable process can be reduced to a few questions.

Step 1: Determine whether the image communicates anything

Ask:

If this image disappeared,
would the reader lose information?

If no, it may be decorative.

Step 2: Identify the image’s purpose

Why was it added?

identification?
instruction?
evidence?
comparison?
navigation?
decoration?
data?

Step 3: Identify what the surrounding text already says

Do not unnecessarily repeat information that is already available immediately beside the image.

Step 4: Write the essential missing information

Communicate what someone needs from the image.

Step 5: Remove unnecessary visual detail

Ask whether each detail changes understanding.

Step 6: Remove redundant wording

Words such as:

image of
picture of
photo of

are often unnecessary.

Step 7: Read it in context

Imagine the page being read aloud.

Does the alternative:

• make sense?
• repeat nearby content?
• interrupt the flow?
• communicate enough?
• communicate too much?

A simple alt-text formula

There is no universal template, but this can be useful:

relevant subject
+
relevant action/state
+
important context

For example:

WordPress Media Library
+
showing images in grid view
+
with three items selected

becomes:

WordPress Media Library in grid view with three images selected

Do not force every description into the formula

Sometimes:

Maria Rossi, Technical Director

is already complete.

Sometimes:

alt=""

is already complete.

Good accessibility writing is contextual, not template worship.

Writing alt text for multilingual WordPress sites

Alternative text should normally match the language of the surrounding content.

An Italian page should not unexpectedly announce an English image description unless there is a meaningful reason.

For multilingual sites, treat translated alt text as content that may require localization.

Do not blindly machine-translate ambiguous alternatives

A source alternative that is already vague:

Dashboard view

does not become more useful merely because it has been accurately translated into six languages.

Improve the source meaning first.

AI can help generate alt text

Modern multimodal models can analyze images and generate descriptive text.

This can be particularly useful for WordPress sites with:

• large Media Libraries;
• legacy images;
• high publishing volumes;
• many product photographs;
• editorial teams that need a first-draft description.

TheOneWP AI Alt Text Generator applies this type of workflow directly to WordPress media.

But AI sees pixels, not editorial intent

An AI model can often recognize:

person
laptop
dashboard
coffee mug
office

It may not know that the article specifically cares about:

the warning visible in the WordPress dashboard

That distinction is why AI-generated alt text should be treated as a candidate, not unquestionable truth.

Review AI-generated descriptions for relevance

Ask:

• Did it identify the correct subject?
• Did it describe the relevant information?
• Did it include irrelevant visual details?
• Did it miss important text?
• Did it invent anything?
• Is the image actually decorative?
• Does the description fit this page?

AI can hallucinate visual details

Image-understanding models are not infallible.

They may incorrectly identify:

• objects;
• text;
• locations;
• brands;
• people;
• actions.

Never assume a generated description is factual merely because it sounds specific.

AI should not guess identities

If a model produces:

CEO John Smith speaking at a conference

when the image provides no reliable basis for identifying the person, correct it.

Use known editorial metadata when identity matters.

AI should not decide decoration from pixels alone

Whether an image is decorative depends largely on context.

A photograph of a server rack might be:

informative

in an article about data-center infrastructure, but:

decorative

in the background of a hosting-company hero section.

The visual content is the same.

The semantic role is different.

Provider choice matters less than review quality

Different multimodal models can produce different descriptions from the same image.

If you are choosing between AI providers for WordPress image processing, see OpenAI vs. Gemini for WordPress AI Features.

Whichever provider you use, the final accessibility decision still belongs to the content workflow.

Bulk AI generation requires sampling

If you generate alt text for thousands of legacy images, do not assume success because the API returned HTTP 200 several thousand times.

Use a process such as:

generate small sample
↓
review manually
↓
identify systematic errors
↓
adjust instructions
↓
test again
↓
scale gradually
↓
continue quality sampling

Separate generation from approval

A useful workflow is:

AI suggestion
↓
editorial review
↓
approved alternative
↓
save

rather than:

AI suggestion
↓
automatic truth

Alt text should survive a simple test

Imagine the image is unavailable.

Read:

previous sentence
+
alt text
+
next sentence

Does the page still make sense?

If the alternative feels repetitive, irrelevant or confusing, revise it.

The telephone test

Another useful mental model is:

How would I communicate the important part
of this image to someone over the phone?

You probably would not describe every shadow, pixel and decorative object.

You would explain what matters.

The deletion test

Temporarily imagine deleting the image.

Ask:

What information disappeared?

If the answer is:

nothing

the image may be decorative.

If the answer is:

the reader no longer knows which setting to enable

that missing information should be available textually.

The repetition test

Read the visible text immediately around the image.

If the page already says:

The setting is located under Settings → Permalinks.

and the alt text says:

Screenshot showing the setting under Settings → Permalinks.

ask whether that repetition provides anything useful.

The purpose test

Complete this sentence:

This image is here because...

If you cannot answer it, the image may not be doing much editorial work in the first place.

Review alt text when content changes

An alternative that was correct when an image was first inserted may become inaccurate after:

• the article is rewritten;
• the image is reused;
• the product changes;
• a screenshot becomes outdated;
• a person changes role;
• the surrounding context changes.

Accessibility metadata is content and should be maintained like content.

Review screenshots after software updates

A screenshot showing an old WordPress interface can become misleading even when its alt text is perfectly written.

When updating technical guides, verify both:

image
+
alternative text

Alt text should describe the current image, not the image you remember uploading

If an attachment is replaced or edited, check whether the existing alternative still matches it.

This is particularly important in workflows that reuse attachment IDs while replacing files.

Audit old alternatives periodically

For established WordPress sites, use the systematic process described in Auditing a WordPress Media Library for Accessibility.

Look for:

• empty alternatives requiring review;
• filename-based descriptions;
• generic placeholders;
• keyword stuffing;
• duplicate descriptions;
• outdated information;
• AI-generated mistakes;
• images that should actually be decorative.

A practical alt-text checklist

1. Determine why the image is on the page.
2. Decide whether it is informative, decorative, functional or complex.
3. If decorative, use an appropriate empty alternative.
4. If informative, identify the essential information.
5. Consider what the surrounding text already communicates.
6. Describe purpose rather than every visible detail.
7. For functional images, communicate the action or destination.
8. For screenshots, describe the relevant interface state.
9. For product galleries, distinguish meaningful views.
10. For charts, identify the subject and provide detailed data elsewhere.
11. For images of text, make important text available as real text where possible.
12. Avoid filenames and placeholders.
13. Avoid unnecessary “image of” wording.
14. Avoid keyword stuffing.
15. Avoid unsupported assumptions about people.
16. Keep the alternative concise but complete.
17. Check whether a caption already communicates some information.
18. Review the description in the context of the page.
19. Verify AI-generated alternatives manually.
20. Revisit alt text when the content or image changes.

Common alt-text mistakes

Describing every image

Decorative images often need an empty alternative.

Leaving informative images undescribed

If meaningful information exists only visually, some users lose it.

Using filenames

IMG_4928.jpg is not a description.

Using attachment titles automatically

WordPress metadata fields have different purposes.

Writing “image of” every time

The medium is usually already exposed by assistive technology.

Writing for search engines

Keyword stuffing harms the usefulness of the alternative.

Ignoring context

The same image can require different treatment in different locations.

Making alt text too vague

Screenshot rarely explains why the screenshot matters.

Making alt text excessively detailed

Include what is relevant, not a complete inventory of the pixels.

Using AI output without review

Image models can miss context or invent details.

Trying to fit complex content into one attribute

Charts and infographics often need additional accessible content.

Related guides

• Auditing a WordPress Media Library for Accessibility
• OpenAI vs. Gemini for WordPress AI Features
• Reviewing AI-Edited Content: A Checklist

Related TheOneWP features

AI Alt Text Generator can generate alternative-text candidates from WordPress images using supported AI providers, making it useful for large libraries and high-volume publishing workflows.

AI SEO Fixer can assist with targeted content and SEO issues, including image-related checks where appropriate.

SEO Meta provides the surrounding SEO analysis layer, while accessibility decisions about an image should still be based on what that image communicates to the reader.

Final recommendation

If you remember only one principle about how to write good alt text, remember this:

Do not describe the image merely because it exists.

Communicate the information the image contributes.

For an informative image, write the shortest natural description that preserves the relevant meaning.

For a functional image, communicate the action or destination.

For a complex image, provide a concise alternative and make the detailed information available elsewhere.

For a decorative image, an empty alternative can be exactly correct.

And when AI generates the first draft, treat it as exactly that: a draft.

The most useful alt text comes from combining:

image content
+
page context
+
>editorial purpose
+
accessibility judgment

That is why there is no universal template, magic character count or automated description capable of replacing context.

Good alt text does not tell someone everything that can be seen.

It tells them what they need to know.