The Handoff Is the Bug

The desk check that couldn’t see the code

The desk check 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, and UX would watch it, trying to work out 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? Nobody could inspect that through a video. It showed the surface and nothing under it.

The developer hadn’t done anything wrong, and the spec wasn’t incomplete; it was thorough. But a comprehensive spec is still read differently by each person who reads it, and a video in a Slack thread gave UX no way to check intent against implementation.

As AI started entering the delivery pipeline, with developers feeding specs into models to speed up their builds, the translation problem didn’t go away. It just moved. Now a model was misreading the spec instead of a person. The ambiguity had been automated.

That reframed the question for me. Instead of asking how to write better specs, I started asking what would happen if AI got 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, and interaction states. Every judgment call is a chance to drift from intent.

At Arcos, that translation tax was paid twice: 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 take in design intent, then rounds of correction after it. The spec was comprehensive. It just wasn’t executable.

Moving the handoff into code

I started working toward a model where the UX team sent design intent in a form closer to code than documentation. Not as a replacement for engineering, but as a cleaner separation of concerns.

The principle pushed toward an MVC separation, with the visual layer decoupled from model and content. UX owned the V. Dev owned the M and C. If front-end visual builds could start inside the UX team, component-correct and already informed by the design system, development could focus on what it does best: backend architecture, data modeling, API integration. Nobody would burn cycles working out whether a button should have 8px or 12px of padding.

That opened something for Product as well. Simple experiences, the low-complexity UI updates that still needed full production cycles, could be built with UX oversight instead of waiting in a delivery queue.

Designers used the 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. Both roles worked from the same artifacts, without a translation step between them, and that is what made the handoff shorter.

Bringing three audiences along first

Changing where front-end code originates touches codebase ownership and delivery accountability, so this wasn’t a UX decision to make alone. 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 and managers: partial; pilot ran. Core concern: code quality and codebase ownership.

Individual developers were often the strongest early allies. They were tired of investigation overhead and wanted to be solving harder problems. 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 Higher Order Component. It was the AI-assisted prototyping work from early in the exploration, and separating the two took months.

Scope needed the same care upstream. Arcos used Shape Up, and getting Product to sharpen how Milestones were defined was its own change effort inside this one: unclear scope going in meant unclear code coming out.

Then the team. As the UX department’s AI Champion, a formal title in Arcos’s program to bring in a ChatGPT corporate account, 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. I led Harmony’s architecture and contributed hands-on at Arcos, including work with a senior designer on the token architecture. Other contributors owned or completed parts of the component and implementation work. That senior designer was Ales Karoza, who went deeper, refining the token sets with me in both Figma and JSON and establishing the external JSON file as the canonical source of truth for Harmony’s token layer. Steve Herring, a Slalom consultant, had helped structure the token library in Figma and defined the Base Theme tokens. The model would only hold if the team could run it without me. After those two weeks, they could.

Prototype tools versus the production codebase

The early exploration had blurred a distinction that mattered.

AI-assisted prototyping tools (Lovable, Bolt.new, Figma Make) were fast and generative, and good for getting abstract thinking onto a screen. They chose their own dependencies, with no relationship to the production codebase. Engineering was right to see that output as throwaway.

VS Code with AI agents and Harmony meant UX working against the actual front-end codebase, with the same tokens, components, and patterns engineering already owned. The output was Higher Order Components that engineers could review, trust, and merge. A HOC built against the actual front-end stack isn’t foreign code. It’s design intent in the team’s own vocabulary.

Harmony was intended to carry design intent to designers, engineers and AI coding agents. I re-architected it with engineering manager Zack Fantauzzi; that architecture has its own case study: Harmony: A Design System Built for Machines.

The spec, generated and then checked by a designer

Every handoff needs a spec: what should be built, how it should behave, what the edge cases are. That need didn’t go away. What changed was who produced it, how, and what it contained.

The old spec was authored by hand, with designers writing annotations, documenting component states, and describing interactions in prose. It was thorough, but static, interpreted by people, and disconnected from the tools developers and AI agents used to build.

The Design Implementation Spec generator was still in pilot when I left. 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.

Two MCPs, one context window

Knowing what a component should look like (Zeplin) and knowing how it actually behaves in production (Storybook) are different things. The old workflow asked developers to hold both in their heads and reconcile them by hand. The new one gave both to the AI agent at once, inside VS Code.

In the Storybook MCP pilot, with both MCPs active together, an agent 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, so it filled gaps from the production component library instead of guessing. That dual context made the output production-adjacent rather than prototype-shaped.

Storybook on Chromatic served both audiences. For designers, developers, and QA, it was a living reference for every component across states and variants. For agents, the Storybook MCP turned the same reference into structured context they could query from the coding environment. One artifact, two consumers, and no second source of truth.

Code Connect kept Zeplin components, Figma components, and the Harmony Storybook linked, and Zeplin annotations documented user type and behavior in detail, so an engineer could pull that context through the MCPs instead of waiting on a clarifying Slack thread. Engineers told me they felt more confident making small calls themselves, like copy voice and interaction behavior, because the documentation answered those questions. By my own read, front-end user stories that used to take 5–6 days came in at 2–3. That isn’t a pulled report, and I haven’t confirmed it maps to the same three pilot cycles as the other numbers, so it’s a related signal, not another data point on the same sample.

Agents that make the wrong path visible

Underneath the build sat an enforcement layer. When I left, a subset of agents was in pilot on two Arcos Control Tower web pods. They ran accessibility validation, reviewed code against the AI-generated design spec, and caught a developer reaching for raw MUI when a Harmony component existed. The system didn’t ask developers to follow it. It made the wrong path visible at the moment a developer took it.

People still reviewed the work. UX-authored HOCs had a path through code review, reviewed like any other pull request, but the formal process wasn’t codified yet when I left. The Desktop Panel was merged into the product, but integration with release code was unfinished; no UX-authored HOC reached a customer release.

A coded concept in 12 hours

I built the first Timecards prototype as a working React application using early Harmony components and Supabase test data, grounded in UX discovery and requirements, and linemen and foremen tested it at the Linemen’s Rodeo in the fall of 2025. Because it was coded rather than simulated, it surfaced interaction behaviors a Figma prototype would have hidden. Their feedback turned the design toward crew-based entry, and that revision, Mark 2.1, took me about 12 hours across three days. By my estimate, a wired Figma prototype covering the same scope would have taken roughly 40 hours. That alternative was never built, so the comparison is an estimate, not a measurement. No handoff required.

From there, my proof-of-concept work went to the senior designers for delivery refinement. Ales Karoza picked up my code as Mark 2.2, integrating and refining it within the larger coded application against a pre-release local Harmony repo with Storybook and Chromatic, months before the npm package. That work is part of Timecards Mark 2, the refined prototype in the Timecards case study, and later testing carried Pendo tags to track user task completion and flows.

What changed, and how far it reached

On Control Tower, kickoff and handoff went from a two-week investigation sprint to three days, and the see-build-review-change loops after it nearly disappeared. Time to market was about 30% faster, which is a separate measure from kickoff length. These numbers came from three delivery cycles on Control Tower, by my own observation and Product management’s reports to executives against roadmap releases: early signal from one platform, not a company-wide result. What really cut kickoff was three things together: structured attributes in Zeplin based on Harmony tokens, the Zeplin and Storybook MCPs, and the AI-generated design spec.

The artifacts arrived in this order. The Zeplin MCP was in active use by development from March 2026. I built the Harmony npm package and first pushed it to a private registry around April 2026, where it was installed in the Control Tower web pilot, and Storybook launched on Chromatic that same month. Then came the Zeplin and Storybook MCPs running together in VS Code, and the agent-generated Design Implementation Spec, reviewed and validated by the designer. The Storybook MCP and spec generator were still in pilot when I left. Zeplin’s routine use did not mean every automation element had rolled out. The Control Tower web theme was in test and integration with the production development flow, and Harmony’s React Native mobile theme was partly in use in Arcos Field, covering some components such as buttons and typography.

After I left Arcos, the remaining team reported moving from Figma and Zeplin to a Claude Code plus design-spec flow. Across two six-week iterations, they said kickoff took about Monday plus part of Tuesday. That is their report, not a measure I took.

What was still open

The formal code review and merge process for HOCs wasn’t settled. The more meaningful change by then was the question itself. Tech leadership was no longer asking “should UX produce code at all.” They were asking “what does the review process look like.” That is a more tractable problem, and the work to close it was still going when my time there ended.

Looking back, I’d show the output before pitching the model. I pitched the vision first, got partial buy-in, and then had to backtrack when the prototype stigma hardened. Leading with a HOC built against the production codebase would have started the conversation with Tech leadership in a different place.

The goal was never to make UX do development. It was to make the handoff disappear, with each role doing the work that needs its expertise and AI handling the translation between them.