We've done twelve design-system handoffs in the last eighteen months. Half of them broke within three months. The half that didn't break had three things in common.
Property 1 — They were typed
Not "documented." Typed. The token names existed as a TypeScript enum or a JSON schema, and the build system refused to compile if a className referenced a token that didn't exist.
Documentation rots. Types fail loudly.
Property 2 — They were flat
One layer between raw value and use. `color-bg-page: #0a0e1a`, used directly as `bg-bg-page`. No semantic layer in the middle pretending to abstract intent.
Semantic layers are a noble idea that, in practice, get used by exactly one designer and ignored by the rest of the team.
Flat tokens are uglier in Figma. They survive longer in code. Pick the one you're optimizing for.
Property 3 — They included the "why"
Each token's definition file had a one-line comment explaining what it was for. Not a description of the color — a description of the design decision.
- --surface-raised — cards, modals, anything visually elevated above the page
- --bg-page — the default background, should be the most-used color
- --accent-bright — single brand accent, used sparingly for emphasis
When someone adds a fourth surface color six months later, the comment is what stops them.
The handoff itself
The actual handoff document is two files: a typed tokens file and a single Markdown sheet with the why for each. No Figma library, no Storybook, no decked-out style guide. Just the two files, checked into the repo, opened at every code review.
Owns the front door. Scopes audits, runs discovery calls, writes proposals that read like plans.