capture-screenshots

name	capture-screenshots
description	Capture reproducible UI screenshots with Playwright (against the Firebase emulators) for use in the docs. Usage: /capture-screenshots <area or shot id>
user_invocable	true
model	sonnet

Capture UI Screenshots

Produce reproducible screenshots of the running app so the documentation in docs/ can show real UI. Screenshots are captured with Playwright against the Firebase emulators (the same infrastructure as the e2e tests), so authenticated screens render deterministically with no real account and no real data.

This skill supports /generate-docs and /update-docs: those skills call it when a document would be clearer with a picture, and /update-docs re-runs it when UI source changes so the images stay in step with the code.

How it works

Piece	Role
e2e/screenshots/manifest.ts	The shot list — one entry per image: id, title, and a setup(page) that drives the app into the desired state. The source of truth for what gets captured.
e2e/screenshots/capture.shots.ts	Runs each shot serially, hides toast notifications, and writes docs/assets/screenshots/<id>.png.
npm run screenshots	Boots the Auth + Database emulators (firebase emulators:exec) and runs the screenshots Playwright project.
docs/assets/screenshots/	Output directory. PNGs are committed and referenced from the docs.

The screenshots Playwright project (in playwright.config.ts) matches only *.shots.ts, uses a 1440×900 viewport, and is not part of npm run test:e2e.

Prerequisites

Same as the e2e tests:

• Node.js ≥ 20 (the repo pins 22 in .nvmrc) — run nvm use.
• Java (JDK) on the PATH for the emulators.
• Chromium installed once: npx playwright install chromium.
• A local src/config/.firebase.js (the dev server boots from it).

Step 1 — Decide what to show

Look at the target document and pick the UI states worth illustrating (a view, a modal, the editor). Prefer a few high-value images over screenshotting everything. Each image must be derivable by driving the real app — never mock or hand-edit a picture.

Step 2 — Add or adjust shots in the manifest

Edit e2e/screenshots/manifest.ts. Each shot:

{
  id: 'invite-modal',                         // → docs/assets/screenshots/invite-modal.png
  title: 'The Invite Member dialog',          // reuse as the image alt text / caption
  setup: async (page) => {
    await signIn(page);                        // call for any authenticated screen
    // ...navigate using the helpers from ../fixtures (createProject, openProject, ...)
    return page.getByRole('dialog');           // return a Locator to clip to it; return nothing for the page
  },
}

Conventions that keep images clean and deterministic:

• Fixed, human-readable names (e.g. 'Example Project') — shots run serially against a DB that is fresh each run, so unique suffixes aren't needed and look unprofessional in docs.
• Capture authenticated screens via signIn(page); reuse createProject/openProject from e2e/fixtures.ts to reach deeper states.
• Return a Locator to tightly frame a modal/panel; return nothing for a full-view shot.
• Toasts are hidden automatically before capture.

Step 3 — Capture

nvm use
npm run screenshots

The emulators start, each shot runs, PNGs are written to docs/assets/screenshots/, and the emulators shut down. Open the produced images and check them — if a state needs adjusting, tweak the shot's setup and re-run.

Step 4 — Embed in the docs

Reference the image from both the Markdown doc and its HTML twin (paths are relative to each file's location):

• Markdown — docs/<area>.md:

  ![The "Your Projects" view](assets/screenshots/projects-list.png)
  

• HTML — docs/html/<area>.html (one directory deeper, so prefix ../):

  <figure>
    <img src="../assets/screenshots/projects-list.png" alt="The &quot;Your Projects&quot; view">
    <figcaption>The "Your Projects" view</figcaption>
  </figure>
  

Use the shot's title as the alt text/caption so the two stay consistent.

Step 5 — Note the source

In a comment near the image (or the doc's "Related code" section) record that the screenshot is generated by this skill from e2e/screenshots/manifest.ts. That way /update-docs knows to re-run npm run screenshots when the relevant UI source changes, rather than treating the PNG as hand-made.

Guidelines

• Derived from the running app — screenshots show real, emulator-backed UI; never fake them.
• Deterministic — fixed names, serial capture, toasts hidden. The same run yields the same image.
• Minimal — a handful of meaningful shots beats a gallery; every shot is one more thing to keep current.
• Commit the PNGs under docs/assets/screenshots/ (they are documentation assets, not test artifacts).
• English captions, consistent with the rest of the docs.