Screenshot audit and refresh program (master)

[superdav42]

Summary

A repo-wide audit of every screenshot in static/img/ and every /img/... reference in docs/ revealed widespread problems:

• 147 image files are tracked, but only 98 unique paths are referenced from docs/ — and many of those single paths are reused for dozens of unrelated concepts.
• At least 32 files are byte-for-byte duplicates of each other (same MD5 hash) saved under different names.
• At least 4 walkthroughs (Zapier, Stripe, PayPal, Customer account page) currently use a single screenshot as a placeholder for every step.

This issue tracks the program of work. Each focused area has its own child issue (linked below).

Goal

Every screenshot in the docs should:

1. Show the actual UI being described.
2. Be unique per concept (no recycled placeholder).
3. Be cropped/sized to highlight the relevant control, not buried in chrome.
4. Be reasonably small (file size + image dimensions) so the docs site stays fast.

---

Capture environment

The dev WordPress used to take new screenshots:

• URL: http://wordpress.local:8080
• Username: admin
• Password: admin
• Plugin: Ultimate Multisite (current main build) active on the network.

Open the login page at http://wordpress.local:8080/wp-login.php, sign in, then go to My Sites → Network Admin → Ultimate Multisite to reach every screen referenced in the docs.

If wordpress.local:8080 is not reachable from your machine, ask in the issue thread for access (a staging clone can be provided).

Capture standards

Rule	Value
Browser window for screen captures	1280 × 800 (consistent across the whole doc set)
Device pixel ratio	1× (use a normal/external monitor, not a Retina-only display)
Theme	WordPress default admin colour scheme, no admin-bar customisations
Browser zoom	100% — confirm with Ctrl/Cmd + 0 before each shot
File format	PNG, 8-bit RGB, non-interlaced
Max longest edge	1568 px — anything larger gets auto-downscaled and wastes bytes
Min readable text height	≥ 12 px after any cropping
Crop policy	Crop tightly to the panel/section being described. Do not capture the whole admin chrome unless the doc text refers to the sidebar / admin bar.
Annotations	None by default. If the doc text already describes the control, the screenshot should speak for itself.
File name	Keep the existing filename when replacing. For new shots, use kebab-case-area-element.png and place under static/img/admin/, static/img/config/, or static/img/installation/ to match siblings.
Optimisation	Run pngquant --quality=70-90 --skip-if-larger -f -o out.png in.png (or oxipng -o 4 in.png) before committing. Target < 200 KB unless the screen genuinely needs more detail.

Recommended capture tools

• Linux: Flameshot (flameshot gui), GNOME Screenshot, or gnome-screenshot -w for a window.
• macOS: Cmd + Shift + 4, then space, then click the browser window. To remove window shadows: defaults write com.apple.screencapture disable-shadow -bool true.
• Cross-platform: Playwright/Chromium headed: open http://wordpress.local:8080/wp-admin/network/admin.php?page=wp-ultimo, resize window to 1280 × 800 via the OS or DevTools device toolbar, then capture.

For full reproducibility you can drive the capture from a tiny Playwright script (1280 × 800 viewport, deviceScaleFactor 1) — useful if you’re doing many at once. Ask in this issue if you want a starter script.

Filename hygiene

• Never paste a screenshot with macOS’s default name Screenshot 2026-… PM.png into commits — rename to the target path first.
• On macOS, the AM/PM in the default filename contains a U+202F narrow no-break space which breaks many tools. Rename to ASCII before committing.

---

Audit findings

A. Exact byte-identical duplicates (same file content, different names)

These were verified with md5sum. The recycled name almost always implies a screenshot that was never actually captured.

MD5	Affected files	Tracking issue
023edc1399…	static/img/config/product-{custom-domains,disk-space,hide-credits,plugins,post-types,reset-limitations,site-templates,themes,upgrades}.png (9 files, all 28 236 B)	#69
1dce0a089f…	static/img/admin/network-dashboard-{activity-stream,first-steps,full,news,right-now,summary}.png + static/img/installation/network-dashboard.png (7 files, all 125 540 B)	#70
28184a7caf…	static/img/admin/settings-payments-{bottom,gateways-2,options}.png (3 files)	#71
1c1ac4f60f…	static/img/config/period-selection-field-{options,settings}.png (2 files)	#72
74f697dd4b…	static/img/installation/plugin-activated.png, static/img/installation/wizard-welcome.png	#75
b9c1d601bb…	static/img/admin/um-dashboard-bottom.png, static/img/admin/um-dashboard-stats.png	#76

Total: 32 files that should collapse to ~10 distinct shots.

B. One screenshot reused for many concepts inside one doc (placeholder pattern)

Doc file	Distinct concepts illustrated	Image used	Tracking issue
docs/user-guide/integrations/zapier.md	14 (Zapier dashboard, app search, trigger picker, auth modal, UM API settings, credentials, payment_received event, test step, action setup …)	webhooks-list.png — wrong screen for every step	#65
docs/user-guide/payment-gateways/stripe.md	13 (UM active gateways, inline card field, Checkout redirect, API keys, Stripe Dashboard, test-data toggle, Stripe webhooks, listener URL, endpoint paste …)	settings-payment-gateways.png — wrong screen for most steps	#66
docs/user-guide/payment-gateways/paypal.md	5 (UM active gateways, API credentials, PayPal account settings, PayPal API integration, generated credentials)	settings-payment-gateways.png — wrong screen for the PayPal-side steps	#67
docs/user-guide/client-management/account-page.md	16 (account menu, account overview, plan summary, Site Limits, Billing Address, update form, change template button, switch confirmation, Add Domain, DNS instructions, change password form, Danger Zone …)	Recycled mix of dashboard.png, customers-list.png, domains-list.png from the network admin — but the doc is about the customer-facing subsite account page.	#68

C. Cross-doc placeholder reuse (heaviest offenders)

Image	Times referenced	Used for	Tracking issue
/img/admin/webhooks-list.png	35	Mostly Zapier walkthroughs	#65, #74
/img/config/settings-payment-gateways.png	34	PayPal + Stripe walkthroughs	#66, #67
/img/admin/memberships-list.png	17	Memberships list, but reused for cancel / downgrade / upgrade flows where the actual screens differ	(future)
/img/config/checkout-form-step.png	16	Re-used for every field type configuration	#72, #73
/img/config/settings-taxes.png	15	VAT add-on walkthrough	(future)
/img/config/discount-codes-list.png	14	Multiple distinct discount-code editor screens	(future)

---

Workflow per child issue

For each linked child issue:

1. Open wordpress.local:8080, log in as admin / admin.
2. Re-create / open the screen described in the doc text.
3. Capture per the standards table above (1280×800, tight crop, < 200 KB).
4. Save to the exact path listed in the issue (overwrite existing file — keep the filename).
5. If the issue says "split into N shots", add the new filenames to static/img/.../ and update the markdown references in the listed docs/... file accordingly.
6. Run npm start, visit the doc page, and confirm every shot renders and matches the surrounding text.
7. Commit with a message like docs(screenshots): refresh <area> per issue #<N> and open a PR referencing the issue.

Child issues

• Screenshots: Zapier integration walkthrough (14 placeholders) #65 — Screenshots: Zapier integration walkthrough (14 placeholders)
• Screenshots: Stripe payment gateway walkthrough (13 placeholders) #66 — Screenshots: Stripe payment gateway walkthrough (13 placeholders)
• Screenshots: PayPal payment gateway walkthrough (5 placeholders) #67 — Screenshots: PayPal payment gateway walkthrough (5 placeholders)
• Screenshots: Customer account page (16 placeholders) #68 — Screenshots: Customer account page (16 placeholders)
• Screenshots: Product limitation tabs (9 identical duplicates) #69 — Screenshots: Product limitation tabs (9 identical duplicates)
• Screenshots: Network admin dashboard widgets (7 identical duplicates) #70 — Screenshots: Network admin dashboard widgets (7 identical duplicates)
• Screenshots: Settings → Payments tabs (3 identical duplicates) #71 — Screenshots: Settings → Payments tabs (3 identical duplicates)
• Screenshots: Checkout form editor flow (heavy reuse) #72 — Screenshots: Checkout form editor flow (heavy reuse)
• Screenshots: Customizing the registration form (depends on checkout forms) #73 — Screenshots: Customizing the registration form (depends on Screenshots: Checkout form editor flow (heavy reuse) #72)
• Screenshots: Webhooks setup walkthrough #74 — Screenshots: Webhooks setup walkthrough
• Screenshots: Installation wizard (1 duplicate + verify currency) #75 — Screenshots: Installation wizard (1 duplicate + verify currency)
• Screenshots: UM analytics dashboard (1 duplicate) #76 — Screenshots: UM analytics dashboard (1 duplicate)
• Screenshots: Site templates documentation #77 — Screenshots: Site templates documentation

How this audit was done

# All tracked images
git ls-files | grep -iE '\.(png|jpg|jpeg|gif|webp)$'

# Exact-duplicate detection
find static/img -type f -name '*.png' -exec md5sum {} \; | sort | uniq -d -w 32

# Reference counts per image
grep -rohE '/img/[^)" ]+\.png' docs/ | sort | uniq -c | sort -rn

# Image dimensions / file sizes
find static/img -name '*.png' -exec file {} \;

Future work (not yet ticketed)

The audit also found heavy reuse in the following areas, which are smaller scope but still worth fixing:

• VAT / Tax handling (tax-handling.md) — settings-taxes.png used as the VAT add-on install screenshot.
• Discount codes (creating-discount-codes.md) — discount-codes-list.png re-used for save / active / advanced screens.
• Domain mapping (how-to-configure-domain-mapping.md) — domains-list.png used for several different screens.
• WooCommerce add-on (addons/woocommerce/index.mdx) — uses addons-page.png and settings-payment-gateways.png for different steps.
• GoCardless / PayFast / Language Selector / Site Exporter / Admin Page Creator add-on docs — each has 1–2 shots that could be more specific.
• Touring the admin panel (touring-the-admin-panel.md) — verify each linked screen still matches the current UI.

These can be ticketed as needed once the high-impact issues above are landed.