An agency portal's design went from 'looks done' to 'is buildable' in one handoff

Representative examplesEvery case study in this library is an illustrative composite of the kind of engagement we deliver — written to show our method and standards, not to name clients.

Where they started

Four people build a client-portal product for creative agencies — two engineers, a founder who sells, and, until shortly before the engagement, a designer. Agencies share deliverables, proofs, and approvals with their own clients through it. The product works and retains agencies, but it grew feature-first: whatever the newest deal needed got built, so screens accumulated with different spacing systems, and the two engineers hold the interface's real spec in their heads.

What it was costing

The previous design handoff shipped beautiful static frames that engineering rebuilt at 60% fidelity — spacing invented, states missing, edge cases undrawn. The dev team had stopped asking questions and just decided things themselves.

What they could see

• The previous handoff's static frames were rebuilt at roughly sixty percent fidelity — spacing invented, hover states missing, edge cases undrawn.
• Engineers had stopped asking design questions and started deciding behavior themselves, so screens shipped that no designer ever approved.
• Fourteen distinct empty, loading, error, and permission states existed in the product but none had ever been designed.
• Every build review surfaced the same argument about what the design intended, settled differently each time.

The constraints we worked inside

• The engineering team was two people — the file had to be navigable by someone with an hour, not a week.
• The product had 14 distinct empty/error/loading states that nobody had ever designed.
• The design had to survive implementation without a designer in the sprint.

What had been tried before

The departing designer produced a polished forty-frame file of final screens, treating completeness as the deliverable.

Nobody could navigate it — no states, no annotations, no build order — so the engineers pulled what they could read and improvised the rest from memory.

Written specs in their project tool described components in prose next to each ticket.

Prose descriptions of visual behavior failed both ways: ambiguous to the engineers, and invisible to whoever picked up the ticket a week later without the conversation.

A mid-project fidelity check was scheduled after each release, with the founder reviewing builds against screenshots.

By then the decisions were shipped and defended; the founder couldn't name what was wrong precisely, and the engineers reasonably asked why nobody said so earlier.

What we proposed

We proposed designing the system the build actually consumes: every screen specified with its empty, loading, error, and permission-denied states, annotated in Dev Mode with behavior notes and token references, and walked through with the two engineers in a guided build-path session. With no designer in their sprints, the file itself had to answer questions instead of provoking them — annotations and auto layout turn measurements into facts. We scoped the first release to the five most-used screens so the two-person engineering team could absorb the new way of working inside a normal sprint rather than a rescue project.

Just as important is what we ruled out, and why:

• A Storybook-first approach where engineers build and document components in code — Two engineers with a feature backlog had no capacity to become the design's maintainers; it moved the workload to the scarcest people without removing the design decisions.
• Hiring a full-time in-house designer to own the backlog — A four-person company couldn't fund the hire, and recruitment would outlast the five-week window — the product needed a system a contractor could leave behind.
• Adopting an existing UI kit to standardize screens quickly — Their product's approval workflows needed bespoke permission states; grafting a kit would solve spacing while leaving the fourteen undesigned states — the actual failure — untouched.

How the work ran

Delivered by the experience pod — 2 designers over 5 weeks, with working increments reviewed with the client every week.

The stack, and the reasoning

Figma

The two engineers already read Figma files, so the system stayed where they were; the win came from structure and annotation, not from switching tools.

Dev Mode annotations

Behavior notes, token references, and specs sit beside the frames they describe, so an engineer with an hour gets answers without a meeting — the handoff's whole thesis.

Auto layout

Proper auto layout made padding and spacing facts instead of eyeball measurements, which is what let the engineers trust the file enough to stop inventing values.

Component variants

Every component shipped with its empty, loading, error, and permission variants attached, so the forgotten states were inside the component — unforgeable by omission, which is how they kept getting lost.

What went wrong

How we worked together

Cadence

A Monday working session with both engineers anchored the week; async questions lived as comments pinned to the frames they concerned, answered within a day.

Client side

The founder made product calls and attended Mondays; the two engineers owned the build path and flagged anything the file couldn't answer.

Decisions

Decisions happened in the file — comments resolved on the frame they referred to — so the rationale stayed where the next question would be asked.

They provided

Access to the staging environment for state-mapping, the founder's time for permission rules, and the engineers' honest list of everything they'd decided without design.

What changed

The headline: design-to-build fidelity on the first post-handoff release, scored by a joint review — 60% → 95%, read from Design QA audit. A second check: undesigned states discovered during the first sprint at 0.

The engineers stopped deciding design by default, and the founder noticed the quiet: build reviews no longer open with what does this screen do. The first post-handoff release scored its fidelity in a joint review, and the engineers' checklist — not the frame count — became the definition of done. When the founder sells the next feature, the file it gets designed into now answers the two engineers' questions before they think to ask, which is the difference between a handoff and a hand-wave.

The result was read from Design QA audit against the pre-engagement baseline over the stated window, with a guardrail check on undesigned states discovered during the first sprint. Where platform-reported numbers and business outcomes differ, this record says which layer it is quoting.

What they own now

• The annotated Figma file with designed empty, loading, error, and permission states
• A build-order checklist mapping the file to sprint-sized engineering work
• The permission state matrix documenting role rules agreed with the founder
• A one-page annotation convention so future files follow the same spec format