docs: prefer committed visual snapshots; split videos into their own lane

Author: edelauna

.github/pull_request_template.md

@@ -38,14 +38,35 @@ Detail the steps to test your changes. This helps reviewers verify your work.
 - [ ] **Scope**: My changes are focused on the linked issue (one major feature/fix per PR).
 - [ ] **Self-Review**: I have performed a thorough self-review of my code.
 - [ ] **Testing**: New and/or updated tests have been added to cover my changes (if applicable).
+- [ ] **Visual Snapshot** (UI changes only): If a user would notice this change at a glance (layout, theme tokens, brand elements, empty/error states), I've added or updated a `*.visual.tsx` snapshot in `webview-ui/`. See `webview-ui/AGENTS.md` → "When a UI change needs a snapshot".
 - [ ] **Documentation Impact**: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
 - [ ] **Contribution Guidelines**: I have read and agree to the [Contributor Guidelines](/CONTRIBUTING.md).
 
-### Screenshots / Videos
+### Visual Snapshots
 
 <!--
-For UI changes, please provide before-and-after screenshots or a short video of the *actual results*.
-This greatly helps in understanding the visual impact of your changes.
+For UI changes to static rendered state, the primary artifact is a committed
+Playwright CT snapshot (`*.visual.tsx` in `webview-ui/`) — that baseline
+becomes durable regression coverage for the surface. See
+`webview-ui/AGENTS.md` for what deserves a snapshot.
+
+Before/after screenshots pasted here are welcome as a review aid but are not a
+substitute for the committed baseline. If a snapshot is possible, prefer the
+snapshot.
+-->
+
+### Videos (interaction / animation only)
+
+<!--
+Snapshots cannot capture motion or multi-step flows. Attach a short screen
+recording here when reviewers need to see:
+  - A new interactive flow (dropdown, form, dialog progression)
+  - Animation, transition, or timing behavior
+  - A regression that only manifests during interaction
+
+Videos are a review aid, not regression coverage. If the *result* of the
+interaction has a distinct rendered state worth protecting, still commit a
+`*.visual.tsx` snapshot of that end-state alongside the video.
 -->
 
 ### Documentation Updates

webview-ui/AGENTS.md

@@ -42,7 +42,26 @@ Codecov tracks `webview-ui` coverage under the `webview-ui` flag.
 
 ## Visual Tests (Playwright CT)
 
-- Add Playwright screenshot tests selectively for components where layout, styling, VS Code theme variables, or real web-component rendering are part of the behavior under test.
+### When a UI change needs a snapshot
+
+If your PR changes anything a user would notice at a glance — layout, spacing, theme tokens, brand elements, gradients, mask/blur effects, hover/empty/error states — **add a `*.visual.tsx` snapshot to the same PR**. Do not attach screenshots to the PR description as evidence; commit the baseline instead so future PRs get regression coverage automatically.
+
+Visual regression is screen-based, not line-based — the goal is a small set of durable "pixel receipts" for the surfaces users see first, not blanket coverage. Prefer covering:
+
+- Onboarding / first-run surfaces (welcome view, hero, unconfigured state)
+- Empty and error states (no history, provider misconfig, degraded modes)
+- Theme-critical layouts that rely heavily on `--vscode-*` tokens or CSS masks/gradients
+- One representative snapshot per user-facing screen — not per component
+
+Skip a visual test when the change is behavior-only (state transitions, handler wiring, validation) — those belong in Vitest. Visual tests are for what JSDOM cannot verify.
+
+### Where the two coverage flags fit
+
+- `webview-ui` (Vitest + JSDOM) — broad line coverage over component logic, hooks, and state. This is your main coverage gate.
+- `webview-ui-ct` (Playwright CT) — narrow pixel-regression signal over a small set of critical screens. Low absolute % is expected and fine; the flag is not a coverage-to-hit target, it's a "did the surface still render the same" check.
+
+### Authoring rules
+
 - Keep behavioral assertions in Vitest. A `*.visual.tsx` test should establish a deterministic state and make a focused screenshot assertion.
 - Run visual comparisons with `pnpm test:visual:docker` from `webview-ui/`.
 - Update intentional baselines with `pnpm test:visual:docker:update` and commit the resulting `__screenshots__` files with the UI change.