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

Area	States to capture	Current paths
Installer	Fresh form, preflight failure, install guide, progress running, success/removal	`packages/installer/docs/images/screenshots/*`
Marketplace	Unconnected, connected, catalogue browsing, readiness review, manual-only install, licence entry, live progress, purchases, package operations	`packages/marketplace/docs/images/screenshots/*`
Admin extensions	Extensions page empty/installed, package settings page, permission denied	Add under `packages/admin/docs/images/screenshots/*`.
Frontend safety	Normal anonymous page, cached page, authoring beacon disabled/enabled for admin	Add under frontend docs when frontend-authoring is installed.

Naming

Use names that describe the state, not the implementation:

marketplace-unconnected.png
marketplace-connected.png
marketplace-readiness-manual-only.png
marketplace-licence-entry.png
marketplace-install-progress.png
installer-preflight-failed.png
installer-success-remove-package.png

Include dark mode only when the visual state differs or the docs page already presents paired light/dark screenshots.

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.json beside package docs when the package already uses one.

Filament Actions

Custom Filament action behaviour needs screenshot coverage. Do not count raw actions; count states a reviewer cannot infer from a normal resource screenshot.

Standard CreateAction, EditAction, DeleteAction, DeleteBulkAction, RestoreAction, ForceDeleteAction, ReplicateAction, and view actions do not need a dedicated action screenshot when they are used without extra behaviour. The resource list, create, edit, or view screenshot is enough.

Add a screenshot when an action:

uses Action::make(), BulkAction::make(), StaticAction::make(), or a package-owned action class for a real workflow;
adds form(), schema(), wizard steps, modal content, footer actions, confirmation text, custom callbacks, mutations, or custom URLs;
handles import, export, publish, unpublish, sync, clone, preview, install, connect, retry, impersonation, token, or destructive behaviour.

Link the screenshot manifest back to the source file with covers:

{
    "id": "publishing-studio-compare-readiness",
    "target": "CompareReadinessPage",
    "covers": [
        "packages/publishing-studio/src/Filament/Pages/CompareReadinessPage.php"
    ]
}

Run npm run docs:filament-action-screenshots before finishing package work. New gaps fail npm run docs:screenshots:check.

The action checker scans this host repository by default. Set CAPELL_PACKAGES_REPO to an absolute companion-repository path only when you intentionally want to include that repository in the same check.

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.

Core workbench content

Core documentation captures come from scripts/screenshots/prepare-workbench.sh, which runs capell:install --demo --package-mode=core --theme=none. That seeds almost no content, because the core, admin and frontend capell.json files all declare "demo": null, and no theme is installed. Content-rich captures (for example the “Index of Practice” demo) come from the theme-submissions package’s demo content in capell-packages-4, so run those passes from capell-packages-4.

After a fresh composer install, post-autoload-dump removes vendor/orchestra/testbench-core/laravel/database/migrations; prepare-workbench.sh recreates the directory before the install step, so a manual testbench capell:install straight after composer install has nowhere to publish vendor migrations to.