toolkit

Scenario · Content and search

Swap out an image

“Can you change this photo?” — a new headshot, a new hero, a replacement product shot.

Swapping out a single photo sounds trivial, and the two ways it goes wrong every time are the same: the replacement gets uploaded at full camera resolution, and the descriptive text carried over from the old image stays attached to a completely different picture. This optimizes the image before it goes anywhere near the site and checks that its description actually matches what's now on the page, catching both the slow-page and the quietly-wrong-caption version of this mistake.

What to ask for

Image optimizerOptimize images for the web locally, before upload — replaces Imagify / ShortPixel / EWWW / Smush and the performance reason for a CDN offload.Alt-text writerAlt-text generator — finds the content images on a page that are missing alt text, writes concise descriptive alt for each with a vision model, and on WordPress publishes it to the media library.Link & image checkerOn-page link & image checker — extracts every link and image a page declares, fetches each to its status code, and reports the dead ones (4xx/5xx broken links and broken images) plus the link-quality issues search engines and screen readers care about: non-descriptive anchor text, image-only links with no accessible text, malformed links, insecure external links, new-tab links missing rel=noopener, and excessive link counts.Before/after checkBefore/after verification for a change to a live page — the safety net for the small edit that doesn't justify a staging round-trip.ScreenshotsCapture multi-device screenshots of any URL from the command line — one PNG per device preset (iPhone → Desktop 4K), headless, on a Playwright core.

See it work

A real run of Image optimizer:

Image weight audit (image-optimizer) — https://toolkit-tests.pages.dev/content/image-optimizer-heavy.html

  1 images  ·  total 498.8 KB  ·  1 legacy-format  ·  1 over 200KB

  guideline (WebP · ≤100KB · descriptive alt): FAIL  1 not-WebP · 0/1 ≤100KB

  Worst offenders:
    498.8 KB  https://toolkit-tests.pages.dev/assets/hero.jpg [jpeg]

  json:   ./out/audit.json
  tsv:    ./out/audit.tsv
  text:   ./out/image-optimizer-image-optimizer.txt
  report: ./out/image-optimizer-image-optimizer.html

The captured report, exactly as a run hands it to a client —open the full report ↗

A one-image change, and the two failures are always the same: the replacement goes up at its original camera resolution, and the alt text carries over from the image that used to be there.

  1. Confirm which image and where. A file supplied without a target is the usual state of this ticket. If the same image appears in several places, decide whether all of them change.
  2. Optimise it before upload. Web-ready sizes, clean descriptive filename. A hero image straight from a photographer is routinely several megabytes, and dropping it in unprocessed is the single fastest way to make a page slower than it was this morning.
  3. Snapshot the page.
  4. [manual] Replace the image in the CMS. Swap the file, and change the alt text with it — the old alt describes the old picture, and leaving it is both an accessibility defect and a small lie about what is on the page. Publish and purge.
  5. Verify. Before/after check on the page: the pixel diff shows whether the swap moved the layout, which is common when the replacement has a different aspect ratio. Link and image check to confirm the new file actually loads — a mistyped path shows as a broken image, not an error. Capture across devices, because a differently-shaped image crops differently on mobile.
  6. Check the alt text landed. The alt-text audit reports the page’s coverage; a swap that left the attribute empty is the most common regression here.

Aspect ratio is the hidden cost

A same-size swap is invisible. A portrait replacing a landscape re-flows everything around it, and on a page built with a visual builder that can push content below the fold or collapse a column entirely. The pixel diff in step 5 is what turns that from a client discovery into a caught one.

What this does not cover

Licensing and identity. Nothing here can tell you whether the practice has the right to publish this photo, whether the person in it consented, or whether it is the right person — a swapped headshot passes every check while showing the wrong doctor. Before-and-after case images are a different job with different rules; this is for ordinary site imagery.

← All scenarios