Prototypes as Specs
Clickable Builds That Replaced Written Handoffs
At an AI edtech company running a POC-driven engineering culture, I built prototypes instead of writing specs. A clickable user-acceptance-testing app that let partners review flows before engineering hardened them, a self-service client onboarding portal targeting the slowest step in every launch, a CMS concept, an end-to-end test suite, and an access-gated roadmap viewer. Each one was simultaneously a demo, an alignment artifact, and a living engineering spec.
The Problem
Handoff documents were losing to reality. Design specs ran to dozens of screens that were mostly responsive variants and state permutations of the same surface, so engineers had to reverse-engineer the actual architecture from a flat screen list. Meanwhile the single slowest step in every customer launch was client onboarding — work that sat open for months, almost all of it blocked on a customer handing over usable files with no way to know they were wrong until someone manually checked.
Research & Discovery
Audited why client onboarding was the slowest workstream and found the work sat open for months across customers, nearly always blocked on the client handing over unusable files with no validation until manual review
Reviewed the existing onboarding initiative's shipped phases before designing, specifically to find the gaps rather than duplicate the working parts
Learned to trust design screenshots over exported PDFs after PDF exports repeatedly showed wrong brand palettes and dropped content
Strategy
Golden Path First
One end-to-end flow before any breadth, so every architectural seam is reviewable within days.
Find the Real Surface
38 spec screens collapsed to 6 routes plus one polymorphic player once variants and state matrices were separated out.
Target the Gap
The onboarding portal built only what the shipped initiative hadn't, rather than duplicating working software.
Fidelity to Fit
Canned fixtures, no real parsing. The question was whether the experience was right, not whether the pipeline worked.
Key Decisions
Shipped one clickable golden path end to end before building any breadth. It exercised every architectural seam — router, shell, modal, polymorphic player, results — without exhausting the question-format permutations, which meant the structure was reviewable days earlier
Treated the test player as one route and one component with three swappable subsystems, rather than the twenty-odd screens the spec implied. The spec itself had named the shared-shell pattern; the screen list just obscured it
Built the onboarding portal to deliberately target what the existing initiative had not built, rather than rebuilding what shipped. A prototype that duplicates working software teaches nothing
Kept prototypes at scripted fidelity with canned fixtures and no real parsing. The question they had to answer was 'is this the right experience,' and real data pipelines would have delayed that answer by weeks
Kept prototype work out of the formal spec process entirely. The canonical requirements doc already existed; adding a parallel design doc for a two-day build would have been ceremony, not clarity
Results & Impact
5
Prototypes Shipped
38→6
Screens to Routes
3
Tenant Skins
- Built a clickable UAT prototype that collapsed a 38-screen design spec into 6 routed surfaces plus one polymorphic test player, after recognizing that roughly half the 'screens' were responsive variants, component state matrices, or in-session states of the same shell
- Implemented multi-tenant theming as a CSS-variable swap on a single theme provider rather than parallel route trees, so three customer brand skins shared one codebase
- Shipped a self-service client onboarding portal prototype targeting the un-built depth of an in-flight initiative: content-completeness validation at submit time, self-serve DNS with live verification, and a 'what good looks like' exemplar layer
- Built a Playwright end-to-end suite covering authenticated smoke paths and core user flows for one of the launch apps
- Shipped an access-gated roadmap viewer behind magic-link auth with an email allowlist, served no-index and no-store so an internal planning artifact could be shared with named people without becoming a public URL