Introduction

shotlist takes annotated UI screenshots. It drives a running site with Playwright, clips a region, draws callouts on it, and writes the image where the project asks.

Each screenshot is a YAML recipe. What the screenshots are for — a handbook, a landing page, a release post, a store listing — is not the tool's concern, and nothing in it assumes one of them.

A recipe

A recipe names the region to capture, the regions inside it worth pointing at, and what to draw on those. Everything else has a default.

name: order-row
install: guide

clip: { css: '.order-row', contains: Acme Corp, pad: 20 }

marks:
  amount: { within: clip, text: $42.00 }

callouts:
  - { mark: amount, text: What they owe, place: left }

A project's config

One shotlist.config.yaml in the project root says where the site runs and where images are installed. Every drawing constant — colour, stroke, radius, font — is configurable here too, with a neutral default.

site:
  url: http://localhost:3000
  viewport: { width: 1440, height: 900 }
  scale: 2

install:
  guide: content/guide/images

A recipe is data

Nothing in a recipe runs. There is no step that evaluates JavaScript, and there will not be one. That keeps a recipe readable by anyone, and a broken screenshot fixable by anyone.