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 was a Loom video in a Slack thread, UX had no way to verify intent against implementation.

As AI started entering the delivery pipeline, with 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 made 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 starting March 2026.
• Storybook on Chromatic: launched April 2026.
• Dual MCP agentic workflow: Zeplin and Storybook MCPs running 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 worked wasn’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 was active and expanding when I left. The Control Tower web theme was in test and integration with the production development flow. What started as a workflow experiment was becoming infrastructure.

These metrics came 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 transmitted design intention in a form that was 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, the low-complexity UI updates that required 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 used this model during the Shaping phase of a milestone, building coded concepts to test with users before a feature entered the delivery queue. Developers used it to extend design code that had already been handed off in the team’s own vocabulary. That dual-user pattern was what made 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 would only hold if the team could 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 ran. 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 owned. Higher Order Components that were 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 made this pipeline possible was Harmony, the Arcos design system, built so UX, engineering, and AI agents could 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 made 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 could reference the design spec and the live production component in the same context window. It saw what the designer intended and what the codebase already contained. That dual context was what made the output production-adjacent rather than prototype-shaped. The AI wasn’t filling gaps with guesses, it was filling gaps with the production component library itself.

Storybook on Chromatic served both audiences. For humans (designers, developers, QA), it was a living reference for what every component looked like, across states and variants, at a given point in time. For AI agents, the Storybook MCP turned that same reference into structured context that was queryable from within the coding environment. One artifact, two consumers. Neither maintained 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, things like copy voice and interaction behavior, because the documentation actually answered those questions by then. 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 was who produced it, how it was produced, and what it contained.

The old spec was authored manually, with designers writing annotations, documenting component states, and 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 was generated agentically. With both MCPs active and Harmony’s structured component context available, an AI agent could produce a spec that already spoke the production codebase’s language, referencing actual component names, real token values, and documented behavior variants. The designer’s role shifted from authoring the spec to reviewing and validating it. Judgment stayed with the designer. The translation work moved 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 changed was that “clearly enough” came to mean something more precise: structured, machine-readable, built from the same vocabulary as the components that would implement it.

The architectural argument underneath it all

The principle underneath this model pushed toward an MVC separation: visual layer decoupled from model and content. UX owned the V. Dev owned 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 made this structural argument concrete. When the design system was also a production dependency, when it was the shared vocabulary that UX, engineering, and AI agents all read from, the separation of concerns became architectural, not just procedural. UX wasn’t translating intent into documentation and hoping it survived the handoff. UX was authoring the layer directly, in the language the codebase already spoke.

What was still unresolved when I left: the formal code review and merge process for HOCs. We had a path, reviewed like any other PR, but it wasn’t codified yet. The most meaningful outcome by then was that the question had changed. Tech leadership was no longer asking “should UX produce code at all.” They were asking “what does the review process look like.” That was a different, more tractable problem. The work to close it was still ongoing when my time there ended.

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’s move to a second platform, React Native, was evidence that the model held beyond its first context. The goal was never to make UX do development. The goal was to make the handoff disappear. That work was underway when I left.