GuideShot

GuideShot is an open-source tool I created at Wemuda for generating annotated screenshots of a web app for help guides and docs. Doing this by hand means taking the screenshots, drawing the arrows and boxes, and redoing all of it whenever the interface changes. Add a few languages plus light and dark mode and the number of images grows fast.

How it works

Each screenshot is described by a strict JSON recipe: which page to open, what to click or fill in, what has to be visible before the shot is taken, and which callouts, arrows or spotlights to draw. Annotations attach to data-guide-target attributes in the app instead of pixel coordinates, so they follow the element when the layout moves. One recipe can expand across locales, themes and user roles, while each viewport size gets its own recipe. The CLI captures every variant in Chromium through Playwright, draws the annotations in a separate offline step and writes a manifest the app can read. Because those steps are cached separately, guideshot compose can re-render a copy change in a callout without reopening the app.

What I did

• Wrote the spec and directed an AI coding agent through the first build of the recipe schema, Playwright capture, renderer and CLI
• Added concurrent capture workers and reuse of prepared browser states, so compatible shots can share one page
• Set up npm publishing for the @guideshot packages with Changesets and GitHub Actions OIDC, and the Docker deploy of the docs site
• Rebuilt the docs site and examples, including example captures at desktop, tablet and mobile sizes

It’s MIT licensed and on npm. At Wemuda we use it to generate the localized screenshots for the help-centre guides in Infood’s web app.