Repository navigation
Description
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:
- Show the actual UI being described.
- Be unique per concept (no recycled placeholder).
- Be cropped/sized to highlight the relevant control, not buried in chrome.
- 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
mainbuild) 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, orgnome-screenshot -wfor 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.pnginto 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:
- Open
wordpress.local:8080, log in asadmin / admin. - Re-create / open the screen described in the doc text.
- Capture per the standards table above (1280×800, tight crop, < 200 KB).
- Save to the exact path listed in the issue (overwrite existing file — keep the filename).
- If the issue says "split into N shots", add the new filenames to
static/img/.../and update the markdown references in the listeddocs/...file accordingly. - Run
npm start, visit the doc page, and confirm every shot renders and matches the surrounding text. - 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.pngused as the VAT add-on install screenshot. - Discount codes (
creating-discount-codes.md) —discount-codes-list.pngre-used for save / active / advanced screens. - Domain mapping (
how-to-configure-domain-mapping.md) —domains-list.pngused for several different screens. - WooCommerce add-on (
addons/woocommerce/index.mdx) — usesaddons-page.pngandsettings-payment-gateways.pngfor 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.
Activity
superdav42 commentedon May 19, 2026
Heads-up: an automated worker session published a parallel audit at #78 / #79 / #80 about a minute after this one (both running from the same prompt as different sessions). Cross-link comments left on each. The other audit adds these areas that I only listed as "future work" here:
Recommend keeping #64 as the program tracker, opening new child issues for those extra areas, and closing #79 / #80 as superseded by the narrower #65–#77 series.
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.
superdav42 commentedon May 19, 2026
Gap analysis from the duplicate session (#78 program)
A second audit pass (#78 / #79–#85, created minutes after #64) covered the same ground via a different methodology (reference-count per page rather than MD5-hash collision detection). The findings overlap heavily but surface 11 additional doc pages with placeholder-reuse problems that aren't yet covered by #65–#77, plus two meta-categories (addons with zero screenshots, and 48 orphan files in
static/img/).Closing #78–#83 as duplicates of this master. Keeping #84 and #85 as net-new sub-issues. Recording the remaining 11 gap pages below so they can be picked up as needed.
Existing per-page coverage (already filed)
integrations/zapier.mdintegrations/zapier-register-account.mdintegrations/webhooks.mdpayment-gateways/stripe.mdpayment-gateways/paypal.mdclient-management/account-page.mdconfiguration/creating-your-first-subscription-product.mdadministration/dashboard-overview.md,understanding-the-dashboard.mdgetting-started/installing-ultimate-multisite.mdadministration/managing-payments-and-invoices.mdconfiguration/checkout-forms.mdconfiguration/customizing-your-registration-form.mdconfiguration/site-templates.md,auto-search-and-replace-in-site-templates.mdGap pages — placeholder reuse, not yet filed
Each entry below is a candidate for its own per-page issue matching the #65–#77 template (For #64. / ## Problem / ref table / ## Captures required / 1280×800 / ## Done when). Line numbers are from
mainat the time of this audit.1.
docs/user-guide/payment-gateways/getting-paid.md— 18 placeholder reusessettings-payment-gateways.png× 7 on L16,22,26,30,34,36,42;settings-general.png× 11 on L62,66,70,74,78,86,90,94,102,106,110. Alt-text describes 18 distinct screens — Settings → Payments rows (auto-renew toggle, trial toggle, invoice scheme, sequential invoice number) and the add-on install dialogs for WooCommerce, GoCardless, Payfast.2.
docs/user-guide/payment-gateways/manual-payments.md— 6 placeholder reusessettings-payment-gateways.png× 3 on L20,24,28 (manual gateway toggle, frontend instructions, Thank You page);payments-list.png× 3 on L34,38,42 (payments list, payment-detail page, status-change + activate-membership toggle).3.
docs/user-guide/payment-gateways/tax-handling.md— 15 placeholder reusessettings-taxes.png× 15 on L18,26,38,42,52,54,58,60,80,84,86,90,94,102,110 covering: Enable Taxes toggle, Inclusive Tax toggle, Manage Tax Rates button, tax rates editor, Add new Tax Category, tax category modal, switch categories, Add-ons sidebar link, VAT add-on listing, VAT install dialog, VAT network-activate, Enable VAT Support toggle, EU VAT rate pull, frontend VAT field.4.
docs/user-guide/configuration/creating-discount-codes.md— 14 placeholder reusesdiscount-codes-list.png× 14 on L16,22,24,28,36,40,44,50,54,64,66,70,74,78. Note: orphan filesdiscount-code-edit.png,discount-code-active.png,discount-code-advanced.png,discount-code-description.png,discount-code-save.png,discount-codes-empty.pngalready exist instatic/img/config/— verify accuracy and wire in before re-capturing.5.
docs/user-guide/configuration/the-registration-flow.md— 9 reuses across 3 imagescheckout-forms-list.png(L20),checkout-form-editor.png× 2 (L26,32),settings-payment-gateways.png× 3 (L46,50,54),payments-list.png× 4 (L60,64,66,70). Covers customer-side registration form, Thank You page, site activation, manual-payment instructions, and admin-side payment processing. Frontend captures needed.6.
docs/user-guide/client-management/upgrading-a-plan.md— 8 reuses across 2 imagesmemberships-list.png× 5 on L16,20,26,32,36 (customer-side: account page, Your Membership / Change button, checkout with plans, upgrade summary, "no-change" message);product-upgrades.png× 3 on L50,54,56 (admin: Up/Downgrades tab, plan-group assignment). Customer captures and admin captures should be split.7.
docs/user-guide/client-management/canceling-a-membership.md— 6 placeholder reusesmemberships-list.png× 6 on L16,20,24,26,30 (note: L30 has two images on one line). Customer Danger Zone, Confirm Account Deletion, logged-out state, cancellation confirmation, customer-still-exists-after-cancel.8.
docs/user-guide/client-management/downgrading-a-plan.md— 4 reuses across 2 imagesmemberships-list.png× 3 on L16,20,26 (Change button, plan options, pending-change message);settings-sites.png× 1 on L38 (post-limit-exceeded options).9.
docs/user-guide/client-management/client-websites.md— 6 placeholder reusescustomers-list.png× 6 on L12,18,22,26,30,34 — customer-side captures: My Sites link, My Sites page, Account menu, Change Default Site button, dropdown, confirmation.10.
docs/user-guide/domain-mapping/how-to-configure-domain-mapping.md— 16 placeholder reusessettings-domain-mapping.png× 7 on L22,30,40,98,102,126,128 (sunrise.php wizard step, Domain Mapping enable, Force Admin Redirect, allow subsite users, product custom-domain option, Integration tab, hosting integration);domains-list.png× 9 on L62,66,74,76,80,106,110,114,116 (admin domains list, Add Domain modal, stage transitions, domain detail page, subsite-side metabox/modal/form).11.
docs/user-guide/miscellaneous/sending-emails-and-broadcasts.md— 14 placeholder reusesbroadcasts-list.png× 9 on L18,22,30,40,44,56,62,70,74 (Notice broadcast on customer dashboard, Broadcasts menu, Add modal as Message and Email, targeting, content editor);settings-emails.png× 5 on L96,100,104,108,120 (Emails settings tab, Customize System Emails button, Reset and Import, Import Emails options, Reset to defaults).Gap pages — data-state refresh (not placeholder reuse)
These don't have placeholder-reuse problems — each image is unique — but the captures show empty or near-empty state.
docs/user-guide/administration/touring-the-admin-panel.md— 13 list-page captures (Dashboard, Checkout Forms, Products, Memberships, Payments, Customers, Sites, Domains, Discount Codes, Broadcasts, Settings, Events, Webhooks). Each capture should be re-taken with the seed data from the capture playbook so lists look populated.docs/user-guide/administration/managing-memberships.md— small page, two captures. Re-take with seed data.These two pages could be handled in a single "populate Network Admin lists with seed data and re-capture the touring + managing-memberships shots" issue.
Net-new categories kept as separate issues
docs/addons/*/index.mdx: 28 addon pages with zero screenshots.static/img/not referenced from any English doc; many appear to be the correct per-step captures that should be wired into the gap pages above (e.g. the orphandiscount-code-edit.pngfamily is the right destination for Code Audit Routines — Open: 0 | Closed: 0 | Simplified: _No open PRs._ #4 above).Closures
Audit methodology:
git ls-files+ Python ref-counter againstdocs/**/*.{md,mdx}onmain, plus manual review of each affected file. Mapping of which doc references each image is reproducible from the cached results at/tmp/opencode/docs-audit/.aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.
superdav42 commentedon May 19, 2026
Sub-issues filed — complete index
The 11 gap pages from the gap-analysis comment have now been filed as per-page issues matching the #65–#77 template.
Per-page sub-issues
integrations/zapier.mdintegrations/zapier-register-account.mdintegrations/webhooks.mdpayment-gateways/stripe.mdpayment-gateways/paypal.mdpayment-gateways/getting-paid.mdpayment-gateways/manual-payments.mdpayment-gateways/tax-handling.mdconfiguration/checkout-forms.mdconfiguration/customizing-your-registration-form.mdconfiguration/creating-discount-codes.mdconfiguration/the-registration-flow.mdconfiguration/creating-your-first-subscription-product.mdconfiguration/site-templates.md+auto-search-and-replace…client-management/account-page.mdclient-management/upgrading-a-plan.mdclient-management/canceling-a-membership.mdclient-management/downgrading-a-plan.mdclient-management/client-websites.mddomain-mapping/how-to-configure-domain-mapping.mdmiscellaneous/sending-emails-and-broadcasts.mdadministration/managing-payments-and-invoices.mdadministration/dashboard-overview.md,understanding-the-dashboard.mdgetting-started/installing-ultimate-multisite.mdBold entries are the new per-page issues filed in this consolidation pass.
Net-new categories
index.mdxpages with zero screenshots.static/img/(markdown-only rewire wins; tackle before Screenshots: Creating discount codes (14 placeholders + 6 orphans to wire) #89/Screenshots: How to configure domain mapping (16 placeholders) #95/Screenshots: Manual payments walkthrough (6 placeholders) #87 to avoid re-capturing files that already exist).Not yet filed (lower priority)
administration/touring-the-admin-panel.mdandadministration/managing-memberships.mdare not placeholder-reuse — each capture is unique — but show empty/zero-state lists. A single "populate Network Admin lists with seed data and re-capture touring + managing-memberships shots" issue would close that gap when convenient.Closures recap
touring/managing-membershipsrefresh. Closed.Total active screenshot audit issues under this master: 24 (was 14 from Session A; +#84, +#85, +11 from this consolidation = 26 created total; 1 master + 24 children remaining open).
aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 10h and 383 tokens on this as a headless worker.
docs: replace 14 placeholder screenshots in creating-discount-codes
docs: replace placeholder screenshots in tax-handling (partial)
docs: add 5 more tax-handling screenshots (10/16 complete)
docs: replace placeholder screenshots in manual-payments (partial)
docs: replace placeholder screenshots in how-to-configure-domain-mapp…
docs: replace placeholder screenshots in sending-emails-and-broadcast…
docs: replace placeholder screenshots in getting-paid (partial)
feat: add customer-side screenshots for membership cancellation flow (#…
2 remaining items
superdav42 commentedon May 20, 2026
Dispatching worker (deterministic).
GH#77: docs: update site template screenshots
superdav42 commentedon Aug 13, 2026
Issue Consolidation Dispatched
A consolidation task has been filed as #179. It contains the full body and substantive comments of this issue inline, plus instructions for a worker to produce a merged spec, file it as a new issue, @mention all contributors, and close this issue as superseded.
What happens next:
consolidatedlabel, and closes this issueAutomated by
_dispatch_issue_consolidation()inpulse-triage.sh(t1982)aidevops.sh v3.32.258 automated scan.
superdav42 commentedon Oct 12, 2026
Superseded by #191. The merged spec is inlined on the new issue — continue discussion there.
aidevops.sh v3.34.13 plugin for OpenCode v1.18.31 with gpt-5.6-terra spent 5m and 68,643 tokens on this as a headless worker.