A reader opens your “ChatGPT custom GPT setup” tutorial. Step 3 says “open the Configure tab and fill in the Knowledge section.” The screenshot shows a 2024 layout where that section was still called Upload files. The reader’s screen says Knowledge, the field positions differ, and they stall — unsure if they are even in the right place. Same product, renamed labels, moved fields. The text was right when you wrote it; the UI moved and the image didn’t follow.
Fastest fix: stop hand-editing images. (1) Inventory every screenshot by platform so a redesign maps to a known list of articles. (2) Batch-replace the highest-traffic affected articles first. (3) Then put captures under a script (Playwright) so the next redesign regenerates them automatically instead of silently rotting. Detection, batch-update, and a capture pipeline — in that order.
Screenshots rot on a schedule you don’t control. Every UI redesign breaks every tutorial that referenced the old version, and most teams have no refresh process, so images drift from “helpful” to “actively misleading” without anyone noticing until a reader complains.
Which bucket are you in
| Symptom | Likely cause | Go to |
|---|---|---|
| One platform’s articles all look old after a redesign | No post-redesign audit | Cause 1, Step 1 + 2 |
| You can’t list every screenshot of a given product | No central index | Cause 2, Step 1 |
ls doesn’t tell you which images are old | No version-stamped filenames | Cause 3, Step 3 |
Alt text is "ChatGPT screenshot" everywhere | Generic alt | Cause 4, Step 4 |
| Text and image describe different steps | Loose text-image alignment | Cause 5 |
| Staleness only surfaces from complaints | No flagging mechanism | Cause 6, Steps 5 + 6 + 7 |
Common causes
Ordered by hit rate, highest first.
1. Platform redesigned, screenshots never re-audited
A vendor ships a redesign on a Tuesday. You have 40 articles referencing that UI. Nobody scheduled an audit, so all 40 silently go stale that day. AI products move fast: ChatGPT, Claude, Gemini, and Cursor all reshuffled settings menus and renamed sections during 2025-2026, so a screenshot can be wrong within months of capture.
How to spot it: pick a recently redesigned platform, sample 5 articles that reference its UI, and compare against the live product today. If 3 or more show the old UI, no audit happened.
2. Screenshots aren’t centrally indexed
Each article keeps its images inline (or in src/content/.../assets/<slug>/) with no central list. When the UI changes, there is no single “all screenshots of product X” inventory to work from.
How to spot it: try to list every screenshot of one platform across the site. If the only way is a manual grep through hundreds of files, you have no index.
3. Filenames have no version stamp
Images are named screenshot1.png or chatgpt.png. Nothing in the name says whether it was captured last month or 18 months ago.
How to spot it: ls public/screenshots/ (or your assets dir). If filenames carry no date or version marker, every image is effectively undated.
4. Alt text is generic, not descriptive
alt="ChatGPT screenshot" helps nobody. WCAG 2.2 success criterion 1.1.1 (Level A) requires a text alternative that conveys the image’s purpose, not just that an image exists. Generic alt also fails your own audits, since it gives no clue what the image was supposed to show.
How to spot it: grep for alt="screenshot or alt values ending in a bare product name. Any hit is too generic.
5. Text doesn’t reference the screenshot specifically
The text says “click submit” and a screenshot sits somewhere below it. When the button moves, text and image diverge with no anchor tying them together, so you can’t tell which step a stale image belongs to.
How to spot it: read a tutorial top to bottom. If you can’t trivially say “this image illustrates step N,” the alignment is loose.
6. Nothing flags screenshots as stale
No PR check, no lint, no scheduled review. Staleness only surfaces when a reader posts a complaint.
How to spot it: when did you last refresh a screenshot proactively, not in response to a complaint? If the answer is “I don’t remember,” there is no process.
Shortest path to fix
Steps 1-2 find and queue the damage. Steps 3-4 make age visible and useful. Steps 5-7 stop it recurring — Step 7 is the durable fix.
Step 1: Inventory screenshots by platform
Use the correct markdown-image pattern. The token that opens an image is ![, so escape the bracket:
# Every article that embeds a markdown image
grep -rlE '!\[' src/content/articles/ | head -40
# Pull image paths + alt out of markdown images
grep -rnoE '!\[[^]]*\]\([^)]+\)' src/content/articles/
# Also catch JSX <img> / <Image> components, which the markdown regex misses
grep -rnE '<(img|Image)\b' src/content/articles/Bucket the matches by platform (chatgpt-*, claude-*, gemini-*, cursor-*, midjourney-*). The result is the per-platform index you were missing in Cause 2. When a platform redesigns, you already know which articles to touch.
Step 2: Prioritize by traffic, then by redesign recency
You can’t refresh everything at once, so refresh what readers actually hit.
Highest priority:
- High-impression article (check Search Console / analytics)
- Platform redesigned in the last 6 months
Lower priority:
- Low-traffic article
- Platform UI stable for 2+ yearsSort the per-platform list by impressions, then work top-down for any platform that changed recently.
Step 3: Version-stamp filenames
Rename images so age is visible from the filename:
Before: chatgpt-ui.png
After: chatgpt-ui-2026-06.png
Or tag the redesign generation:
chatgpt-ui-v3-redesign.pngNow ls tells you what’s old at a glance. On a refresh, write a new file (chatgpt-ui-2026-12.png) and update the article reference; the old file stays as a dated snapshot of how the UI used to look.
Step 4: Make alt text specific
<!-- Bad: says nothing, fails WCAG 1.1.1 -->
<img src="..." alt="ChatGPT screenshot" />
<!-- Good: states what the image proves, ~125 chars -->
<img
src="..."
alt="ChatGPT GPT editor, Configure tab, Knowledge section with two files attached (2026-06 UI)"
/>Keep alt around 125 characters — most screen readers pause near that length — and lead with the image’s purpose, not “image of” or “screenshot of.” Specific alt serves readers on slow connections, screen-reader users, and your own future audits at the same time. If you have generic alt at scale, fix it in bulk first; see Many images missing alt text.
Step 5: Add a quarterly audit checklist
# screenshot-audit-Q2-2026.md
## ChatGPT articles (15)
- [ ] chatgpt-custom-gpt-setup — captured 2024-08, redesign 2026-03 -> UPDATE
- [ ] chatgpt-memory-feature — captured 2026-04, current -> OK
## Claude articles (12)
- [ ] claude-projects-setup — captured 2025-11, check label changesBudget roughly 10 minutes per article for re-capture and put it on a quarterly cadence.
Step 6: Record the capture date in MDX
import ChatGPTUI from "./assets/chatgpt-ui-2026-06.png";
{/* captured: 2026-06, ChatGPT GPT editor v3 */}
<img src={ChatGPTUI} alt="ChatGPT Configure tab, Knowledge section (2026-06)" />A small CI script can then parse those captured: comments and list any image older than your threshold (for example 9 months) as “needs review,” turning invisible rot into a visible checklist item.
Step 7 (durable fix): generate screenshots from a script
The only way to stop screenshots rotting permanently is to stop drawing them by hand. Drive the real UI with Playwright and capture the image from a checked-in script:
// screenshots/chatgpt-gpt-editor.spec.js
import { test } from '@playwright/test';
test('GPT editor Configure tab', async ({ page }) => {
await page.goto('https://chatgpt.com/gpts/editor');
// ...sign in via stored auth state, navigate to the Configure tab...
await page.getByRole('tab', { name: 'Configure' }).click();
await page.screenshot({
path: 'src/content/.../assets/chatgpt-ui-2026-06.png',
fullPage: false,
});
});Re-run the script and every image reflects the current UI — if a button moves or a section is renamed, the regenerated capture shows it, with no manual hunt for stale files. Two ways to layer detection on top, both verified current as of June 2026:
- Visual diff in CI. Playwright’s
expect(page).toHaveScreenshot()(or Percy / Applitools) compares each capture against a baseline and fails the build when pixels move, so a vendor redesign turns into a red check instead of a reader complaint. - Playwright MCP. An agent can drive the same browser and regenerate doc screenshots from a prompt, which is useful for one-off refreshes between full script runs.
For products without a public/loginable URL (or behind strict bot rules), keep the manual cadence from Steps 5-6 — but automate everything you can.
How to confirm it’s fixed
- Open the refreshed article side by side with the live product and walk each numbered step. Every label, tab, and field named in the text appears in the screenshot.
grep -rnE '!\[|<(img|Image)\b' <article>returns only version-stamped, current-dated assets.- Every screenshot has alt text that names what it shows (no
alt="screenshot"). - If you added Step 7: the screenshot script runs green locally, and the visual-diff check is wired into CI so the next redesign fails the build.
Prevention
- Version-stamp filenames so age is visible from
ls. - Keep the per-platform article index current so any redesign maps straight to an audit list.
- Run a quarterly audit and budget time for it.
- Record
captured:dates in MDX plus a CI script that flags images past your age threshold. - Write specific, purpose-led alt text on every screenshot (WCAG 1.1.1).
- Script your captures with Playwright and add a visual-diff gate so a redesign breaks the build, not the reader’s trust.
- When a platform redesigns, batch-update affected articles within two weeks — don’t wait for complaints.
FAQ
How often do AI-tool UIs actually change? Often enough that a quarterly audit is the floor, not the ceiling. ChatGPT, Claude, Gemini, and Cursor each shipped settings-menu reshuffles and section renames during 2025-2026. Treat any screenshot of a fast-moving AI product as suspect after about two quarters.
Do I have to retake every screenshot after a redesign? No. Prioritize by traffic (Step 2). A redesign that renames one label may only affect the steps that reference that label; a full layout change affects everything. Diff the live UI against your captures and update what genuinely moved.
Is automating screenshots with Playwright worth it for a small site? If you have more than a handful of UI tutorials, yes — the script pays for itself the first time a platform redesigns, because regeneration replaces a manual hunt across every article. For a few pages, the manual cadence in Steps 5-6 is enough.
What’s the ideal alt-text length for a screenshot? Around 125 characters. Screen readers commonly pause near that length, and it forces you to state the image’s purpose instead of narrating every pixel. If a screenshot genuinely needs more, describe it in surrounding prose or a caption and keep the alt short.
The screenshot is current but readers still get lost — why? Likely Cause 5: the text doesn’t anchor to the image. Reference the exact label in the step (“click Configure”), keep the screenshot directly under the step it illustrates, and crop to the relevant region so the reader isn’t scanning the whole UI.