WordPress 7.1 adds a decorative toggle to the Image block. The control can improve editing accuracy when an image adds no information, but it can also make meaningful screenshots, product images, diagrams, charts, and linked images silent if editors use it to clear an alt-text warning. The decision must follow the image's purpose in that specific page context.
Use this for publishers, ecommerce teams, universities, nonprofits, agencies, documentation writers, and anyone building reusable WordPress patterns with images.
Quick answer
Decide what the image contributes beside the surrounding text. Mark it decorative only when removing it would not remove information, instruction, identity, action, or destination. Write concise alt text when the image carries meaning. For charts, screenshots, and diagrams, provide the essential takeaway nearby. For linked images, make sure the accessible name describes the link destination or action.
What to check first
- Classify each image as informative, functional, complex, text-bearing, product, identity, redundant, or decorative in its page context.
- Check the Image block decorative state, alt attribute output, caption, link destination, and nearby explanation.
- Test reusable patterns and synced content because the same asset can serve a different purpose on another page.
- Inspect product cards, logo links, screenshots, charts, galleries, sliders, and background-like editorial images.
- Review rendered HTML with images enabled and disabled, then listen to the section with a screen reader.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Classify purpose in the current page instead of reusing an asset-wide answer. | Classify each image as informative, functional, complex, text-bearing, product, identity, redundant, or decorative in its page context. | Decorative images render with empty alt text and do not create noisy announcements. |
| Use the decorative toggle only when the image contributes no information or action. | Check the Image block decorative state, alt attribute output, caption, link destination, and nearby explanation. | Informative images communicate their purpose without keyword stuffing. |
| Write concise contextual alt text for informative and functional images. | Test reusable patterns and synced content because the same asset can serve a different purpose on another page. | Linked images have useful destination or action names. |
| Add nearby real-text explanations for charts, diagrams, and instructional screenshots. | Inspect product cards, logo links, screenshots, charts, galleries, sliders, and background-like editorial images. | Reusable patterns remain correct in every published context reviewed. |
Why this usually happens
- An image's filename and library alt text do not reveal its purpose in every placement.
- Reusable patterns can carry a decorative choice into a context where the image becomes informative.
- SEO checklists sometimes encourage keyword-filled alt text even when an empty alt is the correct accessibility choice.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
context,purpose,decorative,alt_or_text
section divider,visual rhythm,yes,empty alt
settings screenshot,instruction,no,describe the selected control
traffic chart,trend,no,nearby summary plus concise alt
logo link,home action,no,accessible link name
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Divider flourish | Adjacent text contains all meaning | Decorative with empty alt |
| Diagnostic screenshot | Callouts explain a setting | Concise alt plus nearby instructions |
| Product image | Image distinguishes purchasable item | Meaningful product-specific alt |
| Linked logo | Link returns to home | Accessible name describes destination |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Classify purpose in the current page instead of reusing an asset-wide answer.
- Use the decorative toggle only when the image contributes no information or action.
- Write concise contextual alt text for informative and functional images.
- Add nearby real-text explanations for charts, diagrams, and instructional screenshots.
- Audit synced patterns and high-traffic templates after upgrading to WordPress 7.1.
Decision rule
If removing the image would remove meaning, identification, instruction, or an action, it is not decorative. If all meaning already exists in nearby text and the image only changes visual rhythm, an empty alt is usually appropriate.
Production verification checklist
- Decorative images render with empty alt text and do not create noisy announcements.
- Informative images communicate their purpose without keyword stuffing.
- Linked images have useful destination or action names.
- Reusable patterns remain correct in every published context reviewed.
Field notes
- Do not describe every pixel; communicate the information needed for the surrounding task.
- Avoid phrases such as image of unless the medium itself matters.
- Keep chart data or conclusions in real text where readers can search, copy, and translate it.
Questions teams ask during testing
Can this be tested on staging?
Start on staging with production-like versions, roles, data volume, browser behavior, cache, and integrations. Finish with one controlled production fixture when the result depends on the real CDN, email route, worker clock, crawler response, or browser storage.
What evidence should be retained?
Keep the smallest useful evidence set: exact versions, stable IDs, UTC timestamps, sanitized request or log excerpts, expected result, actual result, decision, and final verification. Redact customer data, cookies, secrets, order keys, and full advertising identifiers.
When should the change be rolled back?
Roll back when a revenue, privacy, accessibility, security, publishing, or lead path fails and the cause cannot be isolated inside the approved maintenance window. Preserve the failed fixture before rollback so the next attempt starts with facts.
Mistakes to avoid
- Do not change several production layers at once. Preserve the failing evidence and isolate one variable per test.
- Do not treat a successful request, quiet log, or correct screenshot as proof that the complete user outcome is correct.
- Do not leave debug logs, test records, broad credentials, temporary roles, or browser overrides active after verification.
- Do not close the work without recording versions, fixture IDs, UTC timestamps, owner, result, and rollback point.
What to tell the client or owner
Give the owner the affected versions, exact fixture, stable IDs, UTC timeline, before and after evidence, decision, rollback point, unresolved risks, and next review date.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, audit WordPress image accessibility.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references