DEV Community: jake

How to Review a Signup Regression After a Next.js Release

jake — Tue, 14 Jul 2026 14:31:32 +0000

A signup regression after a Next.js release should not start with panic. It should start with a narrow review.

The dangerous version is familiar: a deploy ships green and signup quietly gets worse, and a few hours later signup looks weaker. Someone opens product analytics. Someone checks Sentry. Someone asks which pull request touched auth. Someone else wonders whether traffic changed. The team has evidence, but not a review.

The useful question is smaller: did this deploy make the signup path worse, and what evidence supports the next action?

Which signup path should you name before opening dashboards?

"Signup is down" is not specific enough.

Signup may include a marketing page, account creation form, email verification, company profile, workspace creation, plan selection, invite acceptance, and first activation step. A Next.js release might affect only one of those pieces. If the review treats signup as one blob, the team can miss the actual regression.

Start by naming the path precisely: /signup, /signup/company, /auth/callback, /join/[invite], /onboarding/workspace, or whatever route actually changed. Then name the success event. It should be a user outcome, not a page view. Account created, email verified, workspace created, invite accepted, or onboarding completed is stronger than "visited signup."

PostHog's funnel docs are useful here because they separate steps, drop-off, conversion rate, breakdowns, and historical trends. A funnel can show where people left. It still needs deploy context before it becomes a release review.

How do you freeze the release context?

Capture the deploy while it is still fresh:

Field	What to record
Deploy	Commit SHA, deploy URL, deploy time
Pull request	Auth, form, validation, layout, tracking, copy, pricing, invite logic
Owner	The team or person responsible for the signup path
Path	The precise route or flow being reviewed
Metric	Signup completion, invite acceptance, verification success, workspace creation
Windows	Before and after intervals with comparable traffic
Evidence	Product funnel, Sentry issue, route trace, logs, page analytics
Decision	Stable, watch, investigate, rollback candidate

Vercel's deployment docs matter because deployments carry concrete release context: generated URLs, environments, commits, logs, and project metadata. Use that context as the anchor. Do not let the review become "sometime after the release."

How do you compare signup against itself?

Do not start with all-site conversion. Signup can regress while the rest of the product looks normal. It can also look worse because a campaign sent colder traffic into the top of the funnel.

Use the deploy timestamp as the anchor and compare a similar window before and after release. The window should match traffic shape where possible. A Monday morning release should not be compared casually against late Friday night traffic unless volume and source mix are stable.

The comparison should answer the practical question without pretending one chart proves causality. Did the protected signup metric move after deploy? Did the PR touch code, content, routing, auth, pricing, flags, or validation on that path? Did traffic source, geography, device mix, or campaign exposure change enough to explain it? Did companion evidence point at the same route?

The comparison should preserve uncertainty. A dip after deploy is not automatically caused by the deploy. A clean error dashboard is not automatically proof that signup is healthy.

What runtime evidence should you check second?

After the path and metric are named, check runtime evidence.

Sentry's Next.js docs cover error monitoring, tracing, session replay, logs, and profiling for Next.js. In a signup review, Sentry is where you look for new exceptions on the signup route, failed server actions, hydration errors on the form, slow transactions around validation or workspace creation, and replay samples where users hit an error state.

The runtime signal is strongest when it lines up with the product signal, because PostHog shows behavior while Sentry shows breakage and a deploy review needs both. "Signup completion dropped and validation exceptions appeared on /signup/company after the validation PR" is a review. "Sentry has a new issue somewhere" is a lead.

Check route and span evidence when the symptom is soft

Signup regressions are not always loud. A route can become slower without throwing. A server action can retry. A third-party auth call can add latency. A dynamic route can fetch more than it did yesterday.

The Next.js OpenTelemetry guide shows default spans for route rendering, fetches, API routes, and metadata work, plus custom spans. That instrumentation helps explain soft regressions: a route render got slower, an auth callback made a slower external call, workspace creation moved from one backend call to several, or a fetch cache change added latency in the first signup step.

The review does not need every span. It needs enough route evidence to explain whether the deploy plausibly changed the path.

Check behavior and traffic context

Product analytics can show the behavioral shape of the regression: more users start signup but fewer complete it, one step loses more people than usual, mobile moves while desktop stays stable, or a flagged cohort behaves differently. Vercel Web Analytics can add page-level context through visitor and page behavior. PostHog can add events, cohorts, flags, and funnel breakdowns. Use those signals to prevent false blame.

For example:

Signup completion dropped after deploy, but traffic from a new campaign doubled and those visitors historically convert lower. Sentry is quiet. Mark watch and recheck with segmented traffic.

That is very different from:

Signup completion dropped after deploy, traffic mix is stable, and Sentry shows new validation failures on the same route. Mark investigate.

Use four decision states

The review should end with a state. Stable means signup stayed in range. Watch means signup moved but the evidence is mixed. Investigate means signup moved and the deploy plausibly touched it. Rollback candidate means signup moved and technical evidence points to the release. This language keeps the team from treating every dip as an incident or every clean error dashboard as a dismissal.

Why write the note while the evidence is fresh?

A good signup regression note is short:

Deploy 9f3c changed company signup validation. /signup/company completion dropped in the first stable post-deploy window. Traffic mix was normal. Sentry shows new validation errors on the same route. Marked investigate; owner is onboarding.

A weak note is:

Signup looks down after the deploy.

The weak note forces the next person to reconstruct the release. The strong note lets them act.

TrueClara is built for that strong note. It keeps deploy metadata, path ownership, signup metrics, evidence links, and the decision together. Your analytics and monitoring tools remain the evidence sources. TrueClara keeps the signup review from dissolving into tabs.

The next time signup moves after a Next.js release, do not start by asking which dashboard is right. Start with the path. Anchor it to the deploy. Layer the evidence. Record the decision.

Sources

[C1] PostHog funnels - Product analytics documentation for funnel steps, conversion, breakdowns, and trends.
[C2] Sentry Next.js docs - Sentry documentation for Next.js errors, traces, replay, logs, and profiling.
[C3] Next.js OpenTelemetry guide - Official Next.js instrumentation guide for route, fetch, API, and custom spans.
[C4] Vercel deployments - Vercel documentation for deploy methods, URLs, environments, and release metadata.
[C5] Vercel Web Analytics - Vercel documentation for page-level visitor behavior.

PostHog Behavior, Sentry Breakage: Deploy Review Needs Both

jake — Thu, 09 Jul 2026 14:30:42 +0000

PostHog and Sentry are not interchangeable tools. They answer different questions.

PostHog is where a team looks when it wants to understand product behavior: events, funnels, cohorts, feature flags, experiments, session replay, and conversion movement. Sentry is where a team looks when it wants to understand software failure: exceptions, traces, performance issues, releases, replays, and the technical context around a broken experience.

After a deploy, both are useful. Neither one, alone, is the full release review.

The question is not "PostHog or Sentry?" The better question is: did this deploy hurt the route we care about, and which evidence proves the next action?

What does each tool answer after a deploy?

A Next.js release can damage a product path without creating a loud exception. It can also create errors without changing the customer outcome enough to matter. That is why deploy review gets messy when a team treats one dashboard as the source of truth.

Sentry for Next.js is strong when the release causes runtime trouble. It can surface errors, performance spans, traces, replays, and release-adjacent debugging context. If a server action starts throwing, a hydration issue appears, or a route slows down, Sentry is often where the technical explanation begins.

PostHog's Next.js docs are strong on product instrumentation. Events, feature flags, user behavior, and funnels help answer whether people completed the path after the release. If signup completion dipped or onboarding step two started losing users, product analytics is the right evidence source.

Vercel Analytics can explain page-level behavior and traffic changes. The Next.js OpenTelemetry guide shows the instrumentation layer underneath routes, fetches, and custom spans.

Each tool is useful. The deploy review is the layer that asks them all the same question.

Question	Best evidence source
Did users complete the path at the same rate?	PostHog funnel or event analysis
Did the release introduce new runtime failures?	Sentry issues, traces, and replays
Did traffic mix or page behavior change?	Vercel Analytics and acquisition context
Did a route render, fetch, or backend call change?	OpenTelemetry spans and traces
Did the PR actually touch the path?	Pull request diff and deploy metadata

Why does deploy impact fall between dashboards?

Most teams already have enough telemetry to see the symptoms. The hard part is keeping the symptoms attached to the release.

A deploy goes out at 10:14. Signup dips by 11:00. Sentry shows a small increase in validation errors. PostHog shows a larger drop at one step. Vercel shows traffic was normal. The PR changed a validation rule. That is a useful story, and it mirrors the pattern in a green Next.js deploy that quietly hurt signup.

But if those facts live in separate tabs, the team has to assemble the story every time. One person pastes a Sentry link. Another posts a funnel screenshot. Someone asks which commit shipped. Someone else asks whether traffic changed. By the time the group agrees on the route, half the context is already stale.

Deploy impact is not a dashboard category. It is an operating question:

Which release created the question?
Which path could a customer feel?
Which metric says the path got better or worse?
Which evidence supports the movement?
What decision did the team make?

TrueClara keeps that question as a case file.

Do not force product analytics to explain engineering failure

PostHog can show that signup completion dropped. It can show the step where users left. It can show whether a feature flag was involved. It can show cohorts, replays, and events around the behavior.

But a product analytics tool is not the best place to inspect stack traces, slow spans, server-side exceptions, or release health. If the route moved because a server action started failing under a certain payload, Sentry or trace data should carry that investigation.

The mistake is using the funnel as proof of cause. A funnel movement tells you something changed in behavior. It does not prove why.

A useful review sentence sounds like this:

Signup completion dropped after deploy 9f3c. PostHog shows the loss at company validation. Sentry shows new validation exceptions on the same route. Investigate the validation change.

That sentence uses product analytics for behavior and error monitoring for failure. It does not make either tool do the other's job.

Do not force error monitoring to explain product movement

Sentry can show a clean release while a route still gets worse. A copy change can confuse users without throwing. A layout change can hide a button without causing a JavaScript exception. A pricing experiment can reduce upgrade completion with no runtime failure. An auth flow can become slower or more confusing before it breaks.

In those cases, the absence of a Sentry incident is useful but not final. It narrows the investigation. It does not close the review.

The route still needs product evidence:

Did users reach the same step?
Did they complete the same action?
Did the exposed audience change?
Did a feature flag split the population?
Did the traffic source change?

A deploy can be technically clean and commercially worse. That is the point of reviewing the path, not only the app.

Build a deploy review packet

The practical answer is not another giant dashboard. It is a packet that keeps the route, release, and evidence together.

Packet field	Why it matters
Deploy and PR	Prevents vague "after the release" debugging
Route or path	Keeps the review tied to a customer experience
Protected metric	Defines what healthy means
Product evidence	Shows behavior movement
Runtime evidence	Shows failures, latency, traces, or replay context
Traffic context	Explains whether audience changed
Decision	Turns evidence into action

The packet does not replace PostHog, Sentry, Vercel, or OpenTelemetry. It makes them answer the same release question.

When should you mark stable, watch, investigate, or rollback candidate?

Use stable when the protected metric stays in range and companion evidence is quiet.

Use watch when the path moved but the supporting evidence is mixed. Maybe traffic changed. Maybe the sample is thin. Maybe the movement is near the edge of normal variance. Watch is a real state because it prevents overreaction.

Use investigate when the path moved and the deploy plausibly touched it. At that point the owner needs evidence links, not another meeting.

Use rollback candidate when the route movement and technical evidence point to the same release. That still requires judgment, but the conversation becomes concrete: the release changed this path, the path got worse, and the evidence supports action. For a full walkthrough of that moment, see the deploy shipped, the route got worse, now what.

Use TrueClara to keep the question intact

TrueClara is built for the space between product analytics and error monitoring. It does not ask a team to abandon either tool. It keeps deploy metadata, route ownership, path metrics, and evidence links attached to the release.

That gives the team a release review object:

what shipped
what route it touched
what behavior changed
what PostHog showed
what Sentry showed
what Vercel or trace data explained
what decision the team made

PostHog shows behavior. Sentry shows breakage. Vercel and OpenTelemetry add traffic and instrumentation context. TrueClara keeps the deploy question intact long enough for the team to answer it.

Who owns the release review?

Tool choice is not the only reason deploy-impact reviews fail. Ownership is just as important.

If product owns the funnel, engineering owns the errors, growth owns experiments, and platform owns deployments, the review can fall between teams. Everyone has a useful dashboard. Nobody owns the release question.

Assign the owner by path, not by tool. If the deploy touched signup, the signup owner owns the review. If it touched checkout, the checkout owner owns the review. If it touched onboarding, the onboarding owner owns the review. Engineering still investigates technical evidence. Product still interprets behavior. The owner keeps the decision moving.

A path owner should be able to say:

this deploy touched my path
this metric defines path health
these evidence links matter
this is stable, watch, investigate, or rollback candidate

That ownership model prevents the team from debating whether PostHog or Sentry is the "real" source. The real source is the review packet. The tools provide evidence.

What if the answer is no action?

A good deploy review often ends with no action. That is not wasted work.

If the route stayed stable, the team learned that the release did not damage the protected path. If the route moved but traffic mix explains it, the team avoided a false incident. If product behavior changed but Sentry stayed quiet, the team learned to investigate UX or copy before chasing exceptions. If errors increased but the path stayed healthy, the team can prioritize cleanup without treating it as a product emergency.

The value is not always a rollback. The value is a decision with evidence.

That decision becomes part of release memory. The next time signup moves, the team can compare against prior reviews instead of starting from scratch. Over time, the route review becomes a habit: every important deploy leaves behind a short record of what happened to the customer path.

Sources

[C1] PostHog Next.js docs - Product analytics, feature flag, and event instrumentation for Next.js apps.
[C2] Sentry for Next.js - Error monitoring, performance monitoring, tracing, replay, and release debugging for Next.js.
[C3] Vercel Analytics - Page-level visitor analytics for Vercel applications.
[C4] Next.js OpenTelemetry guide - Official route, fetch, and span instrumentation guidance for Next.js.

CI Can Take Screenshots. It Should Not Publish Them Blindly.

jake — Thu, 09 Jul 2026 14:30:37 +0000

CI is a good place to generate product screenshots. It is a dangerous place to publish them without review.

A browser can open the product, load a fixture, wait for the UI, capture the page, and store the result as a build artifact. Playwright supports page screenshots, full-page screenshots, element screenshots, and buffers. GitHub Actions can run the job on pull requests, scheduled builds, or docs changes. Tools like shot-scraper make website screenshot capture easy to script.

The capture problem is manageable. The publishing problem is where teams get hurt.

A CI screenshot can be technically fresh and still wrong for the docs.

Treat screenshots like build artifacts

A build artifact has provenance. It came from a commit, a workflow, an environment, and a set of inputs. A docs screenshot needs the same treatment.

If a screenshot appears in public documentation, the team should be able to answer:

Which commit generated it?
Which route did it capture?
Which fixture or account state was loaded?
Which viewport and theme were used?
Which selector proved the page was ready?
Which docs page uses the asset?
Who approved the replacement?

Without that trail, the screenshot is just a generated PNG. It may be correct. It may be a loading state with nice pixels.

Artifact field	Example
Commit	pull request head SHA
Route	\/settings\/api-keys
Fixture	team workspace with one active key
Viewport	1440x900
Ready condition	data-docs-ready="api-keys"
Capture target	API key table panel
Docs usage	docs\/api-keys\/create.mdx
Review state	approved, rejected, needs scenario fix

This metadata is what makes CI screenshots safe to review.

Separate screenshot tests from docs screenshots

Visual regression tests and documentation screenshots overlap, but they are not the same job.

A visual regression test asks, "Did the UI change unexpectedly?" A docs screenshot asks, "Does this image still teach the product step correctly?"

The same browser capture may support both jobs, but the review rules are different. A pixel difference can fail a regression test. In docs, a pixel difference may be the expected result of a product improvement. Conversely, a screenshot can pass a pixel threshold and still be bad documentation if it shows the wrong user state or crop.

A clean CI design keeps the outputs separate:

Output	Owner	Decision
Visual regression result	Engineering	Pass, fail, update baseline
Docs screenshot artifact	Docs, product, or support owner	Approve, reject, request scenario fix
Public docs asset	Docs publisher	Replace only after approval

That separation prevents engineering test baselines from becoming public documentation by accident.

Make product state deterministic enough

Screenshot CI fails when the product state depends on live data, random accounts, timestamps, or whatever a developer had in their local workspace.

The fix is not always a full fake backend. Start with the state that matters for the screenshot. If the screenshot teaches API key creation, the page needs a workspace with a known key state. If it teaches billing settings, the page needs a known plan and payment state. If it teaches integration setup, the page needs connected and disconnected variants.

Useful controls include:

seeded demo workspaces
mocked network responses for unstable external data
fixed dates and time zones
explicit feature flag values
test users with known roles
data attributes for capture targets and ready states

The goal is not to make the entire product deterministic. The goal is to make the screenshot state reproducible.

Wait for the UI you mean to capture

A surprising number of bad screenshots are readiness bugs. The browser captured too early. A skeleton was still visible. A chart had not drawn. A toast covered the button. A font swapped after capture. A settings panel was still animating.

The wait condition should be part of the scenario, not an invisible sleep.

Weak:

wait 3000ms
take full-page screenshot

Better:

open route
wait for account fixture to load
wait for data-docs-ready="billing-settings"
capture locator for the billing panel

Playwright gives teams the browser primitives. The scenario should express what "ready" means for the docs image.

Do not auto-replace public docs on every run

The safest default is: CI generates, humans approve, publishing replaces.

Auto-replacement can work for low-risk internal references. It is risky for public product documentation, especially setup flows, compliance screens, billing pages, admin permissions, and integration guides. Those images carry trust. A wrong screenshot can make the docs look current while making the instruction worse.

Use review states:

State	Meaning
Generated	CI produced the screenshot
Changed	The artifact differs from the current docs asset
Needs review	A human must approve replacement
Approved	The screenshot can publish
Rejected	The asset is wrong or docs need editing
Scenario fix needed	The automation captured the wrong state

This gives the team a lane for screenshots instead of a folder of files.

Use Reshot between CI and the docs repo

Reshot keeps the screenshot scenario, CI artifact, review decision, and approved docs asset together. It does not replace Playwright. It does not replace your CI provider. It gives the screenshots a workflow.

A practical setup looks like this:

Define scenarios for screenshots that matter.
Run the scenarios in CI when product or docs inputs change.
Store generated artifacts with commit, route, fixture, viewport, and docs usage.
Send changed screenshots to review.
Publish approved assets back to the docs repo or asset store.

This is how CI becomes useful for documentation screenshots without becoming reckless.

The browser can take the picture. The team still needs to decide whether the picture belongs in the docs.

Name artifacts so people can debug them

Screenshot artifacts often fail at the boring layer: naming. A folder called screenshots is not enough when a reviewer needs to know which product state produced an image.

Use names that carry useful context without becoming unreadable:

Naming part	Example
Product area	settings-api-keys
Scenario state	one-active-key
Viewport	desktop-1440
Theme or locale	light-en
Commit or run id	pr-1842

A generated file like settings-api-keys_one-active-keydesktop-1440_pr-1842.png is not beautiful, but it is debuggable. The reviewer can tell what it is before opening it. The CI logs, artifact store, and docs replacement step can all refer to the same object.

Pair the file name with a small metadata record. The metadata should include the route, fixture, ready condition, capture target, docs page, and reviewer state. That turns a PNG into a traceable artifact.

Record common failure modes

The first few CI screenshot failures will teach the team more than the happy path. Capture them as scenario fixes instead of one-off debugging.

Common failure modes include:

app captured before hydration finished
test account missing required plan or role
modal or toast covering the target element
external integration state unavailable
browser viewport different from docs layout
animation or chart rendering after capture
feature flag exposing a different UI than production

Each failure should improve the scenario. Add a better ready signal. Seed the fixture. Mock the unstable response. Capture the locator instead of the full page. Pin the feature flag. The point is not to make screenshots flawless immediately. It is to make the workflow more deterministic each time it fails.

This is why review is so important. Review does not only protect the docs. It improves the screenshot system itself.

Sources

[C1] Playwright screenshots - Official screenshot APIs for pages, locators, full-page captures, and buffers.
[C2] GitHub Actions docs - Workflow automation and artifacts in CI.
[C3] shot-scraper docs - Scriptable website screenshot capture.

Playwright Screenshots for Documentation: What to Automate and What to Review

jake — Wed, 08 Jul 2026 14:30:37 +0000

Playwright can take the screenshot. It cannot decide whether that screenshot still belongs in your docs.

That distinction matters. Playwright's screenshot guide covers the mechanics: full-page captures, element captures, buffers, clipping, image quality, and file output. Those primitives are exactly what a docs team needs to stop retaking the same product screenshot by hand.

But documentation screenshots are not ordinary test artifacts. A product image in a setup guide is part of the instruction. It has to show the right user state, the right public UI, the right viewport, and enough surrounding context for a reader to complete a task. Automation helps only when it creates a reviewable artifact instead of a folder full of mystery PNGs.

Automate repeatable product states first

The best first candidates are screenshots where the product state is repeatable and the cost of staleness is high.

Start with the screenshots that help users finish operational tasks: creating an API key, connecting an integration, changing a billing setting, configuring OAuth, exporting data, or checking an admin permission. These screenshots usually have a known route, a stable UI target, and a docs page that depends on them. They are much better candidates than launch collages, annotated marketing images, or one-off editorial visuals.

Playwright's locator screenshot support is especially useful here because many docs images should show a panel, table, modal, or settings section rather than the entire browser window. Capturing a locator keeps the screenshot tied to the instructional object.

Put the screenshot in a scenario manifest

A Playwright test file can capture a page, but the docs team needs more than executable code. It needs a scenario record that explains why the screenshot exists.

A useful scenario manifest contains:

Field	Example
Docs page	docs/integrations/github.mdx
Product route	/settings/integrations/github
Fixture	workspace with GitHub connected
Viewport	desktop 1440x900
Theme	light
Ready signal	data-docs-ready="github-connected"
Capture target	integration settings panel
Output	static/img/integrations/github-connected.png
Owner	docs-platform

This manifest is not bureaucracy. It is the maintenance contract. When the UI changes, the reviewer can see what state the screenshot was supposed to show. When capture fails, the engineer can tell whether the route, fixture, selector, or docs path is wrong.

Use Playwright for readiness, not sleeps

Documentation screenshots often fail in a boring way: the browser captures too early.

A skeleton is still visible. A chart has not rendered. A toast covers the button. A font swaps after the screenshot. A menu animation has not finished. The screenshot looks plausible, but it teaches the wrong thing.

Do not hide readiness in a long timeout. Express it in the scenario. The runner should navigate to the route, select the fixture, wait for the loaded state that matters, confirm the target element is visible, and only then capture the intended locator.

Playwright's docs for screenshots show how simple the capture call can be. The hard part is the sentence before it: "This page is now in the state the docs need."

Separate visual tests from docs screenshots

Playwright also supports visual comparisons, and teams often ask whether docs screenshots should just be visual tests.

They overlap, but they are not the same workflow.

A pixel diff is useful evidence, not the final decision. If a button moved because the product shipped a better layout, the docs screenshot probably should change. If the image changed because the capture account lost access to a feature, the screenshot should not publish.

Visual comparison asks whether the UI changed unexpectedly. Documentation screenshot review asks whether the image still teaches the step correctly. The same browser capture can feed both workflows, but the decision record should be separate. Visual testing protects UI behavior. Screenshot review protects public instructions.

Store artifacts with enough context

GitHub Actions artifacts are a good place to store generated screenshots during CI. The important part is naming and metadata.

A screenshot artifact should answer basic questions without asking the reviewer to inspect CI logs. It needs the commit, scenario, route, fixture, viewport, theme, current docs asset, and whether the candidate differs from the approved version.

Use names that are readable in a CI artifact list:

settings-api-keys__one-active-key__desktop-1440__light__pr-1842.png

The file name does not need to carry everything. Pair it with a small JSON record containing route, owner, ready signal, docs path, and review status. That turns a Playwright output file into a docs artifact.

Review what automation cannot know

Automation can detect that an image changed. It cannot know whether the change is useful, public, or misleading.

Review is where docs, product, support, and engineering have different but useful perspectives. Engineering can tell whether the UI state is valid. Docs can tell whether the screenshot still supports the surrounding copy. Support can spot the states users misunderstand. Product can confirm whether the flow is ready to describe publicly. If a banner, toast, wrong account, unreleased flag, or bad crop appears in the image, the reviewer catches it before the docs inherit the mistake.

Publish only after approval

A safe pipeline has two distinct jobs:

Generate screenshots from Playwright scenarios.
Publish approved docs assets.

Do not collapse those jobs just because CI can write to the docs repo. A technically fresh screenshot can still be wrong. It can show a test account, a transient experiment, a loading state, or a feature that has not launched.

Use review states, but keep the state model simple. A screenshot is generated, changed, needs review, approved, rejected, or blocked on a scenario fix. That is enough to keep CI fast and publishing conservative without turning the workflow into a status taxonomy.

Use Reshot as the artifact layer

Reshot fits between Playwright and the docs repository. Playwright handles browser automation. GitHub Actions or another CI system runs the job. Reshot keeps the scenario, generated screenshot, metadata, review decision, and approved output together.

That lets teams automate the repeatable parts without losing editorial judgment. A practical Reshot setup defines scenarios for the screenshots that matter, runs Playwright when a scenario input changes, stores the generated image with metadata, routes changed screenshots into review, and publishes only the approved asset back to the docs path.

Playwright is the capture engine. Reshot is the place where the capture becomes a documentation artifact with state, ownership, and a decision.

Sources

[C1] Playwright screenshots - Official screenshot primitives for page, full-page, buffer, and locator capture.
[C2] Playwright visual comparisons - Official guidance for snapshot and visual comparison testing.
[C3] GitHub Actions workflow artifacts - Official artifact upload, download, and retention guidance.
[C4] shot-scraper - Open source CLI project for automated website screenshots.

Next.js Observability Is Not Deploy Impact

jake — Tue, 07 Jul 2026 14:30:43 +0000

Next.js observability tells you what the application is doing. Deploy impact tells you whether the release changed a product path that matters.

Those are related questions, but they are not the same question.

A team can have Sentry installed, OpenTelemetry spans flowing, Vercel Web Analytics enabled, Speed Insights collecting Core Web Vitals, and product analytics events in place. The deploy can still leave everyone asking the same awkward question: did this release hurt signup, checkout, onboarding, invite acceptance, or another route customers actually feel?

The missing layer is not more raw signal. It is the review that ties signal to a deploy, a route, a protected metric, and a decision.

Observability gives you witnesses, not the case file

The official Next.js OpenTelemetry guide describes instrumentation for route rendering, fetches, API routes, metadata generation, and custom spans. That is useful engineering evidence. It can tell you that a route got slower, a fetch changed shape, or a server action became noisier.

Sentry's Next.js docs explain how to collect errors, performance data, replays, logs, and tracing context from a Next.js app. That is also useful evidence. It can tell you when a release introduced a new exception or made a transaction slower.

Vercel Web Analytics gives page and visitor behavior. Vercel Speed Insights helps watch real-user performance signals. PostHog's Next.js docs cover product events and feature flags.

All of those tools answer important questions. Error monitoring can show a runtime failure. Tracing can show a route, fetch, or handler changing shape. Web analytics can show page traffic and visitor behavior. Product analytics can show funnel movement. Deployment metadata can show what shipped and when.

None of that automatically decides whether the product path got worse because of the release. Deploy impact starts when those witnesses are attached to the same release question.

The deploy question is narrower than the observability question

Observability asks: what is happening in the system?

Deploy impact asks: after this deploy, did this product path get worse?

That narrower question is why the review should start with a route, not a dashboard. If a pull request touched /signup/company, the first review target is signup completion and the evidence around that path. If it touched payment state, the first review target is checkout completion and payment failure context. If it changed auth middleware, the first review target may be login success, invitation acceptance, and protected route access.

The route keeps the review honest. Without it, the team can waste time scanning broad charts until one of them looks interesting. With it, the team can move in a straight line: anchor the question to a deploy, name the path a user could feel, compare the path against a health metric, then decide whether the companion evidence supports action.

The answer may still be "no action." That is fine. A reviewed stable path is useful release memory.

A green deploy is only a shipping fact

Vercel's deployment docs are clear that every successful build creates a deployment with its own URL, and Git pushes or pull requests can trigger those deployments. That is the shipping layer.

The product layer starts after the deployment exists.

A successful build tells you the app was assembled and deployed. It does not tell you whether users completed signup at the same rate. It does not tell you whether the pricing page sent fewer people to checkout. It does not tell you whether a validation change increased retries without throwing an exception.

This distinction matters because a team can mistake platform health for product health. The build may pass while signup gets slower. Sentry may stay quiet while checkout completion dips. Web Vitals may stay normal while an onboarding step becomes confusing. Product analytics may show a dip that is later explained by traffic mix rather than code.

The review should preserve both facts: the deploy was technically green, and the path still needs evidence.

Use a deploy impact packet

A deploy impact packet is small enough to become habit. It is not a postmortem. It is not a dashboard replacement. It is the minimum object that keeps the release question from scattering.

Field	Example
Deploy	Commit, deployment URL, shipped time
Pull request	What changed and who owns it
Path	`/signup/company`, `/checkout`, `/onboarding/connect`
Protected metric	Completion, successful submit, activation, payment success
Before window	Comparable traffic before release
After window	First stable traffic window after release
Evidence links	Sentry issue, trace sample, PostHog funnel, Vercel page
Decision	Stable, watch, investigate, rollback candidate

The packet is deliberately boring. Boring is useful when a chart is moving and everyone wants to jump to a theory.

Watch for the false comfort of complete instrumentation

Instrumentation coverage can become its own trap. Once a team has enough traces, events, logs, and analytics, it is tempting to believe the answer is in there somewhere. It usually is. The problem is retrieval under pressure.

If the team has not named the path, the search space is too large. If it has not named the deploy, every chart becomes a possible coincidence. If it has not named the decision state, the review ends as a Slack thread instead of an action.

The decision language should stay plain. Stable means the protected metric stayed in range and evidence is quiet. Watch means the path moved, but traffic, sample size, or companion evidence is mixed. Investigate means the path moved and the deploy plausibly touched it. Rollback candidate means the path moved and technical evidence points to the same release.

That standard does not require perfect causality. It requires enough evidence to choose the next action.

Decide what to review before the release

The best post-deploy review starts in the pull request.

If a PR touches a value route, add the post-deploy review target before merge: affected path /signup/company, protected metric company signup completion, evidence to check in validation errors, signup funnel, and route traces, owner onboarding, review window first stable post-deploy traffic window. That short note changes the release habit. The team is no longer surprised after the chart moves. It already knows which path deserves attention.

This is where TrueClara fits. It keeps the deploy, path, metric, evidence links, and decision together. Sentry remains the place to inspect errors and traces. PostHog remains the place to inspect events and funnels. Vercel remains the place to inspect deployments, page behavior, and performance. TrueClara keeps them attached to the product path the release may have changed.

Observability tells you what the system emitted. Deploy impact tells you whether the release changed the path customers care about. Next.js teams need both, but they should not confuse one for the other.

Sources

[C1] Next.js OpenTelemetry guide - Official Next.js guide for instrumentation, default spans, custom spans, testing, and deployment.
[C2] Sentry Next.js docs - Sentry setup and monitoring documentation for Next.js applications.
[C3] Vercel Web Analytics - Vercel documentation for page and visitor analytics.
[C4] Vercel Speed Insights - Vercel documentation for real-user performance measurements.
[C5] Vercel deployments - Vercel deployment methods, URLs, environments, and deployment metadata.
[C6] PostHog Next.js docs - PostHog setup guidance for Next.js, events, and feature flags.

AIF-C01 exam dumps: the real cost, and what to do instead

jake — Thu, 02 Jul 2026 14:30:31 +0000

Short version: if you're searching for AIF-C01 dumps, you're almost certainly not looking to cheat — you're looking to stop spinning your wheels and just pass. Fair. But dumps are a worse bet than they look: they risk your certification, they're often wrong, and they don't make you ready. The good news is the efficient path you actually want exists, and it's not much slower.

What "exam dumps" really are

A dump is a set of supposedly real exam questions, copied from people who recently sat the test and reposted on a forum or a paid site. Two problems are baked in:

They're frequently wrong. Dumped questions are transcribed from memory and "answered" by community vote. On foundational AI topics — where the right answer often hinges on a single AWS service detail — a confidently-upvoted wrong answer is worse than no answer at all.
They go stale fast. AWS rotates exam forms, and AIF-C01 covers fast-moving ground (generative AI and foundation models are over half the blueprint). Last quarter's dump is studying for an exam that no longer exists.

The cost that doesn't show up until later

Using real exam content violates the AWS Certification agreement and NDA you accept before every exam. AWS actively pursues this. The documented consequences include having your result invalidated, your certifications revoked, and a ban from future exams. A revoked cert on a background-checked résumé is a far bigger problem than an extra week of study.

And there's the quieter cost: even if a dump "works," you walk into the job having memorized answers to questions you'll never be asked again, instead of understanding Bedrock, SageMaker, foundation models, and responsible-AI guidelines well enough to use them. The certification was supposed to be a proxy for that understanding. Dumps optimize away the only thing it was measuring.

What you actually want instead

The honest reason people reach for dumps is they want certainty that they're ready without grinding endlessly. That's a reasonable thing to want — it's just available without the risk:

Study from the blueprint, not from memory. The public AIF-C01 exam guide lists every domain and task. Work the official AWS docs for each, weighted by exam share: Applications of Foundation Models (28%) and Generative AI fundamentals (24%) are more than half the exam.
Practice on source-traced questions. Use questions written from the blueprint and official docs, each with the source behind its answer — so when you get one wrong, you learn the real thing, not a forum's guess.
Get a readiness signal you can trust. This is the part dumps are a broken substitute for. You don't want "I saw these questions before" — you want "my projected score clears 700 with margin." Those are different, and only one survives a fresh exam form.

How CutScore covers exactly that gap

CutScore is built on a hard line: no brain-dump sources and no real exam content, ever — only the public blueprint and official documentation. Every question is independently authored and source-linked. And the readiness number is deliberately conservative: it says "ready — book your exam" only when the lower bound of your projected score clears the pass bar and you've covered every domain. It would rather show you no number than tell you you're ready when you aren't.

That's the certainty you were looking for in a dump — minus the wrong answers and the risk to your certification.

FAQ

Are AIF-C01 dumps illegal? Using real exam content breaches the AWS Certification NDA you agree to before testing. AWS can invalidate results, revoke certifications, and ban you from future exams.

Aren't some "dumps" just practice questions? Legitimate, independently-authored practice questions written from the public blueprint are fine and useful. The problem is specifically transcribed real exam content — and many free dump sites mix the two without telling you which is which.

How long does it really take to pass AIF-C01 without dumps? Most candidates with some cloud exposure need a few focused weeks. The bottleneck isn't volume — it's knowing when you've done enough, which is exactly what a calibrated readiness score answers.

Skip the risk. See where you actually stand with CutScore →

The Deploy Shipped. The Route Got Worse. Now What?

jake — Wed, 01 Jul 2026 14:30:46 +0000

A route regression after deploy is not an alert by itself. It is a question the team has to answer before the release fades into memory.

The app stayed up. The deploy was green. Error volume did not explode. But a route that matters started behaving differently. Signup completion softened. Checkout abandonment rose. Invite acceptance dipped. Onboarding step two suddenly had more exits than usual. That is the gray zone where most teams lose time, because every tool has a piece of the story and none of them owns the decision.

The fastest review is narrow: one deploy, one route, one path metric, one evidence packet, one decision.

Start with the route, not the dashboard

The first mistake is opening every dashboard before naming the thing that changed. A dashboard can tell you many things. It cannot decide which user path deserved protection from this release.

A route regression review starts with a sentence like this:

Deploy 9f3c changed company signup validation. Review \/signup\/company completion for the first stable post-deploy window.

That sentence has a deploy, a route, and a behavior. It is much stronger than "conversion looks down," because it tells an engineer where to look and tells a product owner what is at risk.

In a Next.js application, the route can be literal or conceptual. It might be one page, one server action, a multi-step checkout flow, or the route group behind an integration setup. What matters is that the review maps the release to the customer path.

If the deploy touched	Review first
Signup form, validation, identity copy	Signup completion and validation errors
Checkout page, payment state, pricing logic	Checkout completion and payment failures
Onboarding steps, empty states, workspace creation	Step completion and activation
Auth middleware, session handling, invitations	Login success and invite acceptance
Integration setup, OAuth, API keys	Successful connection and retry rate

Whole-product averages are useful later. They are weak at the start. A route can regress while the site-level chart looks normal.

Freeze the release context while it is still fresh

Every route review needs a small case file. Not a postmortem. Not a long incident document. Just the facts that make the question answerable tomorrow.

Capture the deploy time, commit, pull request, author, touched route, owner, protected metric, before window, after window, and evidence links. This gives the team a shared object instead of a pile of tabs.

The tools you already use matter here. Sentry for Next.js can show errors, traces, replays, and performance context. PostHog's Next.js docs show how product events and feature flags can be captured in a Next.js app. Vercel Analytics gives page-level visitor behavior. The Next.js OpenTelemetry guide explains the instrumentation layer for route rendering, fetches, and spans.

Those tools are witnesses. The case file is the review.

A useful packet looks like this:

Field	Example
Deploy	9f3c, June 26, 10:14 UTC
Pull request	Changed signup validation and company field copy
Route	\/signup\/company
Protected metric	Company signup completion
Before window	Previous comparable traffic window
After window	First stable traffic window after deploy
Evidence	Sentry validation errors, product funnel, trace sample, route analytics
Decision	Stable, watch, investigate, or rollback candidate

The point is not bureaucracy. The point is making the next action obvious.

Compare the route against itself

A route regression review should not begin by comparing the route to the whole product. It should compare the route against its own expected behavior.

Ask four questions in order:

Did the route move after the deploy?
Did the deploy plausibly touch that route or the data behind it?
Did companion evidence move in the same direction?
Is the right decision stable, watch, investigate, or rollback candidate?

The companion evidence matters because timing is not causality. A traffic source can change. A campaign can start. A bot spike can hit the route. A feature flag can expose a different audience. A payment provider can have a bad hour. If completion dipped after deploy but errors, traces, traffic, and event mix do not support the same story, the right answer may be watch.

But if completion dipped, the PR touched the same path, Sentry shows a new validation exception, and replay samples show users stuck on the same step, the review has enough evidence to become an investigation.

Use decision states that do not require a meeting

The review should end in a state. Not a vibe. Not a paragraph of hedging. Four states are enough.

State	Use it when	Action
Stable	The route stayed within expected range	Record the review and move on
Watch	The route moved but evidence is mixed or traffic is thin	Recheck after more traffic
Investigate	The route moved and the deploy plausibly touched it	Assign an owner and inspect linked evidence
Rollback candidate	The route moved and telemetry points to failure on the same path	Prepare rollback or hotfix discussion

"Watch" is not weakness. It prevents teams from pretending every chart movement is a release failure. "Rollback candidate" is also not panic. It says the evidence is strong enough to justify a serious rollback conversation.

The discipline is to record the state while the context is still attached to the deploy.

Write the note someone can act on

A good route review note is short and specific:

Deploy 9f3c changed company signup validation. \/signup\/company completion dropped in the first stable post-deploy window. Sentry shows new validation errors on the same route. Marked investigate. Owner: onboarding.

That note can live in a release log, a PR comment, an incident timeline, or a Slack thread. It gives the next person enough to act without reconstructing the whole story.

A weak note looks like this:

Signup looks weird after deploy.

That is not a review. It is a hint.

Decide what to review before the next deploy

The strongest route regression workflow starts before the release. If a pull request touches checkout validation, the review target is checkout completion. If it touches onboarding copy, the review target is onboarding step completion. If it touches auth middleware, the review target might be login success and invite acceptance.

A pre-deploy note can be tiny:

Route touched: \/signup\/company
Protected metric: company signup completion
Evidence to check: validation errors, signup funnel, route traces
Owner: onboarding
Review window: first stable post-deploy traffic window

That note changes the post-deploy conversation. Instead of asking "what happened?" the team asks "did the protected path stay healthy?"

Use TrueClara for the case file

TrueClara keeps the deploy, route, metric, evidence links, and decision together. Sentry remains where you inspect runtime failures. PostHog remains where you inspect events and funnels. Vercel remains where you inspect page behavior. OpenTelemetry remains where you inspect request-level detail.

The missing layer is the review object that ties those signals to the release.

When the next deploy ships, do not start with every dashboard. Start with the route the customer feels. If it stayed healthy, record that and move on. If it moved, attach the evidence. If the evidence points to the release, investigate. If the same path is failing, make the rollback conversation concrete.

A green deploy tells you the release shipped. A route review tells you whether the path survived it.

What counts as enough evidence

A route review does not need courtroom certainty. It needs enough evidence to choose the next action.

For a stable decision, the protected metric stayed in range and no companion evidence contradicts it. For watch, the route moved but the sample is thin, the traffic mix changed, or the supporting signals disagree. For investigate, the route moved and the deploy plausibly touched the path. For rollback candidate, the route moved and technical evidence points at the same release.

That standard keeps the team out of two bad extremes. One extreme is overreacting to every chart movement. The other is waiting for perfect proof while a critical path keeps leaking users.

Use evidence in layers:

Evidence layer	What it tells you
Path metric	Whether the customer action moved
Deploy metadata	Whether the release plausibly touched the path
Runtime signal	Whether errors, latency, or traces changed
Behavior signal	Whether users dropped, retried, or changed flow
Traffic context	Whether the audience changed enough to explain it

The decision is strongest when multiple layers point in the same direction.

Put route review into the pull request habit

Post-deploy review gets easier when the pull request names the path before the release lands.

A useful PR note is short:

affected path: \/signup\/company
protected metric: signup completion
likely evidence: validation errors, route traces, signup funnel
review owner: onboarding
expected review window: first stable post-deploy traffic window

That note helps reviewers see whether the PR touches a critical path. It also gives the post-deploy reviewer a starting point. Nobody has to guess what mattered after the chart changes.

The PR does not need to predict the outcome. It needs to name the path that deserves attention. TrueClara uses that path to keep the release review focused after deploy.

Sources

[C1] Sentry for Next.js - Next.js error monitoring, tracing, replay, and performance context.
[C2] PostHog Next.js docs - Product analytics, events, and feature flag implementation for Next.js.
[C3] Vercel Analytics - Page and visitor analytics for Vercel-hosted applications.
[C4] Next.js OpenTelemetry guide - Official instrumentation guide for Next.js routes, fetches, and spans.

Stop Doing Screenshot Sweeps Before Every Launch

jake — Wed, 01 Jul 2026 14:30:37 +0000

A screenshot sweep feels productive until it becomes the release ritual everyone dreads.

Someone opens every docs page. Someone compares the current UI with screenshots from three months ago. Someone asks which workspace has the right data. Someone retakes a settings page. Someone crops it differently than last time. Someone notices the nav changed in another article. Launch week turns into a scavenger hunt for stale images.

The problem is not that teams forget screenshots. The problem is that screenshots are not connected to the product changes that make them stale.

Stale screenshots are visual debt

Visual debt accumulates whenever a product image no longer matches the current product experience. It is quiet at first. One button label changes. A sidebar moves. An empty state gets redesigned. A plan name changes. The docs still mostly work, so nobody stops the release.

Then support tickets get slower because users do not see what the docs show. Sales engineers stop trusting setup guides. Product marketing avoids screenshots because they might be wrong. Writers spend launch week auditing images instead of improving the page.

The debt exists because a screenshot usually has no owner, no scenario, and no trigger.

Screenshot problem	Operational cause
Old UI appears in docs	No link between UI change and docs asset
Wrong account state	Fixture is implicit or manually recreated
Inconsistent crop	Capture target is not defined
Stale mobile image	Viewport was not part of the scenario
Broken screenshot in release week	Review happens after the product ships

The fix is not a heroic sweep. The fix is to turn important screenshots into maintained scenarios.

A screenshot needs a trigger

A docs screenshot should regenerate when the product area it represents changes. That does not mean every commit should rebuild every screenshot. It means each scenario should know what it depends on.

A setup screenshot might depend on the integration settings page, the connected-state fixture, and the docs file where the image appears. A billing screenshot might depend on the billing route, plan fixtures, and the page that explains invoices. A dashboard screenshot might depend on a demo workspace fixture and a set of chart components.

When one of those inputs changes, the screenshot becomes suspect.

A useful trigger model is simple:

Change detected	Screenshot action
Docs page changed but product route did not	Rebuild linked screenshots for review
Product route changed but docs page did not	Rebuild affected screenshots and flag docs owners
Fixture changed	Rebuild scenarios using that fixture
Viewport or capture target changed	Require review before publishing
Only unrelated code changed	Skip screenshot run

This keeps automation focused. The team reviews screenshots when the product or docs created a reason to review them.

Use browser automation for capture, not judgment

Tools like Playwright are excellent at capturing pages, full pages, and locators. shot-scraper is useful when a team wants a CLI-first screenshot workflow. GitHub Actions can run the capture job in CI and store artifacts.

Those pieces handle capture and execution. They do not decide whether an image still teaches the right thing.

That decision belongs to review:

Is the new UI the public experience?
Does the screenshot match the step in the docs?
Did the automation capture a loading state?
Did a banner, modal, or test account artifact appear?
Does the docs copy need to change with the image?

A changed screenshot is not always bad. Sometimes the product changed correctly. The review exists so the right image publishes with the right explanation.

The scenario is the maintenance contract

A scenario is a small contract between the product and the docs.

It says: to produce this image, open this route, set this state, use this viewport, wait for this element, capture this target, and ask this owner before publishing changes.

That contract removes the guesswork from screenshot maintenance.

Scenario field	Example
Docs page	docs\/integrations\/github.mdx
Product route	\/settings\/integrations\/github
Fixture	workspace with GitHub connected
Viewport	1440x900 desktop
Wait condition	data-docs-ready="github-connected"
Capture target	integration settings panel
Owner	docs-platform

The scenario does not need to be elaborate. It needs to be explicit enough that the screenshot can be regenerated without asking a teammate which account they used last time.

Build a review lane, not a screenshot dump

The common failure mode is a CI job that drops a folder of PNGs somewhere. That is better than manual capture, but it still asks humans to infer what changed.

A review lane should show the scenario metadata with the image:

screenshot name
docs page where it appears
product route captured
fixture and viewport
old asset and new asset
changed reason
reviewer decision

The reviewer should be able to approve, reject, or request a scenario fix. Rejection matters. Sometimes the screenshot is stale because the docs need updating. Sometimes it is wrong because the scenario captured the wrong state. Sometimes the product changed and the docs asset should not publish until the release is public.

Keep the publishing path conservative

Fast generation is good. Conservative publishing is better.

Do not let screenshot automation silently replace public docs assets unless the screenshot category is truly low risk. For product setup flows, billing pages, security settings, admin permissions, and integration states, review should be required.

A practical policy:

Screenshot type	Publish policy
Decorative marketing image	Manual review
Product setup step	Required review
Security or admin setting	Required review
Generated reference image	Review unless scenario is stable and low risk
Test-only internal screenshot	Auto-upload as artifact, never publish

This policy keeps automation from becoming a source of polished mistakes.

Use Reshot to remove the sweep

Reshot is built for the job between browser capture and docs publishing. It keeps scenarios, generated screenshots, review status, and approved assets together.

The workflow becomes predictable:

A product or docs change touches a scenario input.
CI runs the relevant screenshot scenarios.
Reshot stores the generated artifacts with scenario context.
Reviewers approve the screenshots that still teach the right thing.
Approved assets replace the docs images.

That is how teams stop doing launch-week screenshot sweeps. They still review screenshots, but they review the ones that changed for a reason, with enough context to make a decision.

The goal is not to eliminate human taste from documentation. The goal is to stop using human memory as the screenshot system.

Do one inventory, then stop doing sweeps

There is still value in one manual inventory. The point is to make it the last broad sweep, not the new habit.

Start by listing every screenshot in the docs and assigning it a maintenance status:

Status	Meaning
Scenario candidate	Product state is repeatable and useful to automate
Editorial asset	Keep manual, usually launch or narrative imagery
Remove	Screenshot no longer teaches enough to justify maintenance
Replace with text	The step is clearer without an image
Needs product fixture	Valuable, but state is not deterministic yet

This inventory usually reveals that fewer screenshots deserve automation than expected. Some images can be deleted. Some can become text. Some need better product fixtures before capture makes sense. The remaining set becomes the scenario backlog.

After that, stop sweeping the whole docs set before each launch. Review only screenshots connected to changed docs, changed product routes, changed fixtures, or changed scenarios.

Make screenshot ownership boring

A screenshot without an owner becomes everyone's problem and nobody's responsibility.

Ownership does not need to be complicated. Each scenario needs one accountable group: docs platform, product marketing, developer relations, support, product team, or sales engineering. The owner does not have to take every screenshot manually. They decide whether a generated change can publish.

Good ownership answers three questions:

Who reviews changes to this screenshot?
Who fixes the scenario when capture breaks?
Who updates the docs text if the UI changed?

When those answers are visible, stale screenshots stop being surprise work during launch week. They become small review tasks attached to the product changes that created them.

Sources

[C1] Playwright screenshots - Browser screenshot primitives for pages, full pages, and elements.
[C2] shot-scraper docs - CLI workflow for automated website screenshots.
[C3] GitHub Actions docs - CI workflows and artifact handling.

Your Docs Screenshot Is a Build Artifact Now

jake — Tue, 30 Jun 2026 14:30:37 +0000

A documentation screenshot should not be a loose image someone remembers to update before launch.

It should have a source route, a known state, a viewport, a wait condition, an owner, and a review step before it replaces the public docs asset. That is the difference between taking screenshots and operating screenshots.

Teams already know the pain. The product UI changes. The docs screenshot still shows the old nav. A modal moved. A settings page got renamed. A dark-mode screenshot came from the wrong account. Someone notices during release week, opens the product, creates a fake workspace, crops an image by hand, uploads it to the docs repo, and hopes no other screenshot is stale.

That workflow does not scale with a product that ships every week.

Automation starts with a scenario, not a screenshot

Browser automation can capture a page. That part is solved. Playwright's screenshot docs show the core primitives: page screenshots, full-page screenshots, element screenshots, buffers, clipping, quality, and format control. shot-scraper turns screenshots into a developer-friendly CLI workflow, and Simon Willison's launch post names one of the most practical uses: keeping screenshots in documentation up to date.

Those tools answer "can a browser capture this?"

Documentation teams need the next layer: "can we regenerate the right screenshot, in the right state, and know whether it is safe to publish?"

That starts with a scenario.

Scenario field	Why it matters
Route	The product page, docs page, or local preview to capture
State	Signed-in user, plan, fixture data, language, theme, feature flags
Viewport	Desktop, mobile, retina, narrow panel, docs embed size
Ready condition	The selector, network state, or app signal that proves the UI is ready
Capture target	Full page, component, locator, or clipped region
Output path	Where the generated asset lands
Owner	Who approves replacement in docs

A screenshot without a scenario is a file. A screenshot with a scenario is an artifact that can be rebuilt.

Pick one screenshot users depend on

Do not start by automating every image in the docs. That usually creates a brittle pile of scripts and fixtures nobody wants to maintain.

Start with one screenshot that creates support burden when it goes stale:

API key creation
billing settings
OAuth connection
workspace onboarding
integration setup
permission management
dashboard empty state
export configuration

The first scenario should be plain. Open the route. Load deterministic data. Wait for the ready element. Capture the region. Upload the artifact. Ask for review if the output changed.

That is enough to prove whether the workflow belongs in your docs pipeline.

The capture job is not the publishing job

CI can generate screenshots quickly. Publishing should be slower.

A generated screenshot can be wrong for many reasons. The fixture did not load. The user was not signed in. The app showed a cookie banner. The route was half-hydrated. The local server was on the wrong build. A feature flag changed the UI. A loading skeleton got captured. The browser viewport did not match the docs layout.

Automatically publishing that image is worse than leaving a stale screenshot for a day, because now the docs have a fresh-looking lie.

A safer workflow separates capture from approval:

Detect a docs, UI, or scenario change.
Run the screenshot scenarios in CI.
Store generated artifacts with the build.
Compare against the current docs asset.
Mark changed screenshots for review.
Publish only after approval.

GitHub Actions is enough to run this kind of workflow. The missing piece is usually not CI. It is the review object that tells the team what changed and whether the screenshot can replace the docs image.

Screenshots fail when product state is implicit

Most screenshot automation breaks because state is hidden in a human's head.

A person knows which account to use. A script does not. A person knows to dismiss the upgrade modal. A script does not. A person knows the screenshot should show the billing page after a card is attached. A script does not unless the scenario says so.

Make state explicit:

Hidden assumption	Scenario version
"Use the demo workspace"	workspace fixture: demo-docs-workspace
"Make sure billing is active"	plan: team, payment_status: active
"Show the integration connected"	integration: github_connected
"Use the new nav"	feature flag: nav_2026_on
"Crop the settings panel"	capture target: locator('[data-docs-shot="settings-panel"]')

The goal is not perfect determinism on day one. The goal is to remove enough ambiguity that the screenshot can run again next week.

Good documentation screenshots need reviewable diffs

Pixel diffing is useful, but docs screenshots are not visual regression tests in the strict sense. A changed screenshot is not automatically a failure. It may be the point of the product change.

The review question is different:

Did the scenario capture the intended state?
Does the screenshot still teach the step in the docs?
Did the crop, viewport, or density change accidentally?
Is the new UI public and ready to document?
Should the docs text change with the image?

This is why Reshot treats the screenshot as a docs artifact, not just a test output. The artifact needs enough context for a writer, product marketer, engineer, or support lead to approve it without rerunning the whole product in their head.

The scenario file becomes the source of truth

A strong docs screenshot system eventually looks like this:

Layer	Responsibility
Scenario manifest	Defines route, state, viewport, wait condition, and capture target
Browser runner	Uses Playwright or another browser engine to capture the asset
CI workflow	Runs scenarios on relevant changes and stores artifacts
Review queue	Shows changed assets with scenario metadata
Docs repository	Receives approved screenshots only

That architecture is simple on purpose. It lets teams keep Playwright, GitHub Actions, Docusaurus, VitePress, Mintlify, MkDocs, or a custom docs stack. The screenshot workflow sits beside the docs, not inside every writer's muscle memory.

Use Reshot for the reviewable artifact

Reshot turns documentation screenshots into rebuildable, reviewable assets. Playwright can still capture the browser. GitHub Actions can still run the job. Your docs platform can still publish the final image.

Reshot keeps the scenario, generated artifact, review state, and approved output together.

That matters because documentation screenshots fail in the handoff. Engineers can write capture scripts. Writers can spot stale screenshots. Support can tell which steps confuse users. But without a shared artifact, every screenshot update becomes a one-off task.

The practical standard is simple: if a screenshot teaches a product step, it deserves a scenario. If a scenario changes, the screenshot deserves a review. If the screenshot passes review, it becomes the docs asset.

A screenshot is no longer a file someone drags into the repo. It is a build artifact with a reason to exist.

Decide what should never be automated

Not every image in documentation deserves a scenario. Some screenshots are better treated as editorial assets, especially when they are composed, annotated, or designed for a launch narrative rather than a repeatable product state.

Automate the images that teach stable product behavior. Be more careful with images that depend on taste, timing, or campaign context.

Image type	Automation fit
Setup step screenshot	Strong fit
Settings page state	Strong fit
Integration connected or disconnected state	Strong fit
Dashboard with seeded data	Good fit if fixture is stable
Launch marketing collage	Weak fit
Annotated editorial image	Review manually or generate from a controlled source
Customer-specific example	Avoid unless anonymized and approved

This keeps the system from becoming heavy. The goal is not to automate every visual. The goal is to remove manual drift from the screenshots users rely on to complete work.

Keep docs text and screenshots in the same review

A screenshot change often means the text around it needs to change. A button label changes from Create key to Generate key. A setup page moves from Settings to Integrations. A modal becomes a side panel. If the image updates but the instructions do not, the docs still feel stale.

The review should show the docs page where the screenshot appears. That lets the reviewer ask the right question: does this image still support the surrounding instruction?

A strong review packet includes:

old screenshot
generated screenshot
scenario metadata
docs page path
nearby heading or step text
product route
reviewer decision

That is the difference between image replacement and documentation maintenance. Reshot belongs in that maintenance loop.

Sources

[C1] Playwright screenshots - Official documentation for page, full-page, buffer, and element screenshots.
[C2] shot-scraper docs - CLI documentation for automated website screenshots.
[C3] shot-scraper launch post - First-party explanation of screenshot automation for documentation use cases.
[C4] GitHub Actions docs - CI workflow and artifact automation reference.

Your Next.js Deploy Was Green. Did Signup Get Worse?

jake — Mon, 29 Jun 2026 14:31:08 +0000

A deploy can pass every technical check and still make the product worse.

The build succeeds. The Vercel deployment is green. Sentry is not on fire. Nobody is in incident mode. Then the next morning signup looks softer, checkout has a weird dip, or onboarding completion is lower than it should be. The release did not break the app. It may have bent a path that matters.

That is the review most Next.js teams do too late. They look at errors when the question is behavior. They look at a funnel when the missing context is the deploy. They look at page traffic when the path that matters is a user action. The answer is usually spread across Sentry, PostHog, Vercel Analytics, traces, logs, and the pull request.

TrueClara is built around a narrower question: after this deploy, what happened to the route we care about?

Not the whole site. Not every metric. One release. One critical path. Enough evidence to decide whether to ignore it, watch it, investigate it, or roll it back.

Start with the path a customer feels

A “Next.js deploy regression” is rarely a clean red line. It often shows up as hesitation in one path:

fewer users finish /signup
more users abandon /checkout
onboarding completion slips after a server action change
invitation acceptance falls after a layout refactor
API key creation succeeds less often after an auth update
upgrade clicks are stable, but upgrade completion is not

Those are product-path questions. They are not the same as “is the app up?”

The official Next.js OpenTelemetry guide is useful because it shows how deeply Next.js can be instrumented: route rendering, fetches, API routes, metadata generation, and custom spans. That is the raw material. It does not tell you which route deserved a business review after deploy.

Sentry’s Next.js page is useful because it is concrete about error monitoring, performance, tracing, and replays. It gives you runtime evidence. It does not, by itself, decide whether the release made signup worse.

Vercel Web Analytics is useful for page-level behavior. Product analytics tools are useful for funnels and events. None of those are the review. They are witnesses.

The review starts when you name the path.

The wrong first move is opening five dashboards

When a release feels suspicious, the natural move is dashboard-hopping. Open Sentry. Open analytics. Open logs. Open the PR. Ask in Slack whether anyone changed the route. Compare screenshots in your head. Try to remember when the deploy went out.

That works once. It does not become an operating habit.

A better review starts with a small packet:

Field	What goes in it
Deploy	commit, PR, deploy time, author
Path	the route or flow being protected
Path metric	completion, submit success, abandonment, activation, upgrade, invite accepted
Before window	a comparable window before deploy
After window	the first stable window after deploy
Evidence links	Sentry issue, PostHog funnel, Vercel page, trace, replay, log query
Decision	stable, watch, investigate, rollback candidate

That packet is not a replacement for your tools. It is the case file that tells you which tools matter for this release.

Use each tool for the evidence it is good at

Sentry is where you look when the route movement smells like a runtime problem: new exceptions, slower spans, broken server actions, hydration problems, or replays showing users stuck.

PostHog, Amplitude, or another product analytics tool is where you look when the question is behavioral: did users complete the action at the same rate, did a step lose more people, did a feature flag change who saw the new path?

Vercel Analytics is where you check whether traffic or page behavior changed enough to explain the movement. Sometimes the route did not get worse; the audience changed.

OpenTelemetry is where you go when the path needs instrumentation-level explanation. If a route render got slower, a fetch started timing out, or a backend call moved, traces can turn a vague dip into something an engineer can inspect.

TrueClara keeps those signals attached to the deploy and the path, so the review does not dissolve into tabs.

flowchart LR
  Deploy[Deploy] --> Path[Critical path]
  Path --> Metric[Path metric]
  Metric --> Evidence[Evidence links]
  Evidence --> Decision[Stable / Watch / Investigate / Rollback]

Compare the path against itself

Do not start with whole-site conversion. Do not start with all traffic. Do not average the problem away.

If the deploy touched signup, review signup. If it touched checkout, review checkout. If it touched onboarding, review onboarding. Use the deploy timestamp as the anchor, then compare the path against a similar window before the release.

A clean review asks:

Did the protected path move after deploy?
Did the release touch code, copy, data, auth, payment, or routing on that path?
Did traffic mix change enough to explain the movement?
Do errors, traces, replays, or logs point at the same path?
Is this stable, watch, investigate, or rollback candidate?

That last line matters. A graph without a decision is just another tab.

The decision language should be boring

Use four states.

Stable means the path stayed within the expected range. Record it and move on.

Watch means the path moved, but the evidence is mixed. Maybe traffic changed. Maybe a campaign started. Maybe the first post-deploy window is too thin.

Investigate means the path moved and the deploy plausibly touched it. Assign an owner. Open the evidence links. Keep the review tied to the path.

Rollback candidate means the path moved and companion evidence points to the same release. That still does not mean panic. It means the rollback or hotfix conversation is justified.

Here is the kind of note a team can actually use:

Deploy 9f3c touched signup validation. /signup/company completion dropped in the first post-deploy window. Sentry shows new validation errors on the same route. Marked investigate; owner is onboarding.

And here is the kind of note that wastes everyone’s time:

Conversion looks down after the deploy.

One is a review. The other is a weather report.

What PR Impact Preview should show before the deploy lands

The best time to decide what to review is before the deploy ships.

A PR that touches a critical path should say which route it affects and what evidence will be checked after release. If a pull request changes checkout validation, the review target is checkout completion. If it changes onboarding copy, the review target is onboarding step completion. If it changes auth middleware, the review target might be login success or invite acceptance.

That is the point of PR Impact Preview in TrueClara: make the path explicit before the release, then keep the post-deploy review attached to that path.

A useful preview is short:

this PR touches /signup/company
protected metric: company signup completion
companion evidence: Sentry validation errors, signup funnel, route traces
owner: onboarding
review window: first stable post-deploy traffic window

The preview does not need to predict the future. It needs to prevent the team from deciding what mattered only after the chart looks strange.

When the evidence lies

Deploy review gets dangerous when it confuses timing with causality.

A deploy can coincide with a campaign, a pricing change, a bot spike, a feature flag rollout, a backend incident, or a day-of-week pattern. A signup dip after deploy is not automatically caused by the deploy. A checkout drop with no errors is not automatically harmless.

The review packet should make uncertainty visible. That is why “watch” exists. It is also why every decision should carry evidence links instead of a confident sentence with no trail.

The goal is not to prove causality from one chart. The goal is to make the next action obvious enough that the team stops guessing.

What to do on the next deploy

Pick three paths before the next release:

the path that makes money
the path that activates new users
the path that creates the most trust risk when broken

For each path, define one metric that means the path still works. Do not build a giant observability project. Do not instrument everything before reviewing anything. Start with the path where a bad deploy would hurt.

After the next release, create the packet. If the path is stable, save the review. If it moves, attach the evidence. If the evidence points to the release, investigate. If the evidence points to failure on the same path, start the rollback conversation.

A green deploy is not the same thing as a healthy product path. Treat the path as the thing you review.

Sources

[C1] Next.js OpenTelemetry guide - Official Next.js guide for instrumentation, default spans, custom spans, testing, and deployment.
[C2] Sentry for Next.js - Next.js monitoring page covering error monitoring, performance, tracing, replays, and release-adjacent debugging.
[C3] Vercel Web Analytics - Official Vercel docs for page-level analytics and visitor behavior.
[C4] Nurbak: Best Next.js monitoring tools in 2026 - Current comparison-led Next.js monitoring article.
[C5] Google: AI features and your website - Search guidance for crawlable, text-rich, snippet-eligible pages that can appear in AI features.
[C6] Google: using generative AI content - Guidance on AI-assisted content and scaled-content abuse risk.

What Is Visual Debt (and Why Your Docs Are Lying to Users)

jake — Mon, 22 Jun 2026 14:30:50 +0000

Visual debt is the accumulated gap between a product's current interface and the screenshots in its documentation. It compounds with every UI change that is not reflected in docs, eroding user trust and generating support burden. Unlike technical debt, visual debt is experienced directly by end users — and most teams have no mechanism to pay it down.

The definition: visual debt in one sentence

Visual debt is the difference between what your product looks like right now and what your documentation shows. Every screenshot that depicts a button, layout, or workflow that no longer matches the live product adds to this balance. The debt accrues interest in the form of confused users, misguided support tickets, and lost trust in your documentation as a reliable source of truth.

The term is modeled deliberately on technical debt, which Ward Cunningham coined at the OOPSLA 1992 conference to describe the cost of shipping code that reflected an incomplete understanding of the problem domain. Cunningham's insight was that expedient choices in code create a compounding cost — and the longer you wait to address them, the more expensive the fix becomes. Visual debt operates on the same principle, but the interest is paid by your users, not your developers.

I started using this term after auditing documentation for several SaaS products and finding that the visual state of the docs consistently lagged the product by two to four releases. The text was updated, the API references were current, but the screenshots showed UIs that no longer existed. Every time a user followed a screenshot to a button that had moved or been renamed, that was visual debt collecting interest.

The analogy to technical debt is intentional

The power of Cunningham's original technical debt metaphor was that it gave engineering and business teams a shared language. The reason "technical debt" works as a concept is that it reframes an engineering problem in financial terms that executives understand.

Visual debt borrows this framing because the same communication gap exists around documentation quality. When an engineer says "our screenshots are outdated," the response is typically a shrug — it is not perceived as urgent. When they say "we have 80 hours of visual debt and it is generating 15% of our support tickets," the conversation changes.

Property	Technical debt	Visual debt
Coined	Ward Cunningham, OOPSLA 1992	Introduced here
Definition	Cost of expedient code choices	Gap between current UI and docs screenshots
Who pays interest	Developers (slower feature velocity)	End users (confusion, failed tasks)
Compounds via	Code complexity over time	UI changes per release cycle
Detected by	Linters, code reviews, static analysis	Nothing (manual audit only)
Paid down by	Refactoring, rewriting	Re-capturing screenshots (manual or automated)
Tracking tools	SonarQube, CodeClimate, Snyk	None widely adopted

The critical row in that table is "Detected by." Technical debt, for all its challenges, has an ecosystem of tools that surface it. Visual debt has nothing. No linter flags a three-release-old PNG. No CI check compares a screenshot against the live UI. This detection gap is why visual debt accumulates silently until a user files a support ticket saying "your docs show a settings page that does not exist."

Why the conventional advice is wrong

The standard technical writing guidance on documentation screenshots falls into two camps, both wrong:

"Use fewer screenshots" — This is surrender, not strategy. Screenshots are the single most effective way to orient a user in a UI. Removing them to avoid maintenance cost means your documentation is less useful.
"Keep screenshots updated" — This is advice with no mechanism. It is equivalent to saying "have fewer bugs." Without a system that automatically captures and refreshes screenshots, telling teams to keep them updated produces nothing.

The reason both camps of advice fail is that they treat visual debt as a discipline problem when it is actually an infrastructure problem. Teams do not fail to update screenshots because they are lazy — they fail because the process is manual, unowned, and disconnected from the release cycle. Camunda's engineering team reported that their documentation user guide contained 94 screenshots, and that manually recreating all of them for a single release would take one to two full days. Their solution was to automate capture through end-to-end tests — they treated it as infrastructure, not process.

How visual debt compounds

Visual debt does not grow linearly — it compounds. Each release introduces UI changes. Some are cosmetic (a button color change, an icon swap). Some are structural (a page reorganization, a feature rename). Every change that touches a UI element visible in a screenshot creates visual debt. But unlike code changes, where a failing test immediately surfaces the problem, screenshot staleness triggers no automated alert.

The compounding effect works across three dimensions:

Breadth — a single header redesign can invalidate dozens of screenshots simultaneously. When Camunda changed their header, every screenshot containing a header was instantly stale. With 94 screenshots, even a minor navigation change creates a cascading update burden.
Depth — screenshots accumulate over time. A product that ships a release every two weeks with five new features will add 5–15 new screenshots per quarter. If none are being retired, the maintenance surface area grows every sprint.
Velocity — faster release cycles mean faster visual debt accumulation. A product releasing biweekly at a Series B/C stage can realistically invalidate 10–20% of its documentation screenshots per quarter through normal UI iteration. Without automated recapture, the debt balance grows monotonically.

In a typical scenario — a product releasing every two weeks with 8–12% of screenshots affected per release and no automated recapture — over half of documentation screenshots are visually inaccurate within five releases. That is roughly two and a half months. At that point, screenshots are not documentation — they are disinformation.

How to measure your visual debt balance

Visual debt can be quantified. Here is the formula I use:

Visual debt balance (hours) = total screenshots × staleness rate × minutes per manual update ÷ 60

Where:

Total screenshots — count every screenshot in your docs, including variants (mobile, dark mode). A typical B2B SaaS product has 50–200.
Staleness rate — the percentage of screenshots that no longer accurately reflect the current UI. Audit manually or estimate based on releases since last docs refresh. If you have not updated screenshots in three releases, assume 25–40%.
Minutes per manual update — time to navigate to the right state, capture, crop, annotate, export, commit, and deploy. Manual capture typically takes 10–15 minutes per screenshot.

A worked example: a product with 120 screenshots, of which 35% are stale (42 screenshots), each requiring 12 minutes of manual effort to update. The visual debt balance is 42 × 12 ÷ 60 = 8.4 engineering hours. At a fully loaded rate of $75/hour, that is $630 of accumulated visual debt. Multiply by 4 quarterly releases, and you are looking at $2,520/year of recurring manual cost — assuming you actually do the work. Most teams do not, and the debt simply grows.

The only way to pay it down

Manual screenshot maintenance is the documentation equivalent of manual deployments — it works at small scale and fails structurally as the product grows. The only sustainable way to reach and maintain a visual debt balance of zero is to automate documentation screenshots through CI.

The mechanism has three parts:

Declarative screenshot definitions — define what to capture (URL, selector, viewport, wait condition) in a config file that lives in your repo alongside documentation source files. The config is the single source of truth, not a scattered set of PNGs.
Pipeline-triggered capture — wire the capture step into your existing CI pipeline so it runs on every deploy, every PR to main, or on a schedule. This is what Camunda did with their end-to-end test suite.
Stable delivery URLs — serve screenshots through CDN URLs that always resolve to the latest capture. This decouples screenshot freshness from docs deployment — the documentation page is never redeployed, but its images are always current. This is the step that separates a zero-visual-debt architecture from one that merely reduces the manual effort.

The outcome: visual debt drops to zero and stays there. Every git push to main triggers a recapture. Every docs page serves the latest screenshot. No human intervention required.

For the full picture of what visual debt costs and how to architect around it, see what visual debt actually costs your team and screenshots as code.

Frequently asked questions

What is visual debt?
Visual debt is the accumulated difference between a product's current user interface and the screenshots shown in its documentation. Every UI change that is not reflected in docs screenshots increases the visual debt balance. Unlike text-based documentation errors, visual debt is immediately apparent to users — a screenshot showing a button that no longer exists cannot be skimmed past.

How is visual debt different from technical debt?
Technical debt, coined by Ward Cunningham in 1992, describes the cost of expedient code choices. Visual debt describes the cost of expedient documentation choices. The key difference is who experiences the interest: technical debt slows down developers, while visual debt directly confuses end users, generating support tickets and eroding trust in the product.

How do you measure visual debt?
Count the total screenshots in your documentation, multiply by the percentage that no longer accurately reflect the current UI, and multiply by the average time to manually update each one. The result is your visual debt balance expressed in engineering hours. A product with 100 screenshots where 40% are stale and each takes 12 minutes to update carries 8 hours of visual debt.

Why do teams accumulate visual debt?
Visual debt accumulates because screenshot maintenance is entirely manual in most workflows. No CI/CD pipeline catches a stale screenshot. No linter flags a PNG that was last modified three releases ago. The task of updating screenshots has no natural owner — developers consider it a docs problem, and technical writers consider it a product problem. Without tooling that automates the capture-and-update cycle, visual debt is structurally inevitable.

How do you pay down visual debt?
The only sustainable way to pay down visual debt is to automate screenshot capture through CI/CD pipelines. Define screenshot targets in a config file, trigger capture on every deploy, and serve images through stable CDN URLs that always resolve to the latest version. This eliminates the manual cycle that causes visual debt to accumulate in the first place.

Screenshots as Code for Docs

jake — Mon, 22 Jun 2026 14:30:48 +0000

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:

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.

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

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

Pick 10-20 high-traffic screenshots. Choose the ones that appear in your getting-started guide or most-visited docs pages.
Write the scenario config. Define the URLs, selectors, and steps 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.

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.