hraness
Theme
Appearance

direct: every screen by url, deterministically

screenshots you can trust because the world is fake

drafted with ai assistance by ben guo

the rest of this lesson is free: add your email to keep reading.

Visual verification is usually vibes: run the app, click around, decide it looks right, screenshot it for the record. The screenshot proves the app rendered once, in one person's environment, on one data set they happened to have. It is evidence about a moment, not about the system. Direct exists to make the evidence deterministic.

the screenshot problem

A screen's correctness depends on three things: the code, the data, and the environment (theme, viewport, fonts, time). Ordinary screenshots sample all three at once and freeze none. Reviewing a UI change against production data means reviewing against data that changes; reviewing against developer state means reviewing a state nobody else has.

The question Direct answers: how do you get every interesting screen of a product into a state a test can check? The answer is to make the screen a function of a URL and a declared world.

what a composition is

A Direct composition is a deterministic dev-only arrangement of a product's screens. Each composition declares its world as strict JSON: the exact data the screens render with, the fixed inputs, the seeded values. Every screen in the composition is reachable at a stable URL; driving a browser to the URL reproduces the screen exactly, because the world it renders is data, not ambient state.

The strict-JSON rule is the load-bearing part: the world is data with a schema, parsed and bounded like every other foreign value. A composition cannot smuggle a live service, a clock, or "whatever was in the database"; if the screen needs it, it goes in the JSON, where it can be reviewed, diffed, and versioned with the code it exercises.

how the checks run

Verification drives a real browser to the composition URLs and asserts on the rendered artifact: geometry bounds, contrast, focus order, overflow, and console cleanliness, at phone and desktop sizes. Because the world is fixed, the assertions are stable: the same page produces the same layout, so a check that passes today passes until the code or the declared world changes.

Soundfish and PeopleBlade keep preview compositions on this pattern; Jungle's design-system verification runs the same checks across the shared gallery. The suites catch the classes that matter for UI correctness: content overflowing its container at narrow widths, focus rings lost against themed backgrounds, elements that only exist in one data state the developer happened to have open.

the honest limits

A composition is a claim about the screens it declares. A state that was not declared (a seventh tab, an error path, a data shape outside the JSON) is unverified by construction, which is the same coverage honesty as every other tool in this series: the composition's coverage claim is its declared world.

Direct also verifies rendering, not the live path. The composition's world is synthetic by design, so the checks cannot qualify that the production service returns that shape; that is a different evidence lane (live probes, provider qualification) and the boundary is kept explicit. A screen that renders perfectly in the composition can still break against a live response whose schema drifted, which is why the parsing boundary is a separate discipline.

The third limit is maintenance: a composition that is not updated when the product changes becomes a museum of old screens that still pass. The discipline that keeps it load-bearing is that compositions live beside the code, run in the same gates, and fail loudly when the screen or the declared world drifts out of what the JSON can express.

Inside those bounds, the technique converts UI review from "looks fine to me" into "these exact screens, in these exact states, pass these exact checks," which is the difference between a demo and a gate.

keep reading: free for subscribers

the rest of this lesson is free. enter your email to subscribe, and every subscriber lesson unlocks in this browser.

already subscribed? enter the same email to unlock.