Screenshots as Code for Product Journeys

Screenshots as Code is the practice of declaring how product images are produced, reviewed, versioned, and delivered so the result can be reproduced from trustworthy product state. For Product Journeys, the code is only one part of the contract. The complete lineage includes Journey Version, State Capsule, Run, Observation, Decision, Rendition, Publication, and receipt.

The goal is not to put every image in Git. The goal is to eliminate anonymous pixels whose source, state, approval, and freshness cannot be established.

What belongs in the contract

A screenshot definition should identify:

• the owning Journey and immutable version;
• semantic checkpoint;
• declared actor, role, plan, data, flags, locale, theme, viewport, and clock;
• source repository and runner configuration;
• browser and environment policy;
• readiness assertion;
• animation, caret, font, mask, and redaction policy;
• capture dimensions and device scale;
• transformation instructions;
• target Channel and output policy;
• owner and Review requirements.

The definition should be diffable and reviewable. Secrets, reusable authentication state, and private source evidence must remain outside public configuration.

Separate source Observation from outward screenshot

The Observation is evidence of what the product rendered in an exact Run and context. The documentation or marketing screenshot is a Rendition derived from that evidence.

This separation preserves visual truth while allowing an outward asset to apply a crop, annotation, caption, compression, or approved redaction. It also prevents a presentation edit from rewriting the Run artifact that release reviewers relied on.

Each Rendition version should retain the source Observation hash and transformation configuration. If the source changes, the system can identify the output as refresh-due without guessing from filenames.

Repository layout

A practical repository can keep:

journeys/
  invite-member.yaml
captures/
  invite-member/
    pending-mobile-fr-dark.json
renditions/
  docs/
    invite-member-pending.json
publications/
  docs-help-center.json

The Journey definition owns outcome semantics. Capture definitions select approved checkpoints and contexts. Rendition definitions own presentation. Publication definitions own delivery. Generated images can live in object storage, a build artifact, or Git depending on size, review, retention, and distribution needs.

Avoid placing output bytes beside definitions without a manifest. A file called invite-final-v3-new.png does not communicate source or authority.

Deterministic capture

Pin the runner and browser build. Declare viewport, locale, timezone, theme, motion, fonts, clock, data, and flags. Wait for product meaning rather than an arbitrary delay. Control external content. Hide the caret and disable animations only when the checkpoint policy says those states are not evidence.

Run repeated-capture calibration before using visual diffs as a release signal. The Visual Determinism Benchmark publishes a small reproducible example of exact hashing and pixel comparison.

Content-addressed identity

Use cryptographic hashes to bind:

• Journey definition;
• State Capsule;
• runner source contract;
• source Observation;
• transformation configuration;
• output bytes;
• publication payload.

Hashing detects change. It does not decide whether the change is correct. Review and policy still determine whether a new version is approved, blocked, or requires downstream refresh.

Review workflow

For every changed output:

1. verify the native product path completed;
2. compare source and baseline only within compatible contexts;
3. inspect visual, DOM, and accessibility-tree changes where relevant;
4. classify product, state, target, infrastructure, privacy, or policy failures;
5. review crop, annotation, redaction, and alternative text;
6. record an attributable Decision;
7. supersede the previous Rendition without deleting its provenance;
8. publish through an authorized Channel;
9. retain the receipt and stable/version URL relationship.

The creator of a generated image should not be its sole approver for a release-critical asset.

Material-update detection

Compare content and evidence hashes before changing publication dates. A material update includes a changed procedure, screenshot, interpretation, source Journey Version, significant correction, or new evidence. Formatting-only changes can be recorded without presenting the page as newly researched.

When a Journey changes but a screenshot does not need an update, preserve a keep Decision. That provides stronger evidence than silently touching the file.

CI gates

A Screenshots-as-Code pipeline should fail when:

• the owning Journey or checkpoint is missing;
• source state is incompatible with the baseline;
• native execution failed;
• the output uses unapproved private evidence;
• a mask has no declared policy;
• alternative text is missing for a meaningful public image;
• the source Observation or transformation hash is absent;
• a baseline changes without an attributable Decision;
• a Publication reports success without a receipt;
• the page date changes while its material content hash does not.

Storage and privacy

Do not commit authenticated storage state, customer identifiers, tokens, or unredacted private captures. Keep raw evidence under the correct retention and access policy. Publish only intentionally sanitized Renditions. Record permanent redaction as a transformation and verify the public bytes independently.

When this approach is too heavy

A one-off internal screenshot with no release, documentation, or customer consequence may not need the full graph. Use the smallest sufficient process. The approach becomes valuable when screenshots recur, cross channels, influence release decisions, or routinely become stale.

Example definition review

For an invitation guide, the reviewer should be able to reconstruct why a capture exists without opening the PNG. The definition identifies the pending-invitation checkpoint, owner role, business plan, deterministic recipient fixture, en-US locale, light theme, desktop viewport, fixed clock, pinned Chromium build, and no external network content. The Rendition definition applies a crop around the invitation panel, a non-destructive annotation, and alternative text describing the pending state.

When the same Journey needs a French mobile image, create a separate declared context and Rendition version. Do not rename one output and overwrite the desktop baseline. When the control moves but the outcome remains stable, the visual Observation changes, the writer reviews whether the procedure text also changes, and the Publication receipt identifies exactly which channel version was delivered.

Ownership boundaries

Engineers should own executable behavior, fixtures, and protected state reconstruction. Product and design owners decide intended UI changes. Writers own explanation, crop, annotation, caption, and channel presentation. Accessibility and privacy owners decide their subjects. The publication system owns delivery receipts.

The configuration should make these boundaries explicit. A convenient visual editor must not silently rewrite repository-controlled locators, assertions, or side-effect policies. Likewise, a code change should not overwrite a writer’s approved explanation without exposing a conflict and both authors.

Operational observability

Log the definition hash, source revision, runner identity, context cell, capture hash, transformation hash, Decision, Publication attempt, and receipt. Track failure class instead of one generic job status. An infrastructure retry can proceed under policy; a state mismatch, privacy leak, or unexplained product difference requires a different response.

These records let the team distinguish “the browser crashed,” “the wrong locale ran,” “the screenshot changed,” and “the new screenshot was approved but never reached the docs site.” Without that separation, automation increases volume while preserving ambiguity.

Continue with Automated Documentation Screenshots, Documentation Drift, and Full-Journey Visual QA.