Screenshot Documentation

Use this guide when adding reader-facing screenshots to Wardian documentation.

Directory Layout

Committed screenshots live under:

docs/assets/screenshots/<feature-or-window>/<state>.png

Use kebab-case for folders and filenames. Match the folder to the feature guide that owns the screenshot:

• docs/assets/screenshots/grid/
• docs/assets/screenshots/dashboard/
• docs/assets/screenshots/explorer/
• docs/assets/screenshots/spawn-agent/
• docs/assets/screenshots/command-panel/
• docs/assets/screenshots/watchlists/
• docs/assets/screenshots/library/
• docs/assets/screenshots/workflows/
• docs/assets/screenshots/source-control/
• docs/assets/screenshots/settings/
• docs/assets/screenshots/user-terminal/

Do not place committed documentation images under e2e/screenshots/. That directory is ignored and reserved for local PR evidence, rendering audits, and temporary Playwright captures.

Embedding

Embed screenshots from the guide or reference page that explains the feature:

![Source Control panel showing branch state, commit box, staged changes, unstaged changes, and history](../assets/screenshots/source-control/status-panel.png)

Use alt text that describes the visible state. Avoid vague labels such as Screenshot of Source Control.

Capture Rules

• Capture real Wardian UI with seeded or sanitized data.
• Keep screenshots feature-specific. Avoid generic empty-window captures.
• Hide or avoid local usernames, absolute paths, API keys, provider tokens, and private repository names.
• Capture the smallest useful app region or viewport that still shows the interaction clearly.
• Prefer PNG for UI screenshots.
• Compress large images before committing.
• Refresh screenshots in the same PR when a visual change makes existing documentation images stale.

Recommended Workflow

Start the app with an isolated home so screenshots are reproducible.

WARDIAN_HOME="$(mktemp -d)" npm run dev

PowerShell:

$env:WARDIAN_HOME = "$PWD\.tmp\wardian-docs-screenshots"
npm run dev

Capture with Playwright or a browser screenshot tool, then copy only curated images into docs/assets/screenshots/<feature-or-window>/.

The first-pass core feature screenshots can be refreshed with:

npm run docs:screenshots

For screenshots that require Tauri IPC, PTY behavior, or provider runtime behavior, use the native E2E harness instead of browser-only E2E.

Review Checklist

• The image belongs under docs/assets/screenshots/, not e2e/screenshots/.
• The filename and directory are kebab-case.
• The image is embedded from the owning guide page.
• The surrounding text explains the state shown in the image.
• The alt text is descriptive.
• No local paths, secrets, or private data are visible.
• git status shows only intended docs assets and guide updates.

Use Core Feature Screenshot Capture Plan to decide which screenshots belong in the first documentation pass.

See 2026-05-12 Core Feature Screenshot Documentation for the architectural decision.