Design tokens in a design tool vs a sheet your agent reads

Many design teams already keep their tokens in a design tool: colours, type styles, radii and spacing defined as variables or styles in the design file. It's the right home for them while people are designing. The problem appears when an AI coding agent writes the UI, because the agent builds from code and can't see the design file unless someone carries the values across.

This page compares two approaches: keeping tokens only in a design tool, and giving the agent a design sheet it reads over MCP. It compares approaches rather than particular tools, and it says where the design tool is the better place for the work.

What each one is#

Tokens in a design tool are named values (a background colour, a heading style, a corner radius) that designers apply across components and screens in the design file. Change a variable and every frame that uses it updates. Getting them into code takes an extra step: a plugin, a token pipeline, the tool's developer features or someone copying values by hand.

A design sheet is a design system written for the agent. It holds foundations (colour, type, radius, spacing, shadows and a motion spring), slots with one chosen component each, and short rules. The agent calls get_sheet or get_tokens to read it, and get_slot to fetch a component with the values filled in.

The short version#

Where tokens in a design tool shine#

• Designing, not just building. Whole screens, flows, prototypes and edge cases are worked out in the design file. A sheet doesn't replace any of that.
• Collaboration. Designers, product managers and engineers comment on the same frames. The design file is where decisions get argued about.
• Designer-led teams. If designers own the system, their tool is the natural source of truth, and the tokens there are the most up to date.
• Beyond the app. The same variables drive slides, social images and print, which a sheet isn't built for.

The gap between the design file and the code#

Tokens are values. An agent building a screen needs more than values: it needs to know which button to use, how a dialog opens, what a toast does and how a card responds to a cursor. In a design file those answers live in drawings and prototype settings, which an agent can't fetch as code.

Then there's drift. If the export step runs only when someone remembers, the code and the file slowly disagree. And motion is often the missing piece: design files rarely specify springs and durations for every interaction, so the agent falls back on its default fade.

What a sheet adds#

A sheet closes the gap from the code side. The values are there, as CSS variables and a Tailwind theme the agent loads once. Each slot holds a real component, and every component reads the sheet's values, so the agent fetches a working modal transition instead of interpreting a drawing of one. Rules carry the standing instructions, like "never introduce colours outside the foundations", into every task.

Because the agent asks the sheet directly, there's no export step to forget while you work: edit the sheet and the agent gets the new values the next time it reads it. check_ui then reviews what the agent wrote and lists colours, radii, springs, fonts, shadows, spacing or icon strokes that don't belong.

Using them together#

Often the answer is both. Keep designing in the design tool, and give the agent a sheet that mirrors the decisions:

1. Copy your colour, type, radius and spacing tokens into the sheet's Foundations, and set the shadow style and icon style to match. The guide to designing a sheet goes through each one.
2. Choose a component for each slot that matches your designs, using the live library. The colour palettes, font pairings and icon styles topics help if the design file leaves gaps.
3. Pick a motion spring and the transitions your designs imply, since the design file probably doesn't specify them all.
4. Add rules for anything the agent should know, such as which existing components to keep using.
5. When the design tokens change, update the sheet in the same pull request or sprint.

The honest cost is that you now have two places to keep in step. For a small team where the design file changes rarely, that's a small job. For a large system that changes weekly, it's real work, and a token pipeline straight into your repo may serve your agent better.

How to decide#

• Designers own the system and a pipeline already brings tokens into code that your agents use reliably: keep it. A sheet may only help with motion and component choice.
• Tokens live in the design file and nowhere else: your agent can't see them. A sheet, or at least a tokens file in the repo, gives it something to read.
• There's no design file at all: start with a sheet from a starter vibe, a website or a description of your app, and let the design tool come later if you need one.

The MCP setup guide connects an agent to a sheet, and component libraries vs a design sheet covers the other common setup.