Screenshot State Guide
Screenshots should show real product states that help someone debug or understand the workflow. Avoid one perfect happy-path screenshot when the feature has meaningful states.
State Matrix
Section titled “State Matrix”| Area | States to capture | Current paths |
|---|---|---|
| Installer | Fresh form, preflight failure, install guide, progress running, success/removal | public/docs/screenshots/packages/installer/* |
| Marketplace | Unconnected, connected, domain verification failed, catalogue browsing, detail overview, docs/access, mobile detail, update advisories | public/docs/screenshots/packages/marketplace/* |
| Admin extensions | Extensions page empty/installed, package settings page, permission denied | Add under package docs or public/docs/screenshots/packages/admin/*. |
| Frontend safety | Normal anonymous page, cached page, authoring beacon disabled/enabled for admin | Add under frontend docs when frontend-authoring is installed. |
Naming
Section titled “Naming”Use names that describe the state, not the implementation:
marketplace-unconnected.pngmarketplace-connected.pngmarketplace-domain-verification-failed.pnginstaller-preflight-failed.pnginstaller-success-remove-package.pngInclude dark mode only when the visual state differs or the docs page already presents paired light/dark screenshots.
Capture Rules
Section titled “Capture Rules”- Use seeded data that is safe to publish.
- Hide secrets, emails, signing values, tokens, local paths, and private domains.
- Capture the whole viewport unless the docs need a tight crop of one control.
- Keep mobile screenshots for workflows that materially change on mobile.
- Update
screenshots.jsonbeside package docs when the package already uses one.
Flux Visual Companion Diagrams
Section titled “Flux Visual Companion Diagrams”Flux-generated diagrams are useful for conceptual visuals at the top of docs pages. They should not be the source of truth for class names, method names, or exact request flow.
Use Flux for:
- high-level architecture visuals;
- onboarding illustrations;
- state overview graphics;
- docs covers or section headers.
Use Mermaid for:
- exact class and registry flow;
- sequence diagrams;
- testable architecture;
- anything with code symbols.
The FLUX connector must be authenticated before generating these assets. Once authenticated, create images under docs/images/diagrams/ and keep the exact Mermaid diagram beside the image in the same doc.