Skip to content

Screenshot audit and refresh program (master) #64

Closed as not planned
Closed as not planned

Description

@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

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.

Activity

  1. added
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    help wantedExtra attention is needed
    origin:interactiveAuto-created by pulse labelless backfill (t2112)
    on May 19, 2026
  2. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    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:

    • 28 addon index.mdx pages with zero screenshots
    • 48 orphan files in static/img/ that exist on disk but are not referenced
    • Heavy single-image reuse in tax-handling.md (15×), creating-discount-codes.md (14×), zapier-register-account.md (12×), how-to-configure-domain-mapping.md (9×), sending-emails-and-broadcasts.md (9×), canceling-a-membership.md (6×), client-websites.md (6×)

    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.

  3. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    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)

    Page Sub-issue
    integrations/zapier.md #65
    integrations/zapier-register-account.md #74
    integrations/webhooks.md #65, #74
    payment-gateways/stripe.md #66
    payment-gateways/paypal.md #67
    client-management/account-page.md #68
    configuration/creating-your-first-subscription-product.md #69
    administration/dashboard-overview.md, understanding-the-dashboard.md #70, #76
    getting-started/installing-ultimate-multisite.md #70, #75
    administration/managing-payments-and-invoices.md #71
    configuration/checkout-forms.md #72
    configuration/customizing-your-registration-form.md #73
    configuration/site-templates.md, auto-search-and-replace-in-site-templates.md #77

    Gap 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 main at the time of this audit.

    1. docs/user-guide/payment-gateways/getting-paid.md — 18 placeholder reuses

    settings-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 reuses

    settings-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 reuses

    settings-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 reuses

    discount-codes-list.png × 14 on L16,22,24,28,36,40,44,50,54,64,66,70,74,78. Note: orphan files discount-code-edit.png, discount-code-active.png, discount-code-advanced.png, discount-code-description.png, discount-code-save.png, discount-codes-empty.png already exist in static/img/config/ — verify accuracy and wire in before re-capturing.

    5. docs/user-guide/configuration/the-registration-flow.md — 9 reuses across 3 images

    checkout-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 images

    memberships-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 reuses

    memberships-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 images

    memberships-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 reuses

    customers-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 reuses

    settings-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 reuses

    broadcasts-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

    Closures

    Audit methodology: git ls-files + Python ref-counter against docs/**/*.{md,mdx} on main, 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.

  4. superdav42 commented on May 19, 2026

    @superdav42
    ContributorAuthor

    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

    Doc page Issue Placeholder reuses
    integrations/zapier.md #65 14
    integrations/zapier-register-account.md #74 12
    integrations/webhooks.md #65 / #74 8
    payment-gateways/stripe.md #66 13
    payment-gateways/paypal.md #67 5
    payment-gateways/getting-paid.md #86 18
    payment-gateways/manual-payments.md #87 6
    payment-gateways/tax-handling.md #88 15
    configuration/checkout-forms.md #72 heavy
    configuration/customizing-your-registration-form.md #73 heavy
    configuration/creating-discount-codes.md #89 14 (+ 6 orphans to wire)
    configuration/the-registration-flow.md #90 9
    configuration/creating-your-first-subscription-product.md #69 9 identical
    configuration/site-templates.md + auto-search-and-replace… #77 —
    client-management/account-page.md #68 16
    client-management/upgrading-a-plan.md #91 8
    client-management/canceling-a-membership.md #92 6
    client-management/downgrading-a-plan.md #93 4
    client-management/client-websites.md #94 6
    domain-mapping/how-to-configure-domain-mapping.md #95 16
    miscellaneous/sending-emails-and-broadcasts.md #96 14
    administration/managing-payments-and-invoices.md #71 3 identical
    administration/dashboard-overview.md, understanding-the-dashboard.md #70 / #76 7 identical / 1 dup
    getting-started/installing-ultimate-multisite.md #70 / #75 wizard dup

    Bold entries are the new per-page issues filed in this consolidation pass.

    Net-new categories

    Not yet filed (lower priority)

    administration/touring-the-admin-panel.md and administration/managing-memberships.md are 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

    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.

  5. 2 remaining items

  6. self-assigned this
    on May 20, 2026
  7. superdav42 commented on May 20, 2026

    @superdav42
    ContributorAuthor

    Dispatching worker (deterministic).

  8. removed their assignment
    on May 20, 2026
  9. added and removed
    status:queuedWorker dispatched, not yet started
    on May 20, 2026
  10. added
    consolidation-in-progressAnother runner is creating a consolidation child issue (cross-runner advisory lock)
    needs-consolidationIssue held from dispatch pending comment consolidation
    on Aug 13, 2026
  11. superdav42 commented on Aug 13, 2026

    @superdav42
    ContributorAuthor

    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:

    1. A worker picks up consolidation-task: merge thread on #64 into single spec #179 on the next pulse cycle
    2. It files a new consolidated issue with the merged spec
    3. It comments "Superseded by #NNN" here, applies the consolidated label, and closes this issue
    4. Contributors (@superdav42) are @-mentioned on the new issue

    Automated by _dispatch_issue_consolidation() in pulse-triage.sh (t1982)


    aidevops.sh v3.32.258 automated scan.

  12. removed
    consolidation-in-progressAnother runner is creating a consolidation child issue (cross-runner advisory lock)
    on Aug 13, 2026
  13. superdav42 commented on Oct 12, 2026

    @superdav42
    ContributorAuthor

    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.

  14. added
    consolidatedIssue superseded by a consolidated child
    and removed
    needs-consolidationIssue held from dispatch pending comment consolidation
    on Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    consolidatedIssue superseded by a consolidated childdocumentationImprovements or additions to documentationenhancementNew feature or requesthelp wantedExtra attention is neededorigin:interactiveAuto-created by pulse labelless backfill (t2112)origin:workerCreated by headless/pulse worker sessionstatus:availableTask is available for claiming

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions