Constructive Distractions
Backstage
An overlay that turns any prototype into a self-explaining demo — showing stakeholders exactly where data comes from, what's real, what's mocked, and what's still open.
Built for the moment when an engineer in the room asks “is that number real?” and you want a better answer than “yes” or a fumbled explanation.
How it works
A tab peeks on the right edge of the prototype. Clicking it slides open a dark panel — invisible until needed, so the prototype looks clean for the parts of the demo that don't need narration.
Inspector
Top thirdHover or click any annotated element. The inspector shows where that element's data comes from — which API, database, or service — what's computed, a sample request and response, and a one-line note to say aloud. Each element carries a status badge.
Event log
Bottom two-thirdsEvery click on an annotated element appends a card narrating the backend story. "User clicked Verify → POST /kyc/verify → awaiting pass/fail." Newest on top. Builds a running transcript of the demo as you go.
The panel reads from a separate annotations file — one file maps element IDs to their backend descriptions. The prototype markup only gets data-backstage="id" attributes. Everything else is declarative.
The status system
Every annotated element carries one of three statuses. The honest gap isn't a problem to hide — it's the most useful thing to surface live, because it's usually the decision that needs the room's input.
Status
Meaning
When to use
Source confirmed — wired or wireable
You can point to the real endpoint or table.
Stubbed, but the real source is known
Data is faked for the demo, but you know where it'll come from.
Source not yet identified
You're guessing. Say so, and add an open question.
When in doubt, prefer tbd. A demo full of confident-but-fake “live” endpoints falls apart the moment an engineer asks a pointed question.
Adding it to a prototype
Three steps. The annotation file is the only thing that needs ongoing editing.
Tag elements
Add a data-backstage="<id>" attribute to the elements a presenter would point at. Aim for 6–12 per prototype — the ones that carry the demo. Not every div.
Write annotations
In a separate file, map each id to its backend description: where the data comes from, what's computed, a sample request/response, a line to say aloud, and any open questions. Pre-fill what you know; set status to tbd for the rest.
Init the overlay
Load the engine and call Backstage.init(annotations) once after the DOM loads (vanilla), or render <Backstage annotations={...} /> at the app root (React). Off by default — the prototype looks clean until the presenter pulls the curtain back.
Implementations
Two reference implementations — adapt them to match the prototype's conventions. Keep the annotation schema; change the styling freely.
Vanilla JS
No dependenciesA single self-contained script. Load it and call Backstage.init(). Injects its own styles. Works in plain HTML, Vue, Svelte, or any framework where you just want a drop-in script.
React / TypeScript
TailwindA typed React component with Tailwind styling. Render <Backstage annotations={...} /> at the app root. Same structure as the vanilla version — restyle freely, keep the annotation schema.
The annotation file is the artifact that persists after the demo. It's a record of what was real, what was mocked, and what questions were still open — useful for whoever picks up the engineering work next.