The Handoff Is the Bug

A thorough spec isn’t an executable one

The deskcheck at Arcos wasn’t a meeting. It was a Slack channel — and sometimes a long, unwieldy thread trying to get a single component right. A developer would post a Loom video of the work. UX would watch it, trying to investigate what was actually in the code. Was the correct token used, or just a value that looked right on screen? Was that spacing coming from the design system or hardcoded? You couldn’t inspect it through a video. You could only see the surface.

That’s what stuck with me. Not that the developer had done something wrong — they hadn’t. Not that the spec was incomplete — it was thorough. But a comprehensive spec is still interpreted differently by each person who reads it. And when the review mechanism is a Loom video in a Slack thread, UX has no way to verify intent against implementation.

As AI started entering the delivery pipeline — developers feeding specs into models to accelerate their builds — the translation problem didn’t go away. It just moved. Now an AI was misreading the spec instead of a human. We’d automated the ambiguity.

That realization reframed the question. Instead of “how do we write better specs,” I started asking: what if we gave AI better source material to begin with?

The diagnosis

The traditional design-to-dev handoff has always had a lossy translation layer. Designers produce Figma files, annotations, and Zeplin specs. Developers interpret them — making judgment calls about tokens, spacing, component variants, interaction states. Every judgment call is a potential drift from intent.

At Arcos, that translation tax was being paid in two ways: in time, through investigation sprints and spikes at the start of every delivery cycle, and in quality, through the see-build-review-change loops that consumed the back half. A two-week sprint just to ingest design intent. Then cycles of correction after that. The spec was comprehensive. It just wasn’t executable.

What shipped

The artifacts that make this model real, in the order they shipped:

• Harmony Design System — npm package published to production, March 2026.
• Zeplin MCP — in active use by development as of March 2026.
• Storybook on Chromatic — launched April 2026.
• Dual MCP agentic workflow — Zeplin and Storybook MCPs active simultaneously in VS Code.
• Design Implementation Spec — agentically generated, reviewed and validated by the designer.
• Shape Up scope alignment — a cross-functional effort with Product to sharpen Milestone definitions upstream.

The proof that the model works isn’t theoretical. Using Storybook and Harmony, I personally built a functioning testable web concept in 12 hours over 3 days — grounded in UX discovery and requirements, with Pendo tags embedded to track user task completion and flows. A wired Figma prototype covering the same scope would have taken roughly 40 hours. The concept went directly to user testing, and because it was coded rather than simulated, it surfaced interaction behaviors that a Figma prototype would have hidden entirely. No handoff required.

The model is active and expanding. The Control Tower web theme is in test and integration with the production development flow. What started as a workflow experiment is becoming infrastructure.

These metrics come from three delivery cycles on Control Tower — early signal from one platform, not a company-wide result.

The vision — and why it required cross-functional buy-in from the start

I started working toward a different model — one where the UX team transmits design intention in a form that’s closer to code than documentation. Not as a replacement for engineering, but as a cleaner separation of concerns.

The idea was to move the bar left. If front-end visual builds could originate within the UX team — component-correct, pattern-consistent, already informed by the design system — then development could focus on what it does best: backend architecture, data modeling, API integration. Not burning cycles interpreting whether a button should have 8px or 12px of padding.

At the same time, this opened a different opportunity for Product. Simple experiences — low-complexity UI updates that currently require full production cycles — could be built with UX oversight rather than waiting in a delivery queue. Three roles, each elevated to their highest use. That was the vision.

Designers use this model during the Shaping phase of a milestone — building coded concepts to test with users before a feature enters the delivery queue. Developers use it to extend design code that’s already been handed off in the team’s own vocabulary. That dual-user pattern is what makes the handoff genuinely shorter: both roles working from the same artifacts, in the same codebase vocabulary, without a translation step between them.

But I recognized early that this wasn’t a UX decision to make alone. Changing where front-end code originates touches codebase ownership and delivery accountability. I needed product and engineering leadership in the room before anything was built. And I needed my own team to be genuinely capable inside the model — not watching me demonstrate it.

As Arcos’s AI Champion, I led two weeks of training and environment setup to move all three senior designers into VS Code with Claude Code CLI. That’s a real ask for experienced designers who’ve never worked in a terminal. One Senior Designer went deeper — collaborating with me to refine the token sets in both Figma and JSON, and establishing the external JSON file as the canonical source of truth for Harmony’s token layer. The model only holds if the team can run it without me. After those two weeks, they could.

Building the coalition — where alignment held and where it didn’t

I brought the model to three audiences before building anything:

• Individual developers — Buy-in secured. Aligned on reducing investigation overhead.
• Product leadership — Buy-in secured. Saw faster delivery on simple experiences.
• Tech leaders & managers — Partial; pilot running. Core concern: code quality and codebase ownership.

The Tech leader objection had a specific shape that took time to surface. When they pushed back on “UX-generated code entering the codebase,” the artifact in their heads wasn’t a HOC — it was the AI-assisted prototyping work from early in the exploration. Separating those two things was the work the next phase required.

How the model matured — from prototype stigma to production-adjacent components

Responding to that feedback meant making a meaningful technical distinction the early exploration had blurred.

AI-assisted prototyping tools (Lovable, Bolt.new, Figma Make): Fast, generative, great for moving abstract thinking onto a screen. AI-chosen dependencies, no relationship to the production codebase. Correctly perceived by engineering as throwaway.

VS Code + AI agents + Harmony: UX working in VS Code against the actual front-end codebase. Same tokens, same components, same patterns engineering already owns. Higher Order Components that are reviewable, trustable, and mergeable.

A HOC built against the actual front-end stack isn’t foreign. It’s design intent expressed in the team’s own vocabulary.

Harmony — a design language for UX, engineering, and AI

The single source of truth that makes this pipeline possible is Harmony, the Arcos design system — built so UX, engineering, and AI agents can all operate from the same tokens, components, and patterns instead of three different interpretations of the same intent. For the full architecture, see the dedicated case study: Harmony: A Design System Built for Machines.

The agentic workflow — two MCPs, one context window

Knowing what a component should look like (Zeplin) and knowing how a component actually behaves in production (Storybook) are two different things. The old workflow asked developers to hold both in their heads and reconcile them manually. The new workflow makes both available to the AI agent simultaneously, without leaving VS Code.

With the Zeplin MCP and Storybook MCP active at the same time, an AI agent working in VS Code can reference the design spec and the live production component in the same context window. It sees what the designer intended and what the codebase already contains. That dual context is what makes the output production-adjacent rather than prototype-shaped — the AI isn’t filling gaps with guesses, it’s filling gaps with the production component library itself.

Storybook on Chromatic serves both audiences. For humans — designers, developers, QA — it’s a living reference for what every component looks like, across states and variants, at a given point in time. For AI agents, the Storybook MCP turns that same reference into structured context that’s queryable from within the coding environment. One artifact, two consumers. Neither maintains a separate source of truth.

Moving discovery earlier changed what engineers had in front of them by the time a story reached build. High-fidelity design work happened up front, Zeplin annotations documented user type and behavior in detail, and Code Connect kept Zeplin components, Figma components, and the Harmony Storybook tightly linked — so an engineer working in VS Code could pull that context directly through the Zeplin and Storybook MCPs instead of waiting on a clarifying Slack thread. The first coded draft landed closer to the design target: colors and spacing tracked the central token source more consistently, and engineers told me they felt more confident making the small calls themselves — copy voice, interaction behavior — because the documentation actually answered those questions now. Net result: front-end user stories that used to take 5–6 days to complete came in at 2–3. That’s my own read of the work, not a pulled report, and I haven’t confirmed it maps to the same three pilot cycles behind this case study’s other delivery numbers — treat it as a related, separately-observed signal, not a fifth data point on the same sample.

The Design Implementation Spec — same purpose, different form

Every handoff has always needed a spec. A document that says: here is what should be built, here is how it should behave, here are the edge cases. That need didn’t go away. What changed is who produces it, how it’s produced, and what it contains.

The old spec was authored manually — designers writing annotations, documenting component states, describing interactions in prose. It was thorough, but it was also static, human-interpreted, and structurally disconnected from the tools developers and AI agents were actually using to build.

The Design Implementation Spec is generated agentically. With both MCPs active and Harmony’s structured component context available, an AI agent can produce a spec that already speaks the production codebase’s language — referencing actual component names, real token values, documented behavior variants. The designer’s role shifts from authoring the spec to reviewing and validating it. Judgment stays with the designer. The translation work moves to the AI.

This is an evolution, not a replacement. The purpose of the spec hasn’t changed — transmit design intent clearly enough that something real can be built from it. What’s changed is that “clearly enough” now means something more precise: structured, machine-readable, built from the same vocabulary as the components that will implement it.

The architectural argument underneath it all

The principle underneath this model pushes toward an MVC separation — visual layer decoupled from model and content. UX owns the V. Dev owns the M and C. That’s not just a workflow change. It’s a structural argument for how product teams should be organized in an AI-assisted delivery environment.

Harmony makes this structural argument concrete. When the design system is also a production dependency — when it’s the shared vocabulary that UX, engineering, and AI agents all read from — the separation of concerns becomes architectural, not just procedural. UX isn’t translating intent into documentation and hoping it survives the handoff. UX is authoring the layer directly, in the language the codebase already speaks.

What’s still unresolved: the formal code review and merge process for HOCs. We have a path — reviewed like any other PR — but it’s not codified yet. The most meaningful outcome so far is that the question has changed. Tech leadership is no longer asking “should UX produce code at all.” They’re asking “what does the review process look like.” That’s a different, more tractable problem. The work to close it is ongoing.

The teams that will move fastest aren’t the ones with the most developers — they’re the ones where each role is doing the work that requires their specific expertise, and AI is handling the translation between them. Harmony moving to a second platform — React Native — is evidence that the model holds beyond its first context. The goal was never to make UX do development. The goal was to make the handoff disappear. That work is underway.