In 2016, the idea of defining your server infrastructure in a YAML file and committing it to git felt radical. Today, infrastructure as code is the default. Nobody manually configures production servers through a web console anymore.
Documentation screenshots are stuck in the 2015 era. Someone opens the product, manually navigates to the right screen, takes a screenshot, crops it, annotates it, and drops it into a docs folder. When the UI changes, someone (maybe the same person, maybe not) has to repeat the entire process. There is no version control, no automation, and no way to know whether the screenshots in your docs still match reality.
The screenshots-as-code approach applies the same principles that transformed infrastructure management to documentation visuals. Define what you want to capture in configuration. Let automation handle the execution. Integrate it into your existing workflows. Version everything.
The parallels are direct:
| Infrastructure as Code | Screenshots as Code |
|---|---|
| Terraform/Pulumi config files | Screenshot capture config files |
terraform plan (preview changes) |
Visual diff (preview screenshot changes) |
terraform apply (deploy infra) |
Capture and publish (deploy screenshots) |
| State file (current infra state) | Visual registry (current screenshot state) |
| Drift detection (config vs. actual) | Visual debt detection (screenshot vs. live UI) |
| Multi-environment (staging, prod) | Multi-variant (themes, locales, roles) |
The mental model is the same: your documentation visuals should be a deterministic output of a declarative configuration, not a manual artifact managed through tribal knowledge.
The foundation of screenshots-as-code is a configuration file that declaratively defines every screenshot your documentation needs. Here is what that looks like in practice:
{
"baseUrl": "https://app.example.com",
"outputDir": "./docs/images",
"defaults": {
"viewport": { "width": 1280, "height": 800 },
"waitForSelector": "[data-ready='true']",
"format": "png",
"quality": 90
},
"captures": [
{
"id": "dashboard-overview",
"path": "/dashboard",
"selector": ".dashboard-container",
"description": "Main dashboard with sample data",
"usedIn": ["docs/getting-started.md", "docs/dashboard-guide.md"]
},
{
"id": "settings-general",
"path": "/settings/general",
"selector": ".settings-panel",
"actions": [
{ "type": "click", "selector": "[data-tab='notifications']" },
{ "type": "wait", "duration": 500 }
],
"description": "Settings page with notifications tab active"
},
{
"id": "project-create-modal",
"path": "/projects",
"actions": [
{ "type": "click", "selector": "[data-action='new-project']" },
{ "type": "waitForSelector", "selector": ".modal-overlay" }
],
"selector": ".modal-overlay",
"description": "New project creation modal"
}
]
}
Each capture entry defines:
path)selector)actions -- clicks, waits, form fills needed to reach the target state)description, usedIn)The configuration is the source of truth. If a screenshot is not in the config, it should not be in your docs. If a config entry references a selector that no longer exists, the capture fails and you get an immediate signal that something changed.
Real documentation screenshots are rarely just "navigate to a URL and take a picture." You need to open modals, switch tabs, fill in sample data, expand accordions, hover over tooltips. The actions array handles this:
{
"id": "billing-upgrade-flow",
"path": "/settings/billing",
"actions": [
{ "type": "click", "selector": "[data-action='upgrade']" },
{ "type": "waitForSelector", "selector": ".plan-comparison" },
{ "type": "click", "selector": "[data-plan='pro']" },
{ "type": "wait", "duration": 300 },
{ "type": "fill", "selector": "#coupon-code", "value": "DEMO2026" }
],
"selector": ".upgrade-modal",
"description": "Upgrade modal with Pro plan selected and coupon applied"
}
This is reproducible. Any engineer can read this config and understand exactly what the screenshot should show. There is no ambiguity, no "I think Sarah took this screenshot last quarter."
This is where screenshots-as-code delivers its biggest advantage over manual processes. Modern products have multiple visual states, and your documentation should reflect all of them.
{
"variants": {
"themes": [
{
"name": "light",
"setup": {
"type": "evaluate",
"script": "document.documentElement.setAttribute('data-theme', 'light')"
}
},
{
"name": "dark",
"setup": {
"type": "evaluate",
"script": "document.documentElement.setAttribute('data-theme', 'dark')"
}
}
]
}
}
{
"variants": {
"locales": [
{
"name": "en",
"setup": { "type": "cookie", "name": "locale", "value": "en" }
},
{
"name": "ja",
"setup": { "type": "cookie", "name": "locale", "value": "ja" }
},
{
"name": "de",
"setup": { "type": "cookie", "name": "locale", "value": "de" }
}
]
}
}
{
"variants": {
"roles": [
{
"name": "admin",
"auth": { "email": "admin@test.com", "token": "${ADMIN_TOKEN}" }
},
{
"name": "member",
"auth": { "email": "member@test.com", "token": "${MEMBER_TOKEN}" }
},
{
"name": "viewer",
"auth": { "email": "viewer@test.com", "token": "${VIEWER_TOKEN}" }
}
]
}
}
When variants are configured, a single capture definition produces multiple output images:
docs/images/
dashboard-overview/
light-en-admin.png
light-en-member.png
light-ja-admin.png
dark-en-admin.png
dark-en-member.png
...
A documentation set with 50 captures and three variant dimensions (2 themes, 3 locales, 3 roles) produces 900 screenshots from 50 config entries. Doing this manually is not just tedious -- it is practically impossible to maintain. With config-driven capture, adding a new locale means adding one entry to the variants block and re-running automation.
Screenshots-as-code reaches its full potential when integrated into your local workflow or any automation system. Here is a practical example using a shell script or build tool:
#!/bin/bash
# Visual Documentation Sync
# Run this script on code changes or on a schedule (e.g., weekly)
npm run build
npm start &
APP_PID=$!
npx wait-on http://localhost:3000 --timeout 60000
# Capture screenshots
npx reshot run --config reshot.config.json
# Compare with current
if npx reshot diff --threshold 0.02; then
# Changes detected
git checkout -b docs/visual-update-$(date +%s)
git add docs/images/
git commit -m "chore(docs): update documentation screenshots"
git push origin docs/visual-update-$(date +%s)
gh pr create \
--title "docs: update screenshots ($(date +%Y-%m-%d))" \
--body "$(npx reshot diff --report)" \
--label "documentation"
fi
kill $APP_PID
You can integrate this into your build system, run it locally before commits, or script it into any workflow you prefer.
Triggers on UI changes. Re-capture screenshots whenever frontend code changes. No manual intervention needed.
Runs on a schedule. Set up a cron job or scheduled task to run weekly and catch changes that might slip through -- data-driven UI changes, third-party widget updates, or content changes from a CMS.
Diffs against current screenshots. The diff step compares newly captured screenshots against the existing ones in the repository. A threshold of 0.02 (2% pixel difference) avoids false positives from anti-aliasing or rendering variance.
Creates a PR with a visual diff report. Changed screenshots are committed to a branch and a pull request is opened with a human-readable report of what changed and why.
The PR becomes the review checkpoint. Reviewers can see the old screenshot, the new screenshot, and the visual diff side-by-side. They approve it like any other code change.
The goal is not to add a new process. It is to fold documentation visuals into the process you already have.
Most teams already have automation for testing, linting, and deployment. Screenshots-as-code adds one more step to that automation. It uses the same infrastructure, the same review process, and the same deployment cadence. No new tools to learn, no new workflows to adopt.
One of the most powerful aspects of the automation approach is that you get bounded freshness. If your automation runs on every merge to main, your screenshots are never more than one merge behind the current localhost build you captured. If it runs weekly, your maximum drift is seven days.
Compare this to manual processes where screenshots can drift for months or years without anyone noticing.
You can enforce freshness at different levels:
The idea of treating screenshots as code did not emerge in a vacuum. It follows a well-established pattern in software engineering:
Each wave applies the same core insight: anything that can be defined declaratively and executed automatically should be. Manual processes do not scale, introduce human error, and lack auditability.
For a deeper look at the costs of the manual approach, see what visual debt actually costs your team.
Annotations can be config-driven too. Define bounding boxes, arrow positions, and label text in the capture configuration. The automation applies them consistently every time. This actually produces better annotations than manual work because placement is pixel-precise and consistent across every screenshot.
Prefer a localhost build with deterministic seed data. The point is to run the shipped app locally inside CI, not to capture against production URLs. This is the same approach you already use for reliable end-to-end tests.
They do not need to. The config file is JSON -- any technical writer can edit it. The capture runs as a CLI command, and the PR review process is the same one they already use for content changes.
Every approach has edge cases. The goal is to automate 80-90% of your screenshots and handle the remaining 10-20% through a documented manual process. Even partial automation dramatically reduces visual debt accumulation.
You do not need to convert your entire documentation set overnight. Start with a pilot:
Pick 10-20 high-traffic screenshots. Choose the ones that appear in your getting-started guide or most-visited docs pages.
Write the capture config. Define the paths, selectors, and actions needed to reproduce each screenshot.
Run it locally. Verify that the automated captures match your current screenshots closely enough.
Add it to CI. Start with monitoring-only mode. Let it run for two weeks and review the diff reports.
Expand gradually. Add more captures to the config as you gain confidence in the approach.
The Reshot docs walk through this workflow end-to-end: config-driven capture, variant management, visual diffing, and local automation. But the approach itself is tool-agnostic. You can build it with Playwright and a shell script if you want. The principles matter more than the tooling.