Screenshots as Code: Automating Documentation Visuals

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 Infrastructure as Code Analogy

The parallels are direct:

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.

Config-Driven Screenshot Capture

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": "http://localhost:3000",
  "storageStatePath": ".reshot/auth-state.json",
  "viewport": { "width": 1280, "height": 800 },
  "scenarios": [
    {
      "key": "dashboard-overview",
      "name": "Dashboard overview",
      "description": "Main dashboard with sample data",
      "url": "/dashboard",
      "readySelector": "[data-ready='true']",
      "steps": [
        { "action": "waitForSelector", "selector": ".dashboard-container" },
        { "action": "screenshot", "key": "dashboard-overview" }
      ]
    },
    {
      "key": "settings-notifications",
      "name": "Settings notifications tab",
      "description": "Settings page with notifications tab active",
      "url": "/settings/general",
      "steps": [
        { "action": "click", "selector": "[data-tab='notifications']" },
        { "action": "wait", "ms": 500 },
        { "action": "screenshot", "key": "settings-notifications" }
      ]
    },
    {
      "key": "project-create-modal",
      "name": "New project modal",
      "description": "New project creation modal",
      "url": "/projects",
      "steps": [
        { "action": "click", "selector": "[data-action='new-project']" },
        { "action": "waitForSelector", "selector": ".modal-overlay" },
        { "action": "screenshot", "key": "project-create-modal" }
      ]
    }
  ]
}

Each scenario entry defines:

• Where to navigate (url)
• How to get there (steps -- goto, click, wait, waitForSelector, type needed to reach the target state)
• What to capture (the screenshot step and its stable key)
• Why it exists (name, description)

The configuration is the source of truth. If a screenshot is not in the config, it should not be in your docs. If a step references a selector that no longer exists, the capture fails and you get an immediate signal that something changed.

Steps: Reaching Complex States

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 steps array handles this:

{
  "key": "billing-upgrade-flow",
  "name": "Billing upgrade flow",
  "url": "/settings/billing",
  "description": "Upgrade modal with Pro plan selected and coupon applied",
  "steps": [
    { "action": "click", "selector": "[data-action='upgrade']" },
    { "action": "waitForSelector", "selector": ".plan-comparison" },
    { "action": "click", "selector": "[data-plan='pro']" },
    { "action": "wait", "ms": 300 },
    { "action": "type", "selector": "#coupon-code", "text": "DEMO2026" },
    { "action": "screenshot", "key": "billing-upgrade-flow" }
  ]
}

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."

Variant Management

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 are declared once under a top-level variants.dimensions block, then opted into per scenario with "variants": { "dimensions": ["theme", "locale"] }. Each option lists how to set the state with an inject array (localStorage, cookie, or browser).

Theme Variants

{
  "variants": {
    "dimensions": {
      "theme": {
        "label": "Theme",
        "options": {
          "light": {
            "name": "Light Mode",
            "inject": [
              { "method": "localStorage", "key": "app-theme", "value": "light" },
              { "method": "browser", "colorScheme": "light" }
            ]
          },
          "dark": {
            "name": "Dark Mode",
            "inject": [
              { "method": "localStorage", "key": "app-theme", "value": "dark" },
              { "method": "browser", "colorScheme": "dark" }
            ]
          }
        }
      }
    }
  }
}

Locale Variants

{
  "variants": {
    "dimensions": {
      "locale": {
        "label": "Locale",
        "options": {
          "en": { "name": "English", "inject": [{ "method": "cookie", "key": "locale", "value": "en" }] },
          "ja": { "name": "Japanese", "inject": [{ "method": "cookie", "key": "locale", "value": "ja" }] },
          "de": { "name": "German", "inject": [{ "method": "cookie", "key": "locale", "value": "de" }] }
        }
      }
    }
  }
}

Role Variants

{
  "variants": {
    "dimensions": {
      "role": {
        "label": "Role",
        "options": {
          "admin": { "name": "Admin", "inject": [{ "method": "localStorage", "key": "auth-token", "value": "${ADMIN_TOKEN}" }] },
          "member": { "name": "Member", "inject": [{ "method": "localStorage", "key": "auth-token", "value": "${MEMBER_TOKEN}" }] },
          "viewer": { "name": "Viewer", "inject": [{ "method": "localStorage", "key": "auth-token", "value": "${VIEWER_TOKEN}" }] }
        }
      }
    }
  }
}

When dimensions are opted into on a scenario, a single scenario 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 scenarios and three variant dimensions (2 themes, 3 locales, 3 roles) produces 900 screenshots from 50 scenario 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.

Local 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 against localhost, diff against the live registry, and push any
# changed captures to the Reshot review queue. One command, no diff plumbing.
npx @reshotdev/screenshot run --headless --config reshot.config.json

kill $APP_PID

You can integrate this into your build system, run it locally before commits, or script it into any workflow you prefer.

What This Automation Does

1. Triggers on UI changes. Re-capture screenshots whenever frontend code changes. No manual intervention needed.

2. 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.

3. Diffs against the live registry. reshot run compares each freshly captured screenshot against the current approved version Reshot is already serving. Anti-aliasing and rendering variance are tuned out, so you only hear about real changes.

4. Sends changed captures to Review. Changed screenshots land in the Reshot review queue as candidates, with the old version, the new version, and the visual diff side-by-side -- not as a pile of binary files in a git PR for someone to eyeball.

Review is the checkpoint. A reviewer approves a candidate and the same durable URL Reshot was already serving flips to the new image -- every doc, README, and embed updates at once, with no find-and-replace and no broken links.

Integration with Existing Workflows

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.

Freshness Boundaries

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:

• Hard gate: Fail the build if any screenshot diffs exceed a threshold. This is aggressive but guarantees zero visual debt.
• Soft gate: Create a PR but do not block the build. This is more practical for most teams and keeps visual updates in the review queue without slowing down feature development.
• Monitoring only: Capture diffs and report them to a dashboard without any blocking. Useful as a first step when introducing screenshots-as-code to a team.

Where This Approach Came From

The idea of treating screenshots as code did not emerge in a vacuum. It follows a well-established pattern in software engineering:

• 2013-2015: Infrastructure as code (Terraform, CloudFormation) replaces manual server configuration
• 2016-2018: Configuration as code (Kubernetes manifests, Docker Compose) replaces manual deployment
• 2018-2020: Policy as code (OPA, Sentinel) replaces manual compliance checks
• 2020-2023: Visual testing as code (Percy, Chromatic) replaces manual visual QA
• 2024-present: Screenshots as code replaces manual documentation visuals

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.

Common Objections

"Our screenshots need custom annotations and callouts."

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.

"We need test data, not production data."

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.

"Our docs team does not know automation."

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.

"What about edge cases where automation cannot reach the right state?"

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.

Getting Started

You do not need to convert your entire documentation set overnight. Start with a pilot:

1. Pick 10-20 high-traffic screenshots. Choose the ones that appear in your getting-started guide or most-visited docs pages.

2. Write the scenario config. Define the URLs, selectors, and steps needed to reproduce each screenshot.

3. Run it locally. Verify that the automated captures match your current screenshots closely enough.

4. Add it to CI. Start with monitoring-only mode. Let it run for two weeks and review the diff reports.

5. 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.

The capture half of this is the part you can build yourself -- Playwright plus a shell script will take a screenshot. What that script will not give you is the hard half: a review queue so a non-engineer can approve a changed screenshot, a visual registry that tracks the approved state of every variant, and durable URLs that flip to the new image on approval so every doc, README, and embed updates at once without a find-and-replace. Owning that layer -- diff storage, approval state, CDN invalidation, dead-link safety across hundreds of embeds -- is a product, not a script. That is the part Reshot manages so your team does not have to. The principles in this post are tool-agnostic; the managed review-and-delivery layer is where the actual leverage lives.