Add missing and inconsistent alt attributes to homepage images on WordPress.org for improved accessibility

[ibrahimriaz]

During an accessibility review of the WordPress.org homepage, I found several images missing alt attributes or using non-descriptive text. This creates accessibility barriers for screen reader users and reduces overall usability.

According to WCAG 2.1 – Non-text Content (1.1.1) and WordPress’s accessibility standards, every image should have a meaningful alt text if it conveys information. Purely decorative images should use an empty alt (alt="") and role="presentation".

Examples Observed

1. Hero Section

<img src="https://wordpress.org/files/2024/04/brush.png" alt />

Issue: The image is purely decorative but lacks the appropriate accessibility attributes. It should have an empty alt attribute and a role="presentation" to indicate that it conveys no meaningful content.

Suggested fix: Add role="presentation" to ensures screen readers ignore the image, improving accessibility for visually impaired users.

<img src="https://wordpress.org/files/2024/04/brush.png" alt="" role="presentation" />

2. Whats New Section

<img src="https://wordpress.org/files/2024/10/whats-new-visual-6-7.png" alt />

Issue: Missing alt attribute.
Suggested fix: Alt text should describe the image.

<img src="https://wordpress.org/files/2024/10/whats-new-visual-6-7.png" alt="What's New Visual in WordPress" />

3. Showcase Section

<img src="https://wordpress.org/files/2023/10/showcase-top-row-full.png" alt />
<img src="https://wordpress.org/files/2023/10/showcase-middle-row.png" alt />
<img src="https://wordpress.org/files/2023/10/showcase-bottom-row.png" alt />

Issue: Missing alt text for showcase images.
Suggested fix: Alt text should describe the context.

<img src="https://wordpress.org/files/2023/10/showcase-top-row-full.png" alt="Top Showcase Image" />
<img src="https://wordpress.org/files/2023/10/showcase-middle-row.png" alt="Middle Showcase Image" />
<img src="https://wordpress.org/files/2023/10/showcase-bottom-row.png" alt="Bottom Showcase Image" />

Suggested Improvements:
Audit all <img> elements on the WordPress.org homepage.

Add appropriate alt attributes:
Descriptive text for informative images.
alt="" + role="presentation" for decorative ones.

Review block-rendered images (wp-block-image, wp-block-media-text, etc.) for consistent accessibility output.
Optionally consider automated linting for missing alt attributes during the build process.

Benefits

• Improves compliance with WCAG 2.1 AA and WordPress Accessibility Coding Standards.
• Enhances user experience for assistive technology users.
• Supports SEO and improves overall content clarity.
• Reinforces WordPress’s accessibility-first approach.

[baikare.sandeep007]

There is alt missing on the new image which is added as banner for WCEU 2026

<img src="https://wordpress.org/files/2026/05/dotorg_banner_wceu-6.png" alt="">

[baikare.sandeep007]

It looks like the alt is missing throughout the images, including showcase images as well. not sure we have to fix it at wp-block-image block level or alt image is not set for all images.

[matejwpm]

Images had empty alt — alt probably wasn’t set on the blocks / in the Media Library. If an Image block has no alt, use the Media Library alt.

[softglaze]

I've opened a PR for this: ​https://github.com/WordPress/wporg-main-2022/pull/723

Before writing the patch I went through all 20 <img> tags in source/wp-content/themes/wporg-main-2022/patterns/home.php and checked each one against the live homepage. A few things came up that change how this ticket reads.

No alt attributes are actually missing. Every image in the pattern already has an alt attribute on it. The problem is that some of them are empty on images that carry meaning, so those images get dropped from the accessibility tree instead of being announced.

The part I think has been blocking progress here is that the empty values are hardcoded in the pattern file, not unset in the Media Library. This is different from what comment:4 suggests. home.php writes alt="" straight into the wp:image block markup, so editing the alt text on the media items would not change anything on the rendered homepage. The fix has to go into the pattern file itself.

The two images named in the description are no longer on the homepage. Neither whats-new-visual-6-7.png nor dotorg_banner_wceu-6.png is there now. The ones that actually need attention are the Design, Build and Extend feature images plus the two "See what's new" collages.

The hidden "Core Features 6.9" group reuses the same attachment IDs as the visible 7.0 group, so the same image was appearing twice with different alt values. The patch updates both groups so each shared image reads the same way in either place. That works out to five unique images across eight <img> instances.

I kept the new strings translatable. The alt text already in this file, meaning the six brand logos and the community photo, is wrapped in esc_attr_e( '...', 'wporg' ), so the new descriptions follow the same convention instead of being hardcoded English. All 15 non-empty alt attributes in the file are consistent on that now, and php -l passes on the result.

On the two suggestions in the description, I did not add role="presentation". On an image with alt="" it is redundant, because the HTML spec already maps those out of the accessibility tree. I also avoided the "Top Showcase Image" style strings, since those describe where an image sits rather than what it shows, and those three showcase-*-row images are decorative anyway. They keep alt="", which is correct.

The images left with alt="" on purpose are brush.png (39758), the three showcase-*-row images (22644, 22641, 22642), and the WCUS banner logo (52112), which sits next to a paragraph that already says the same thing.

One more thing worth flagging, though it isn't an accessibility problem. The third feature column is headed "Extend" and the copy under it is about plugins, but the image in that column is wporg-69-publish.png, which shows a finished website and nothing plugin related. I wrote the alt text to describe the image as it actually is, since that is what a screen reader user gets. If the image is meant to match the copy, that is a content change and probably wants its own ticket.

Testing steps are in the PR. Since alt text only affects the accessibility tree and the page renders identically either way, the thing to check is the computed accessible name in the browser accessibility inspector rather than a visual comparison.