Old knowledge into new work, part 1: the loop watched the wrong thing
Dozens of components came out of Figma in June. The useful part was the loop around them, and a reader's comment showed that the loop was watching values while the bindings rotted.
Contents · 6 sections
Part 1 of two. In June an agent generated a design-system package from Figma through the MCP server, and a scheduled job kept watching the design for changes. A reader pointed out what that job could not see: the binding between a design node and its code component, which regeneration drops. This part covers the generation, the ten lessons, the sync loop, the comment, and the identity gates built after it.
In June an agent generated a design-system package from a set of Figma libraries: dozens of typed React components, a token pipeline, Storybook and docs, one commit per component. The component count made a good headline and was the least interesting thing about the work. Generation was only the first step. What lasts is whatever keeps the code and the design from drifting apart afterwards.
This series follows that idea from one project to the next. Part 1 is June: generating once, the loop built around it, and the gap a reader found in that loop. Part 2 is October: a loop that runs in both directions, where the Figma library is rendered from the code. The June work was first written up on LinkedIn; this post tells it again, with the part that came after.
The idea was a rule-driven design system anchored in design rather than in development: bring design and development closer, and let updates flow without someone carrying them by hand.
Generate once
On paper the pipeline had five steps. Read the design through the Figma MCP server (get_metadata, then get_design_context, get_variable_defs, get_screenshot). Turn the variables into W3C tokens, then into CSS custom properties and a Tailwind @theme. Generate typed React: forwardRef, a displayName, twMerge, shared style props. Verify with tsc, ESLint and a Storybook visual harness. Document each component and keep a changelog.
In practice the agent was very good at volume and weak wherever it could not see its own output. The first Button it wrote had plausible Tailwind, px-4 py-2. The actual component used different padding, typography and letter spacing. Storybook showed unstyled HTML for most of the build, because nothing ever compiled Tailwind, while the code looked finished. Every fix that worked closed a feedback loop: render the thing, read the design node by node, line the code up with the system that already existed.
The ten lessons from the article, in one line each:
- “Looks done” is a trap: make the agent read the design node by node.
- Check what renders, not the code. Wire the visual surface first.
- The source of truth may already be in the codebase: the theme package had the values, under the names of the Figma layers.
- Respect units: hard-coded pixel values were converted to rem throughout the package.
- Git history should tell the truth: one commit per component, fixups squashed in.
- Generating is easy. What lasts is the loop.
- Decide where the loop keeps its memory.
- Give every snapshot its provenance.
- Be safe by default: a dry run needs no secrets.
- Write the decision down: an ADR, and the extraction steps as a reusable skill.
Lessons 6 to 9 are about the loop.
The loop that watched values
The sync loop is a scheduled job. Every weekday morning it pulls the variables and published components from the tracked Figma files, compares them with the last baseline, and opens an issue that names exactly what changed: which token or component, whether it was added, updated or removed, and a deep link to it. Then it saves the new baseline. A ticket in the issue tracker follows as a best-effort stub, so an outage there cannot swallow a detected change. It never opens a pull request. It detects and it describes; a person applies the change and checks it.
- tracked files variables, components
- restore baseline from the CI cache
- normalise + diff exit 0 / 1 / 2
- issue for a person what changed, deep link
- tracked files variables, components leads to restore baseline from the CI cache: fetch, retry on 429
- normalise + diff exit 0 / 1 / 2 leads to issue for a person what changed, deep link: exit 2: change
- normalise + diff exit 0 / 1 / 2 leads to restore baseline from the CI cache: save the baseline for the next weekday (the baseline the next run compares against)
- restore baseline from the CI cache leads to normalise + diff exit 0 / 1 / 2
- Figma
- tracked files variables, components
- Weekday job
- restore baseline from the CI cache
- normalise + diff exit 0 / 1 / 2
- Tracked work
- issue for a person what changed, deep link
Most of the engineering went into not raising false alarms. Token values are normalised before the diff, so an alias points at a name and floats are rounded, and a designer re-saving a file is not a change. If a fetch fails, the last good section is carried forward, so an API blip never reads as “everything was removed”. When the snapshot format itself changes, the job reseeds instead of diffing old against new:
if _snapshot_schema(old_state) != SCHEMA_VERSION:
if _has_fetch_errors(new_state):
print("reseed deferred — a fetch errored this run; keeping old baseline.")
sys.exit(0)
print("reseeding baseline (no diff).")
if update_snapshot and not dry_run:
write_snapshot(merge_for_snapshot({}, new_state))
sys.exit(0)
The baseline moved out of the repo into the CI cache, and every snapshot carries a _meta block: schema version, timestamp, the files it read. The diff is written so that it never looks at that block. The snapshot describes where it came from, and the comparison is built to look past that description to the design. Lesson 8, in six lines.
That is the loop the phase-one work summary records: automated tests, provenance, dry-run safety, tickets instead of auto-PRs.
What a reader saw
Under the article, a reader asked the question I had walked past. Paraphrased: generating answers “what could this look like?”, not “is this what my code is, and will it stay that way?” And on lesson 6, what does the loop actually preserve? A snapshot diff notices that a token’s value moved. What rots, though, is the binding between a design node and the code component that implements it, and a value diff cannot see that. Lesson 3 had come close: lining names up with layers is the binding, and bindings are exactly what regeneration drops. The reader’s last point: a person at every check is right, and it does not scale. Can the check be a deterministic gate, so that the loop closes both ways and identity survives a round trip instead of being guessed again?
My answer at the time was that the loop tracked components by identity, so it caught value drift and a broken name-to-node link, but not the binding from code back to design. In the code that binding was metadata sitting next to the component, enforced by nothing. Regeneration dropped it, because identity lived outside the generated files and was never an input to generating them.
- node 1234:5678 Button
- Button.tsx same values, new file
- story lost its node id CI fails H2 DESIGN_LINK
- token values unchanged no issue
- node 1234:5678 Button leads to Button.tsx same values, new file: agent regenerates
- Button.tsx same values, new file leads to story lost its node id CI fails H2 DESIGN_LINK: the binding check reads the story
- Button.tsx same values, new file leads to token values unchanged no issue (what a value diff reports: nothing)
- Design
- node 1234:5678 Button
- Regeneration
- Button.tsx same values, new file
- Binding check
- story lost its node id CI fails H2 DESIGN_LINK
- Value diff
- token values unchanged no issue
The figure is the whole gap. Consider a hypothetical regeneration that drops the story’s design link. Button comes back from its node with identical values, and the value diff reports nothing, correctly. But the story no longer carries the node id, and nothing ties the component to its node any more. Nothing in the loop was looking at that.
The handover calls this work “loop-tightening”, and the binding-contract script describes the gap in the reader’s words.
Identity, as gates
What came next added a second layer to the loop: identity, checked by code. Each piece is a small stdlib script with tests, and most need no token, so they run on every pull request.
A binding contract. Five hard gates, each one a CI failure:
H1 COVERAGE every component directory has a *.stories.tsx
H2 DESIGN_LINK every story declares a Figma design URL with a node-id
H3 WELL_FORMED every design URL yields a (fileKey, nodeId)
H4 KNOWN_FILE every fileKey is one of the tracked design files
H5 NO_COLLISION no Figma node-id is claimed by more than one component
Two soft signals sit beside them: how many story nodes appear in the latest snapshot, and whether node comments in the code agree with the story. The script calls them a gap still being closed.
A binding manifest. The repo derives one record per component (file key, node id, component name, code file, story file, Code Connect id) and compares the result with a committed binding-manifest.json. Any drift fails CI. Identity stopped being metadata next to the code and became a file that a test reads.
A live node check. It asks Figma whether each bound node still exists and still hosts the same component. A node deleted and recreated gets a new id and fails, and a migration record lets an intended rename through.
Code Connect, in two tiers. A policy lists the components that are required to have a mapping and those that are verified, meaning their property names were checked against the live file. Every pull request parses the mappings. Only main, only with the secret, and only the verified list publishes:
{ "required": ["Accordion", "Button", "Tabs"],
"verified": [],
"requireAll": false, "exempt": {} }
The verified list was empty, so publishing did nothing. A half-finished mapping could ship without telling a designer something false.
A regen guard. This one is for the agent, not CI: may it regenerate a component from node X?
for name, b in bindings.items():
if b.get("figmaNodeId") == target:
if b.get("codeConnectId"):
return True, f"ALLOW: node {target} is bound to '{name}' via Code Connect."
return False, (f"BLOCK: node {target} maps to '{name}' but has NO Code "
f"Connect file. Add {name}.figma.tsx before regenerating.")
A node outside the manifest is refused too, unless the agent explicitly says it is creating a new component. The guard could refuse regeneration when invoked, but it was not yet wired into the agent at handover.
A token round trip. The committed DTCG tokens.json is the source of truth. The script flattens it and a Figma export side by side and reports what is missing, extra or changed. It detects and does not fix; the direction is written down as “code wins”, and only metadata (mappings, descriptions, tokens, links) was meant to flow back into Figma. Code Connect proves identity, not that the pixels match.
binding-contractEvery component has a story with a Figma node id, in a tracked file, claimed by one component only.
binding-manifest --checkOne identity record per component, compared with the committed manifest. Any drift fails CI.
node-validationFigma confirms each node still exists and hosts the same component; a migration record allows a rename.
code-connect-coverageRequired components have a mapping on the right node. Only verified ones publish.
regen-guard <node>When invoked, it refuses regeneration over a node not bound through Code Connect. Not yet wired into the agent at handover.
token-roundtripCode tokens against a Figma export: missing, extra, changed. Code wins; it reports, never fixes.
The check that checked the agent
The first run of the live verification, through the MCP server, found the agent’s own mappings wrong. It had inferred property names without checking them against the live design, and neither those names nor the binding targets matched the design. The mappings needed checking before publication. This was lesson 1 again, one level up. The agent wrote mappings that looked done, and only a check that read the real design could tell. That is why the verified tier exists.
At handover the second layer was staged changes with automated tests, and a short list of open items: the real property names, a CI secret, visual baselines, a decision on which node a binding should point at, and wiring the regen guard into the agent.
I ran the loop a few times before I left, and it held. What happened to it after the handover, I don’t know.
Where this sits on the thread
On the graph this post hangs on two ideas. Guardrails, because the reader’s question (“can verification be a gate?”) has a plain answer here: yes, for identity, as five lines of rules and a manifest that a test reads. Information engineering, because what the loop has to keep is not the values, which Figma already holds, but the links between things. A binding that lives outside every input is information nobody owns.
The June loop still ran one way, design to code, and still asked a person at the end. Part 2 is the autumn: a project where the code draws the Figma library, designers change it there, and the same three concerns come up again.
Follows the thread to
- How Claude, Codex, Copilot and Gemini talk to each other
- How this site works, part 3: deploy and guards
- How this site works, part 2: islands and the Ask Worker
- How this site works, part 1: from constants to pages
- Old knowledge into new work, part 2: the library draws itself
- review-loop: a second model family reviews every ticket, and code decides what blocks
- security-floor: the server-side check that --no-verify can't skip
- How Autograph turns your work into a vault
- My Claude Code setup: guardrails, a plan gate, shared memory and a wiki that dreams
- Autograph
- Throw away your IDE?