A method for taking a clinical or product problem from "we have a ticket" to "we have something concrete enough to evaluate", without jumping straight to high-fidelity design or production code. Written for anyone who wants to build a compelling prototype — designers, QAs, developers, managers.
The point of this work is to make a decision cheap to test. A rough layout that exposes the real problem beats a polished screen that hides it.
One principle organises everything: match the fidelity to the question you are asking. Fidelity is not a quality setting you turn up over time — it is chosen per question. More polish than the question needs is harmful: show stakeholders colour and they comment on colour, when you wanted them to test the flow. Stay only as finished as the decision requires.
Two further principles run throughout:
- Flow over screens. Clinicians judge a journey, not a still frame. Wiring states together keeps the transitions honest and stops you hand-waving the bits between screens.
- Real clinical content, fake data. Use genuine vocabulary — real timescales, thresholds, clinical codes, pathway names — so it reads as plausible to a clinician. The data itself is invented and clearly labelled as illustrative.
Four levels. The thinking work (framing, states, taxonomy, text wireframes) is Level 1; the build spans Levels 2–4. Climb only as far as the question demands.
| Level | Name | Answers | Lives in | Owned by |
|---|---|---|---|---|
| 1 | Text sketch | "Is this worth building? what's the order and hierarchy?" | The chat — no files | Anyone |
| 2 | Skeleton | "Does the flow, navigation and IA hold up?" | Repo, greyscale, no accents | Designer |
| 3 | Demo | "Do clinicians and stakeholders buy this?" | Repo, colour-coded with the brand tokens | Designer + stakeholders |
| 4 | Vertical slice | "Does this hold as real front-end?" | Repo + production design-system components | Developers (+ designer) |
Level 1 — Text sketch. Pure text or Unicode blocks in the conversation. For tiny changes, or to agree order, hierarchy and copy before committing to files. Saves setting up a repo. Limit: it settles order, hierarchy, IA and copy — not proportion, density or spacing. A spacing debate is the signal to graduate.
Level 2 — Skeleton. Plain layout, flow and page structure, intentionally without accents. The first build-up of the concept, and where you lock navigation and information architecture for anything with several surfaces, collections or resources. Quiet, but with clear, real copy — copy is a design decision, not a placeholder.
Level 3 — Demo. Add accents, colour-coding and minimal decoration for a discovery walkthrough with the clinical team and stakeholders. Themed with the brand tokens (see tokens.css). A Demo can be the source of truth — but only for behaviour, flow, states, copy and acceptance criteria, not for final visual styling. Nobody should pixel-match a Demo.
Level 4 — Vertical slice. Real production-design-system components, scaffolded by developers. Best kept to simple front-end-only ideas with a mocked-out back end — not a route to building the full thing. This crosses from throwaway artefact to engineering spike: ownership shifts to developers, and "simple preview" quietly becoming "build the feature" is the main risk. The front-end-only, mocked-back-end boundary is the guardrail.
Shapes: a build at Levels 2–3 is usually an interactive flow prototype (single-file state machine); occasionally a live-control playground (to feel one visual variable) or a print/A4 spec (for a document deliverable). Pick the shape; the level sets the fidelity.
- Gather context, then frame the real problem. Read the epic and tickets, the internal docs, and the relevant clinical guidance (e.g. NICE) for the topic. Tickets often scope too narrowly — one screen, one field — when the real problem is structural. State the broader definition in your own words and flag the mismatch to whoever owns the ticket.
- Name the objects and their states. List what's on the screen as objects (a note, an attribute, a card), then the states each can be in (
draft/posted/amended). Get the state machine right first — most layout problems are state problems wearing a layout costume. - Sort the content — what belongs where and why. In plain words: raw responses vs summary highlights, decided vs needs sign-off. The taxonomy is the spine; the layout just expresses it.
- Wireframe in text — and stop there if it's enough. A text sketch (labelled blocks, nesting, state notes) often settles the question. Don't escalate unless the text genuinely can't carry the decision.
- Build a neutral skeleton only when structure must be felt. When variable content breaks a layout — long labels, eight attributes where there were two, overflowing cards — build it to see it fail. Feed it the hardest real content you have, including the empty case.
- Add accents only for a stakeholder demo. Climb to Level 3 when you need buy-in, and move annotations out of the UI as you do (see chrome, below).
These are the guards that separate a prototype from a compelling one. Apply them at every step.
- Push back. The ticket is a prompt, not a brief. If it frames the wrong problem, say so before designing.
- Clinical safety. Anything patient- or clinician-facing that could mislead stops the flow, however minor it seems.
- Accessibility. Colour is never the only carrier of meaning — always pair it with a text label. Keyboard and focus basics from the skeleton up.
- Copy. Follow the editorial / UI-writing standards for all text: British English, plain language, calm tone, no hype; tone scales with clinical stakes. See oleksiilapenko/editorial.
- Decided vs open. End every pass with two lists — decisions ready to act on, and open questions for the team or research. Never let an assumption masquerade as a decision. This is what lets someone else pick the work up.
"Chrome" means two things; keep them separate.
- Product chrome — the app's own shell (header, nav, patient banner). It climbs the ladder: described in a line at Level 1 → labelled boxes at Level 2 → themed approximation at Level 3 → the real shell at Level 4.
- Prototype chrome — the meta layer about the prototype: mode banners, annotations, state switchers, governance labels.
On explanatory text — where it's allowed, and whether you strip it later — the discipline is separation, not cleanup. Architect annotations so promoting a prototype up the ladder never means hunting through the UI to remove notes.
| Level | Explanatory text |
|---|---|
| 1 Text sketch | All annotation by nature — expected |
| 2 Skeleton | Inline and abundant, but visibly placeholder (bracketed / greyed) |
| 3 Demo | Moves out of the UI body into a separate, toggleable layer — side notes or numbered callouts. UI copy is now real: review-ready and editorial-compliant |
| 4 Slice | None in the artefact — it lives in the ticket / PR description. A note left in code is a defect; it can ship |
Deliberately minimal — speed and zero setup matter more than engineering quality below Level 4.
- Plain HTML, CSS and JavaScript. No framework, no bundler, no
package.jsonuntil Level 4. Open the file in a browser and it runs. - An AI coding tool (e.g. Claude Code) to build from a text wireframe — but someone has to read the output and judge whether the structure holds.
- The neutral token set in
tokens.cssas the skeleton baseline: type scale, spacing, greys, focus ring and a few basic controls, as plain CSS custom properties. It keeps Level 2 → Level 3 continuous. - A CSS micro-library (e.g. Oat UI via CDN) is an optional accelerator when you want ready-made controls without writing CSS. Not the default.
- Single-file prototypes where you can — embedded
<style>and<script>, faster to share and reason about. Mock data in its own seed file so you can swap the scenario without touching the markup.
Below Level 4, don't pull in the production design system — neutral styling keeps focus on structure and avoids coupling a throwaway to a versioned package.
tokens.css is split into a stable neutral base and a brand layer. Theme a Demo by editing the brand layer only; when your design system or branding changes, you swap that one block and the prototype follows. Never cite a Demo's visuals as a final styling spec — styling is the production design system's job.
- Gather context before designing — the epic, internal docs, and relevant clinical guidance.
- Define the problem in your own words first — the ticket is a prompt, not a specification.
- Work the states before the pixels — the layout falls out of the state machine.
- Prefer text wireframes — faster to write, faster to argue with, and usually enough.
- Build to expose failure — feed it the longest label, the most items, the empty case.
- Keep it visually quiet until structure is settled — neutral styling stops people reacting to polish instead of structure.
- Pair colour with a text label — colour is never the only signal.
- Separate decisions from open questions at the end of every pass.
- Don't treat the ticket as the brief.
- Don't design the happy path only — empty, error and overflow states are where low-fi earns its keep.
- Don't reach for high fidelity early — colour, type and spacing decided before structure is settled get thrown away.
- Don't build to answer a question text already answered — if you can't name the question the build answers, don't build it.
- Don't mirror the production design system below the Demo level — neutral keeps focus on structure.
- Don't fake the transitions — wire the states so the journey is honest.
- Don't carry assumptions forward as facts — if the team hasn't signed off, it's open.
The rules above are defaults with reasons, not absolutes. When context genuinely demands a different choice — an established NHS convention, a clinical workflow constraint, a stakeholder need — apply judgement and say which rule you're overriding and why.
Reserve absolute rules for the few that protect the people you test with or ship to:
- faking a transition or journey that wouldn't really work
- letting illustrative data read as a real clinical rule or threshold
- using colour as the only carrier of meaning
- shipping anything that could mislead a clinician or patient about risk or results
Outside those, prefer "default to X, here's when Y is fine" over "never."
<workflow-name>/
├── index.html # the prototype: embedded <style> + <script>, states on one DOM
├── data/
│ └── seed-<scenario>.js # mock data, swappable, labelled illustrative
├── css/
│ └── tokens.css # the neutral token set + brand layer
└── docs/
├── SPEC.md # problem, objects + states, taxonomy, scope, out-of-scope
└── DECISIONS.md # decided vs open, updated every pass