Code First

OVERVIEW

Project Overview

I opened the Figma file and the code side by side. The button in Figma said 'Primary, Large.' The button in Storybook said 'variant: action, size: lg.' Same component. Different names. Different assumptions. And this was one of the simpler ones. Somewhere in the gap between those two descriptions, a year of quiet drift had accumulated — and nobody had noticed because the system still looked right, even though it no longer said the same thing in both places.

This was Brad Frost's design system. The person who wrote Atomic Design. If alignment could drift here, in a system built on first principles by someone who literally invented the vocabulary — it could drift anywhere. That realisation reframed the entire project for me.

Working as part of the Maker Program, the challenge wasn't to design a system and hand it off. It was to understand an existing, principled system deeply enough to contribute at the component and token level — to close the gap between Figma and code, and to explore whether AI tooling could make that kind of structural investigation fundamentally faster.

CONTEXT

Starting From Code

Brad Frost's approach to design systems is rooted in Atomic Design — the idea that UIs are built from atoms to molecules to organisms, and that the smallest decisions compound upward. Working with his system meant operating in an environment where those principles were already embedded in the codebase, not aspirational documentation.

The Maker Program is structured around real contribution: participants don't observe, they build. The expectation from day one was to read the existing codebase, understand how components were structured, identify gaps between design and implementation, and then close them — through Figma work, documentation, and direct collaboration with Brad and other contributors.

This was a fundamentally different experience from owning a design system from scratch. Every decision had to be justified against an existing, principled structure rather than invented from first principles. That constraint turned out to be enormously useful.

MY ROLE

Collaboration and Contribution

My work spanned three areas. The first was component archaeology: reading Storybook stories, tracing prop structures, and mapping how existing components composed. This wasn't glamorous work, but it was the prerequisite for everything else — you can't contribute to a design system you don't understand.

The second was Figma alignment: rebuilding or updating Figma components to accurately reflect their code counterparts. This meant matching variant names to prop names, ensuring token usage was consistent, and eliminating the silent drift that accumulates when design and code evolve independently.

The third was tooling: using Claude via MCP to interrogate system structure, surface token relationships, and accelerate the investigation work that would otherwise require extensive manual tracing. This was the most experimental part of the project and the one I learned the most from.

TECHNICAL WORK

Token Alignment and Component Architecture

Token alignment was the most technically demanding part of the work. The system used a layered token structure — primitive values feeding into semantic aliases, which fed into component-level decisions. Understanding where a visual change should be made required tracing the full chain before touching anything.

Several components had diverged between Figma and Storybook over time. Some were structural: variant names in Figma didn't match prop names in code, which made handoff ambiguous. Others were visual: spacing or color values had been updated in one place but not the other. The process of aligning these wasn't just cosmetic — it required understanding the intent behind each decision well enough to make the right reconciliation.

Component architecture decisions in the codebase reflected years of atomic thinking. Certain patterns that I might have approached differently as a solo designer — like deeply nested composition patterns or explicit default prop handling — made more sense in context. That was a useful recalibration: understanding why a system is structured the way it is before proposing changes to it.

AI TOOLING

Using Claude MCP for System Investigation

The most novel part of the project was using Claude's Model Context Protocol to assist with system investigation. MCP allows Claude to interact directly with local files and project structure, which made it possible to ask structural questions about the codebase — "what components use this token?", "where is this variant defined?" — and get answers grounded in the actual code rather than hallucinated from training data.

This changed the pace of investigation work significantly. Manual token tracing across a large component library can take hours. Using MCP to surface relationships and then verify them manually reduced that to minutes for most queries. The workflow settled into a pattern: use Claude to generate a structural hypothesis, verify it against the source, then act on it.

The limits were also instructive. MCP is powerful for surfacing structure, but it doesn't replace understanding. Queries that required design judgement — "is this the right token for this context?" — still needed a human answer. The tooling accelerated investigation; it didn't replace thinking.

KEY LEARNINGS

Key Learnings

Code-first is a design skill. Reading a codebase to understand design intent requires the same analytical rigour as reading a user research report. The information is just encoded differently.

Token discipline is a long-term investment. Systems that maintain strict token layering are significantly easier to update consistently. The upfront cost of doing this well pays back compoundingly as the system scales.

Figma–Storybook alignment requires active maintenance. Drift is the default state; alignment requires deliberate process. The question isn't whether it will drift — it's whether you've built the habit of closing the gap.

AI tooling changes what's feasible in investigation. MCP-assisted system investigation made structural questions answerable in minutes that would previously have taken hours. That changes what you can reasonably attempt in a bounded project.

REFLECTION

Reflection

This project shifted my intuition about where design system work actually happens. The highest-value work isn't in the Figma file — it's in the alignment between design intent and implementation reality. That alignment requires a designer who can read code, trace decisions, and understand a system on its own terms before proposing changes to it.

Working with Brad's system was the most rigorous design system experience I've had precisely because there was no greenfield freedom. Every decision was in conversation with something that already existed and had been thought through. That constraint is, I think, the most realistic version of design system work at scale — and the one worth getting good at.