Harmony: A Design System Built for Machines

Where the first two systems stopped

Harmony is my third design system. 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. BetterCloud Fulcrum became the best prototyping library its designers had ever had and never crossed into engineering, and TVH Uplift crossed into engineering but drifted, trusted in some teams and built around in others, until its engineers moved under UX with protected capacity.

At Arcos I treated both lessons as solved premises: a system has to live in engineering, and it needs an owner who can protect it. The third problem was new. Once AI entered the delivery pipeline, the gap between what a person could read in a design system and what a machine could act on stopped being theoretical. Harmony was intended to carry design intent to designers, engineers and AI coding agents.

How did building Fulcrum and Uplift shape what Harmony needed to be?

What a name can’t carry

AI is very good at moving fast and very bad at knowing what it doesn’t know. Feed a model a Figma spec and it will produce code, confidently, making the same small judgment calls a developer would make. A developer can ask a question. A model just picks.

Agentic coding tools are only as good as the context they can reach, and most design systems were written for a human reader who could infer and ask. A token named color-feedback-warning tells a developer something. It tells a model a label. A component documented with props and variants tells an engineer how to use it and tells an agent the syntax. Neither carries what decides whether the output is right: why this token and not the similar one two rows up, why this component and not the raw library element underneath it.

Two product requirements made that gap concrete. Arcos Control Tower shipped in both dark and light, and a warning surface was not a hex value. It was a role that resolved to different values in each theme. A model that picks by the closest name, or worse by the value it saw last, produces something that reads correctly in one theme and fails contrast in the other, and nobody catches it until a user in the wrong theme reports it.

The second requirement was language. Customers kept asking for Spanish across the storm-response tools, and a component whose padding, line count, or truncation quietly assumes English string length breaks the moment the copy grows by a third. Neither constraint shows up in a token name or a prop table.

So intent had to be legible at every layer: in the token descriptions, in component documentation grounded in user need, in feature-level intent from the design spec, and in agents that enforce the system rather than only assist with it.

What does 'machine-readable design intent' actually mean in practice?

Building the chain

Dark and light were both core from the start of the token work, not a later theme variant, and dark got the design attention first. Command center and dispatch users sat in Control Tower for hours at a stretch, command center operators alongside seven other applications across four monitors, and during a storm event that stretch became a shift and then another one. A majority of them asked for dark, so dark was where contrast, elevation, and status color were validated first, and light was then held to the same bar. Localization arrived implied rather than stated, so the layer had to let a locale drop in without a redesign: no copy baked into components, spacing and line handling that tolerated longer strings, and formatting that resolved from locale rather than from a hardcoded pattern.

The chain started with the tokens. Harmony used the DTCG format because the standard was open, the tooling was mature, and the description field was structured. Harmony’s token descriptions, where authored, explain a token’s intended use. The descriptions went into the DTCG file after the first extraction from Figma, when the JSON file in the repo became the source of truth. The names stayed semantic for people, and the descriptions carried the layer of meaning a name couldn’t: the layer that decides whether a model picks the right token for the right reason or just the closest syntactic match. 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 helped establish the external JSON file as the canonical source of truth for the token layer. Steve Herring, a Slalom consultant, helped structure the token library in Figma and defined the Base Theme tokens.

From the tokens, the system built upward. I built the Harmony npm package and pushed it to private AWS CodeArtifact, where the Control Tower web pilot installed it as a versioned dependency. Figma Code Connect, which I built, mapped the atomic components and three desktop patterns to their TypeScript implementations, so the source of truth and the code couldn’t drift apart silently. Storybook ran against the published package and documented what each component was for, grounded in user need. Harmony’s chip guidance maps color to semantic intent; warning means pending or review required. The Harmony Chip Intent example shows the same work-order statuses in light and dark themes.

The architecture I left behind wasn’t the one I first drafted. My first approach consumed MUI components, overrode each one with a theme provider, and exported the result, so engineering would import Button from Harmony instead of from MUI and UX would own the whole visual layer. The case against it showed up as soon as I worked through the implications: owning components meant owning MUI version updates, bug fixes that started in MUI, and every regression from a breaking change. UX had no dedicated React developers, the way the design system org at TVH did, to carry that.

Engineering manager Zack Fantauzzi came in once my first code theme was ready for review, and together we re-architected it. Harmony provided themes instead: token sets and implementations delivered through MUI’s ThemeProvider, layered on unmodified MUI components. UX controlled the visual layer and MUI handled the component layer. The system gained a safety property the first draft lacked: if Harmony failed to load, MUI fell back to its defaults and the software still worked. That separation made the system safe to ship in pilot, because UX wasn’t claiming anything it couldn’t sustain. It also settled theming. I wrote the web theme myself, because development didn’t have the people for it. A mode was a token set, so dark and light stayed a configuration of the layer UX owned instead of a fork of the layer engineering owned. A pivot made for capacity turned out to be why the theme layer could carry two modes at all.

The agent layer closed the chain, with two MCP servers scoped to two consumers. Designers worked in Figma MCP at full source fidelity, for authoring, governance, and system updates. Developers worked only in Zeplin MCP, which delivered feature-scoped design context and user intent annotations into the build environment. Storybook was MCP-enabled in pilot, so component purpose flowed into the agent’s context alongside the feature spec. A kickoff skill Ales Karoza created pulled the JIRA ticket that defined a feature, paired it with the Zeplin context, and generated a build plan before anyone opened VS Code.

Underneath ran agents that enforced rather than assisted. I built them, with process input from a few senior and lead developers. UX used governance agents for design system updates. Two development pods piloted enforcement agents that ran accessibility validation, reviewed code against the pilot-generated design spec, and caught developers reaching for raw MUI components when a Harmony equivalent existed. The system didn’t ask developers to follow it. It made the wrong path visible at the moment they took it.

Earning engineering’s trust

The argument had to be heard before anything got built. Individual developers came on board first; they paid the highest cost of the old handoff and saw the relief most clearly. Product leadership followed. Tech leadership was the harder room, and that conversation was still open when I left. Their questions about codebase ownership and what UX-generated code meant inside an engineering org were legitimate, and they deserved careful answers rather than workarounds.

The pilot couldn’t run on my work alone. Three senior designers went through two weeks of training and environment setup to work in VS Code with Claude Code CLI. That is a real ask for experienced designers who had never opened a terminal, and they showed up for it. The model held because the team could run it without me.

Engineering credibility came from work engineers could judge on their own terms. When the first higher order component (HOC) from UX, the Desktop Panel, went to the Control Tower codebase, the question wasn’t whether it looked right. It was whether engineers who hadn’t built it could review, trust, and merge it. They could, and it was merged into the product. It lived in the same repository as the production code and arrived through the same dependency channels as any other internal package. Integration with release code was still unfinished when I left, so no UX-authored HOC reached a customer release.

The sharpest proof came from somewhere I hadn’t planned. The mobile pod, never part of the original rollout, with no training and no onboarding, connected the Zeplin MCP into its own Claude Code workflow during a planning session, using it to visualize shaping outcomes mid-discussion. The pod also built a UX Designer agent trained on the UX team’s documented ways of working. Nobody onboarded them. They read the same architecture the pilot pods used and extended it themselves.

View larger (opens the full image)

Where it stood when I left

The pieces went in a deliberate order: foundation, then chain, then enforcement. Code Connect couldn’t ship until the package existed. The Storybook MCP couldn’t pilot until Storybook ran against the package. Chromatic only meant something once Storybook imported the real dependency.

In production, as of when I left. The Zeplin MCP was active across planning and initial build, and Ales Karoza’s kickoff skill generated build plans against JIRA tickets. Storybook had been live on Chromatic since April 2026 with tokens and core components. UX ran my governance agents as normal practice.

Launched and instrumenting. I first pushed the Harmony npm package to private AWS CodeArtifact around April 2026. It was installed only in the Arcos Control Tower web pilot, where existing production code was being refactored against the token and theme layer, not in released product code. I had just finished Figma Code Connect, built with Figma MCP and Claude Code CLI, mapping the atomic components and three desktop patterns (Panel, MainNav, WebAppBar) to their TypeScript implementations.

In pilot or under evaluation. The Storybook MCP was in pilot with two Control Tower web pods, who were assessing its accuracy against their own feature work. The enforcement agents ran in those same two pods, and the Design Implementation Spec generator I built was still in pilot. Across three piloted Control Tower cycles, structured Zeplin attributes based on Harmony tokens, both MCPs, and the AI-generated design spec worked together to cut kickoff from two weeks to three days. Routine Zeplin and governance use did not mean every automation element had rolled out. QA was evaluating Chromatic visual regression.

Localization was the honest item on the list. The layer was built so a Spanish locale could drop in, but no Spanish build had shipped in an Arcos product when I left. Structural readiness is not a shipped locale.

The delivery numbers this pilot produced are told in The Handoff Is the Bug: kickoff went from a two-week investigation sprint to three days, time to market ran about 30% faster across piloted delivery cycles, and I built a testable coded concept, Timecards Mark 2.1, in about 12 hours over 3 days, which Ales Karoza then integrated and refined, against my estimate of roughly 40 hours for a wired Figma prototype covering the same scope. What was in pilot was in pilot because that’s where the work stood when my time there ended, not because it stalled.