How To Fix Decorative Images With Descriptive Alt in Classic PHP Themes

Why This Issue Happens In Classic PHP Themes

The **Decorative image with descriptive alt** problem appears when an image that adds no meaningful content is given alt text that screen readers will announce. In classic WordPress theme PHP templates, this often happens because developers reuse one image helper everywhere, pull attachment metadata automatically, or hard-code alt text into template parts without checking whether the image is actually informative.

For accessibility, decorative images should usually have an empty alt attribute: `alt=""`. That tells assistive technology to skip the image so users are not forced to hear redundant or distracting descriptions. If a flourish, divider, background-like icon, or ornamental thumbnail has descriptive alt text, the page becomes noisier than it needs to be.

Classic themes are especially prone to this because image markup is often spread across `header.php`, `footer.php`, `page.php`, `single.php`, partials, and custom loops. The result is inconsistent decisions about when an image is content and when it is purely visual.

How To Identify A Decorative Image With Descriptive Alt

Before changing template code, decide whether the image communicates meaning.

Use this simple rule:

If removing the image would not change the meaning of the page, it is probably decorative.
If nearby text already conveys the same information, the image is often decorative.
If the image is used only for mood, spacing, ornament, branding polish, or visual balance, it is decorative.
If the image functions as a link, product photo, author headshot, diagram, chart, or key illustration, it is not decorative.

In classic PHP templates, the issue commonly shows up in these scenarios:

Section dividers rendered with `img` tags
Decorative icons placed next to headings or buttons
Hero embellishments with alt text copied from the media library
Repeated post thumbnail patterns where the image is visually present but context is already fully covered by linked text
Theme options that output a logo variant, flourish, or badge with a descriptive alt even when it adds no content

Common Failure Modes In Classic Theme PHP Templates

Automatically Reusing Attachment Alt Text Everywhere

A frequent pattern in older themes is to fetch the attachment alt and print it for every image, regardless of context.

<?php
$alt = get_post_meta($image_id, '_wp_attachment_image_alt', true);
echo wp_get_attachment_image($image_id, 'full', false, array(
    'alt' => $alt,
));
?>

This is not always wrong, but it becomes a problem when the same attachment is decorative in one template and informative in another. Media library alt text is not context-aware.

Hard-Coded Descriptive Alt On Decorative Assets

Some classic themes include markup like this:

<img src="<?php echo esc_url( get_template_directory_uri() . '/assets/divider.png' ); ?>" alt="Decorative leaf divider">

That sounds descriptive, but the divider does not convey meaning. A screen reader user gains nothing from hearing it.

Template Parts Used In Multiple Contexts

A reusable partial may output an image with descriptive alt for one layout, then get included in another layout where that same image becomes ornamental.

Examples include:

card components

n- banner partials

badge or ribbon includes
icon-text list items

When the PHP partial has no context flag, it cannot decide correctly.

Theme Logos And Brand Graphics Misclassified

A logo can be informative or decorative depending on placement.

In a site header, the logo often identifies the site and may need meaningful alt.
In a decorative footer flourish or repeated brand strip, it may be better treated as decorative if adjacent text already names the site.

The mistake is assuming every branded image needs descriptive alt text.

What WCAG Is Trying To Prevent

The issue maps to the broader requirement that text alternatives should serve equivalent purpose, not create extra chatter. Decorative images should be ignored by assistive technologies rather than announced with text that adds no value.

Useful references:

How To Fix Decorative Image With Descriptive Alt In PHP Templates

Use Empty Alt For Truly Decorative Images

If the image is decorative, output an empty alt attribute.

<img src="<?php echo esc_url( $image_url ); ?>" alt="">

If you are using `wp_get_attachment_image()`, override the attachment alt when the template context is decorative.

<?php
echo wp_get_attachment_image($image_id, 'full', false, array(
    'alt' => '',
));
?>

This is the most direct fix for the **Decorative image with descriptive alt** failure.

Avoid Omitting The Alt Attribute Entirely

Do not remove the `alt` attribute from an `img` element. For HTML images used decoratively, the right pattern is an empty alt, not a missing alt.

Correct: `alt=""`
Usually wrong: no `alt` attribute

Pass Context Into Template Parts

If a template part is reused across layouts, make the image role explicit.

<?php
get_template_part('template-parts/hero', null, array(
    'image_id' => $image_id,
    'decorative' => true,
));
?>

Then inside the template part:

<?php
$decorative = !empty($args['decorative']);
$image_id = !empty($args['image_id']) ? (int) $args['image_id'] : 0;
$alt = $decorative ? '' : get_post_meta($image_id, '_wp_attachment_image_alt', true);

echo wp_get_attachment_image($image_id, 'full', false, array(
    'alt' => $alt,
));
?>

This approach is cleaner than trying to infer meaning from the attachment alone.

Keep Informative And Decorative Uses Separate

If one asset serves both decorative and informative roles in different places, do not rely on a single universal output helper with one alt rule.

Instead:

Create one function for decorative rendering.
Create one function for informative rendering.
Call the appropriate helper from each template.

Example:

<?php
function theme_render_decorative_image($image_id, $size = 'full') {
    echo wp_get_attachment_image($image_id, $size, false, array(
        'alt' => '',
    ));
}

function theme_render_informative_image($image_id, $size = 'full', $fallback_alt = '') {
    $alt = get_post_meta($image_id, '_wp_attachment_image_alt', true);
    if ($alt === '') {
        $alt = $fallback_alt;
    }

    echo wp_get_attachment_image($image_id, $size, false, array(
        'alt' => $alt,
    ));
}
?>

When The Right Fix Is To Remove The Image Tag Entirely

Sometimes the decorative effect should not be an `img` element at all.

If the visual is purely presentational, consider using CSS background images, masks, borders, gradients, or pseudo-elements instead of image markup. That can simplify accessibility because the decoration no longer appears in the document as content.

This is often a better fit for:

ornamental separators
corner flourishes
repeated texture elements
non-essential badge overlays
background accents behind headings

Be careful, though: if the graphic carries meaning, moving it into CSS can hide useful content from users who need text alternatives.

Decision Guide By Use Case

Scenario	Decorative Or Informative	Recommended Fix
Divider between content sections	Decorative	Use `alt=""` or move to CSS
Icon next to heading where text already explains meaning	Decorative	Use `alt=""`; consider inline SVG with `aria-hidden` if appropriate
Product image on a product page	Informative	Keep meaningful alt tied to product context
Site logo in primary header with no adjacent site name	Informative	Use meaningful alt such as site name
Repeated logo in a decorative footer strip	Usually decorative	Use `alt=""` if nearby text already identifies the brand
Hero flourish behind headline	Decorative	Prefer CSS or empty alt
Featured image in a card where linked title fully identifies the post and image adds no extra meaning	Context-dependent	Often decorative; test with actual UX goals

Practical Audit Steps For Older WordPress Themes

Check High-Risk Template Files First

Start with files that commonly output images:

`header.php`
`footer.php`
`front-page.php`
`home.php`
`single.php`
`page.php`
`archive.php`
`template-parts/*.php`
custom walker or helper files

Search for these patterns:

`<img`
`wp_get_attachment_image(`
`the_post_thumbnail(`
`_wp_attachment_image_alt`

Review Repeated UI Elements

The highest-value fixes are often the repeated elements that appear across the site.

Focus on:

decorative icons in buttons or feature lists
separators and flourishes
card thumbnails used in post grids
social or metadata icons
theme option graphics

A single bad partial can create hundreds of accessibility errors across templates.

Test With Real Page Context

Do not decide image purpose from markup alone. Open the rendered page and ask:

Does the image communicate information not already in text?
Is it functional?
Would a non-visual user miss anything if it were skipped?

If the answer is no, descriptive alt is probably the wrong output.

Safe Refactoring Patterns

Add An Explicit Decorative Flag

One of the safest improvements for classic themes is to add an explicit boolean for decorative usage.

Benefits:

reduces guesswork
avoids global behavior changes
makes reviews easier
preserves meaningful alt where needed

Do Not Blank Alt Globally

A risky fix is to strip alt text from all theme images after finding a decorative-image issue. That creates a worse accessibility problem by erasing text alternatives from genuinely meaningful images.

Avoid broad changes like:

add_filter('wp_get_attachment_image_attributes', function($attr) {
    $attr['alt'] = '';
    return $attr;
});

That is too blunt unless it is tightly scoped to a known decorative context.

Use Code Review Criteria

When updating templates, apply these checks:

Is the image content, function, or decoration?
Is the alt text context-specific?
If decorative, is the output `alt=""`?
If informative, does the alt convey purpose without repeating nearby text unnecessarily?

How Different Audiences Should Fix It

For Theme Developers

Your best fix is context-aware rendering. Do not trust media library alt text as a universal answer. Build helpers or template arguments that distinguish decorative from informative output.

For Site Owners Using A Custom Classic Theme

If you cannot rewrite templates yourself, ask your developer to audit repeated image components first. That usually removes the largest number of **Decorative image with descriptive alt** errors quickly.

For Agencies Maintaining Legacy Themes

Standardize image output rules across projects:

decorative images get empty alt
informative images get contextual alt
repeated components accept an explicit accessibility setting
design QA includes screen reader noise reduction, not only missing-alt checks

Final Fix Recommendation

The right way to fix **Decorative image with descriptive alt** in classic theme PHP templates is to treat image alt as a context decision, not a media-field default. In practice, that means identifying decorative uses, outputting `alt=""` for those cases, and keeping meaningful alt only where the image actually communicates content or function.

If you are maintaining an older WordPress theme, start with shared partials and helper functions. That is where the biggest accessibility wins usually are, and it gives you a cleaner long-term pattern instead of patching one template at a time.