Design Tokens That Survive the Handoff to Code
The gap between design and code is not a rendering problem.
It is a naming problem, and it is solved by carrying names across the boundary instead of colours.
Short answer
They survive when the design variables ARE the tokens, with no export step in between to drift. Define them per mode, then match them at handoff against the tokens already in the project, so an agent writes your token name instead of a hex value that breaks the next time somebody changes the theme.
What this covers
- Variables are named values in collections and groups, defined per mode, where light and dark are the obvious pair and brand, density or platform are the ones that make the feature earn its keep.
- At handoff those variables are matched against the tokens that already exist in your project, so an agent writes your token name rather than a hex value that breaks the next time somebody changes the theme.
- Component bindings carry the source path in your codebase and a confidence, so an agent that knows a button is a specific file writes an instance instead of a new component.
- Components that did not match are reported rather than dropped: they are the work list of what the screen needs and the project does not have yet, which turns a handoff into a plan instead of an argument about fidelity.
- Design node ids are carried into the code, making a later fidelity comparison exact and an automated tap in a UI test unambiguous.
Comparison
| What crosses the boundary | A screenshot handoff | A structured handoff |
|---|---|---|
| Colour | #16191E | Your token name, matched to the project |
| A button | A picture of a button | The source path of the component you already have |
| Layout | Inferred from pixels | The screen's own semantics |
| Motion | A note saying fades in | The compiled keyframes |
| What is missing | Discovered in review | Reported as a work list |
The handoff problem is a naming problem
Design and code disagree less about what things look like than about what things are called. The screenshot says a surface is a particular shade of near-black. The codebase says that surface is a token with a name, used in forty places, and that adjusting it is a one-line change.
Hand an agent the shade and it writes the shade. The screen looks right today and is wrong the moment anybody touches the theme, and nobody notices until a dark mode ships with one panel that did not move.
The variables are the tokens
In Pathrule's Design surface, variables are named values organised into collections and groups, and defined per mode. Light and dark are the obvious pair; brand, density and platform are the ones that make the feature worth having.
There is no separate token export. The variables are the tokens, which removes the step where two representations of the same value drift apart. The editor is a tree of collections on one side and a name plus a per-mode table on the other, so changing a value in every mode is one row rather than a hunt.
What the agent actually receives
The handoff carries the screen's semantics rather than scraped markup: what each element is, how it is laid out, and how it responds, taken from the design's own representation.
It carries the tokens, matched against the ones that already exist in your project, so the agent writes your name for the value. It carries component bindings with the source path in your codebase and a confidence, so an agent that knows the button on this screen lives at a specific file writes an instance rather than a new button. It carries the compiled motion, and the assets the screen uses.
And it carries the design node ids into the code, which is a small thing that pays twice: it makes a later fidelity comparison exact, and it makes an automated tap in a generated UI test unambiguous.
The unmatched components are the useful part
A binding that matched is a fact. A binding that did not is also information, and it is reported rather than quietly dropped: these are the components this screen needs and your project does not have yet.
That single reporting choice changes what a handoff is. Instead of a picture and an argument about whether the implementation is faithful, you get a work list: build these three, reuse these nine.
The same project map works in the other direction too, which is what lets a design be authored against the components that really exist rather than against ones somebody hopes exist.