hraness
Theme
Appearance

direct: every screen by url, deterministically

fixed data at a stable url gives the same screen every time

by hraness · drafted with ai assistance

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

A screen can be checked like a function when its data is fixed and it lives at a stable URL. Direct is the Hraness library that sets this up: each screen of a product renders from a declared JSON world, so a browser check against that URL gives the same answer every time the code and the world are unchanged.

why screenshots prove little

The usual visual check is to run the app, click around, and save a screenshot. That shows the app rendered once, in one person's environment, on whatever data they had open.

A screen's appearance depends on the code, the data, and the environment (theme, viewport, fonts, time). An ordinary screenshot captures all of them at once and holds none of them still. Review against production data means reviewing against data that changes, and review against a developer's local state means reviewing a state nobody else has. Direct makes each screen a function of a URL and a declared world.

a composition fixes the data

A Direct composition is a deterministic, dev-only arrangement of a product's screens. It declares its world as strict JSON: the data the screens render, the fixed inputs, and the seeded values. Every screen in the composition has a stable URL, and opening that URL in a browser reproduces the screen, because what it renders is data rather than whatever the machine happens to hold.

The strict JSON rule does most of the work. The world has a schema and is parsed and size-limited like any other outside value. A composition cannot bring in a live service, a clock, or “whatever was in the database.” If a screen needs something, it goes in the JSON, where it can be reviewed, diffed, and versioned with the code it exercises.

what the browser checks assert

Hraness's own browser checks drive a real browser to the composition URLs and check the rendered page at phone and desktop sizes: geometry, contrast, focus order, overflow, and a clean console. With the world fixed, the same page produces the same layout, so a check that passes today keeps passing until the code or the declared world changes.

Soundfish, SlopCamera, and Rough Day keep preview compositions built this way, and Jungle's design-system verification runs the same checks across the shared gallery. The failures these suites catch are the common ones in UI work: content that overflows its container at narrow widths, focus rings that disappear against a themed background, and elements that exist only in the one data state a developer had open.

what a composition cannot tell you

A composition covers the screens and states it declares. A state left out of the JSON, such as a seventh tab, an error path, or an unusual data shape, has not been checked at all.

The checks cover rendering, not the live path. Because the world is synthetic, a passing composition says nothing about whether the production service returns that shape; live probes answer that question. A screen that renders perfectly in the composition can still break when a live response's schema drifts, which is why parsing outside values is a separate practice.

Compositions also need upkeep. One that is not updated when the product changes keeps passing on screens that no longer exist. Keeping compositions beside the code and running them in the same checks as everything else is what makes them fail when the screen or its data moves past what the JSON describes.

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.