Genie Design System

The drift is not caused by carelessness, which is why exhortation never fixes it. It is caused by the three artifacts having different edit costs. Changing padding in Figma takes a second and leaves no trace. Changing it in code requires a review. Changing it in the docs requires remembering the docs exist. Any system whose consistency depends on the most expensive of those happening every time will decay at exactly the rate the cheapest one gets used.

So the question is not how to keep three things in sync. It is which of them is allowed to be the source, and what mechanism makes the others derive from it rather than agree with it by convention.

Code Connect is the first half of the answer. A Figma component gets bound to the real implementation, so Dev Mode stops handing over a picture and starts handing over the import and the props. The Figma MCP server then exposes that same binding to a coding agent: it reads the selected frame and gets a component name, its variants and its props, instead of inferring a likely-looking div from a screenshot.

What this removes is the translation step — the moment where a person looks at a design and decides which component it probably is. That decision was always the leak. Nearly every accidental re-implementation of an existing component begins with somebody answering it wrong, in good faith, because the design looked slightly different from the one in the library.

It is also a deliberately brittle binding, and that is the feature. Renaming a variant in Figma breaks the connection loudly instead of letting the two drift quietly apart. A silent inconsistency is a design-system bug that surfaces months later as a slightly wrong button; a broken build surfaces today.

Bindings are also the clearest place to see that Figma variant names are load-bearing. Once "Primary" in the variant panel maps to variant="primary" in the props, the naming in the design file has stopped being a label for designers and become an interface. That reframing did more for naming discipline in Figma than any amount of asking.

What a binding cannot do is carry meaning. It says which component to use. It says nothing about when you should not use it, which variant belongs to a destructive action, or why there is no error state. That knowledge has always lived in prose, in people’s heads, and in review comments — which is exactly where the second reader runs aground.

A designer reading a thin component doc fills the gaps without noticing: from the other screens, from what the team did last quarter, from a message to whoever built it. Ambiguity gets absorbed by the reader, so it never shows up as a defect. It shows up eighteen months later as four subtly different buttons and nobody able to say which one is right.

An agent absorbs nothing. It has no institutional memory, it will not ask a colleague, and it does not know which conventions are load-bearing and which are accidents. Hand it an ambiguous doc and it produces something confidently wrong — immediately, and in the diff, where you can see it.

That is a feedback loop a design system has never had. Every gap that used to be quietly filled in by a human now fails visibly and on the same day. Writing docs for a machine is, in practice, the first honest audit of the docs.

The sections an agent needs turn out to be the sections human documentation habitually omits. When not to use this component, and what to reach for instead. What each variant means rather than what it looks like — that "destructive" is a claim about reversibility, not a colour. Which states exist, and which deliberately do not, because a documented absence stops the same question being re-answered differently every time. And the accessibility contract in words: focus-visible only, aria-label required on icon-only buttons, never swap a label for a spinner because it destroys the accessible name mid-action.

Every one of those is a rule I would have given a new designer verbally in their first month. None of them was written down anywhere, because verbal transmission worked well enough that the absence was invisible.

A per-component markdown file beside the component, plus a design.md that carries the decisions spanning all of them, is a boring format on purpose. Markdown is what an agent reads well and what a person will actually edit in the same pull request as the code — which makes it the only documentation with a chance of staying true.

Storybook holds the layer neither the binding nor the prose can: every variant and every state rendered and executable, with accessibility checks running on each. Prose can claim a focus ring exists. A story proves it, for a human reviewing and for a snapshot diff alike.

The conclusion I did not expect is that none of this is really about agents. Nothing I wrote for a machine was a compromise for a machine. "When not to use this", "what this variant means", "which states deliberately do not exist" — that is just a better component doc, and it always was. The agent did not create a new requirement; it removed the slack that had been hiding the old one going unmet.

Which gives a test I now apply generally. If a design system’s documentation would produce wrong code in the hands of a competent reader with no context, it was never really documentation — it was a set of reminders for people who already knew the answer.