## 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 - [ ] #65 — Screenshots: Zapier integration walkthrough (14 placeholders) - [ ] #66 — Screenshots: Stripe payment gateway walkthrough (13 placeholders) - [ ] #67 — Screenshots: PayPal payment gateway walkthrough (5 placeholders) - [ ] #68 — Screenshots: Customer account page (16 placeholders) - [ ] #69 — Screenshots: Product limitation tabs (9 identical duplicates) - [ ] #70 — Screenshots: Network admin dashboard widgets (7 identical duplicates) - [ ] #71 — Screenshots: Settings → Payments tabs (3 identical duplicates) - [ ] #72 — Screenshots: Checkout form editor flow (heavy reuse) - [ ] #73 — Screenshots: Customizing the registration form (depends on #72) - [ ] #74 — Screenshots: Webhooks setup walkthrough - [ ] #75 — Screenshots: Installation wizard (1 duplicate + verify currency) - [ ] #76 — Screenshots: UM analytics dashboard (1 duplicate) - [ ] #77 — Screenshots: Site templates documentation ## How this audit was done ```bash # 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.