Diagnose the browser’s selected candidate against the image’s actual display slot; a responsive CSS width alone does not control file selection.
Inspect the selected resource
Select the image in browser developer tools and inspect its currentSrc, rendered width and available srcset candidates. Compare the chosen request in Network with the HTML declaration. Use a fresh page load at the target viewport rather than only shrinking a desktop window: an already downloaded large image can remain selected. Record device pixel ratio as well as CSS viewport width.
Check the slot description
For width-descriptor srcset, sizes describes the intended display width under different conditions. If a half-width card is described as a full-width slot, the browser can select a larger file than necessary. Compare the declared conditions with the real layout, including container padding and maximum widths. The goal is a truthful slot estimate, not forcing the smallest candidate at every screen size.
Verify the generated candidate files
Open the selected candidates independently. Confirm their dimensions, successful status and useful content. A theme may refer to a missing crop, or a media optimization layer may rewrite URLs inconsistently. If the required smaller size does not exist, correcting sizes alone cannot create it. Regenerate image derivatives through the responsible WordPress tooling after preserving originals and confirming its behavior on staging.
Retest crispness at realistic densities
Compare a narrow phone and a wider desktop layout using fresh requests. A high-density display may reasonably need more image pixels than its CSS width. Inspect product details and text embedded in artwork, not just byte size. Keep the existing meaningful alt text and intended crop while changing delivery; performance work should not make a product image misleading.
Apply the fix to the template owner
Correct the theme or block markup that generates the image, rather than editing one rendered page that will be overwritten. Check another image using the same component and a different aspect ratio. Purge relevant HTML and image derivatives if required by the delivery setup. Save the old markup or template revision so you can restore it if candidate selection or visual quality regresses.
Symptom-to-cause worksheet
| What you observe | What to investigate | Next check |
|---|---|---|
| Small card chooses wide candidate | Slot declaration may overstate width | Compare sizes with measured CSS width |
| Candidate request returns 404 | Derivative missing or URL rewrite wrong | Open original and candidate URLs separately |
| Smallest file appears blurry | Density or detail requirements ignored | Compare fresh loads on target displays |
Worked investigation scenario
This is an illustrative case, not a measured Velonic result. Imagine a card occupies half of an approximately 360 CSS-pixel content area, yet its sizes declaration advertises the full viewport. Measure the actual slot and correct the generating component. Reload at the target width in a clean session, inspect currentSrc, and compare image detail on the intended device. Do not require a particular candidate filename in every browser: the goal is a truthful declaration and appropriate quality, including higher-density displays.
Put it into practice
- Record currentSrc, slot width and pixel ratio.
- Test with a fresh load at each viewport.
- Fix generated template markup, not one DOM instance.
AI-assisted educational content prepared for the Velonic resource library. How these guides are prepared.