Starting from an Incomplete Figma File
2026-05-19
Why does the gap between design and implementation keep appearing?
What makes this Figma file incomplete?
When we outsourced design work, the designer didn't provide Figma dev mode access. From a frontend engineer's perspective, that's unusual — but I wasn't involved in the initial contract negotiations, and with my hands full on development, I didn't want to interfere with an arrangement someone else had already agreed to.
When I finally got access to the full Figma file at project close, I found the gaps. In practice, I bridged them mentally as I built — but the moment anyone tries to automate anything (design tokens, AI generation, cross-platform export), this design file falls apart immediately. That's why I wanted to use the remaining month and a half of handover time to work through this properly.
What this Figma looks like to a frontend engineer
From the perspective of a human doing frontend implementation, the file isn't actually that bad:
| Problems | Workable (if you're willing to guess) |
|---|---|
| Inconsistent naming | Visually judge whether two buttons are the same component |
| No auto layout | Eyeball whether that gap is 16px or 24px |
| Designer unreachable post-project | The visual design itself is mostly fine |
The visual output is fine, but AI can't read design intent. The moment you replace "human" with "machine," every one of those workarounds breaks:
- Inconsistent naming → token extraction can't produce a stable namespace
- No auto layout → spacing intent is invisible; all you see is hardcoded x/y values
- Same color written as different hex values in different places → which one does the AI pick when generating UI?
But the biggest problem is that the designer is unreachable — and there's no guarantee whoever takes over will have enough design sense to fill the gap.
Why this series exists
I'm about to leave the company. Before I do, I want to accomplish two things:
- Process notes, built in public — walk the full pipeline from Figma → design token → AI agent generating UI from text descriptions, and honestly document every dead end and detour
- A handover assistant, not a handover document — using tokens + an agent, future engineers can generate design-system-compliant UI and code through conversation
The second goal is the real point of this series. I don't want to leave behind a 200-page wiki that goes stale in six months and that nobody opens. I want to leave something you can talk to.
One early decision: don't start by cleaning up the Figma
The intuitive move is to tidy the Figma first, then extract tokens. That's not how I approached it:
- With less than a month left, Figma cleanup would consume all the time
- Figma shouldn't be the source of truth for a design system — code should be
- Even if I cleaned it up, whoever takes over without the same discipline would mess it up again in three months — so a "clean Figma" has a half-life of about three months
The right direction is the reverse:
tokens.jsonas the source of truth- Treat the messy Figma as archaeological material — extract the raw primitives
- Use an agent to generate a Vue-based component library from the tokens
What's next in this series
Starting from Part 2: turning this mess into data — why Figma MCP failed, how I ended up using the REST API instead, and what the raw data actually looked like on the first successful pull.