Guide

Design tokens your agent can follow

An agent drifts off your scale when the code lets it write any value. Once UI tokens are props with a fixed set of values, so an agent can't pick a spacing or a colour that isn't in the system.

Updated 56 minutes ago

Most design drift from coding agents comes down to one thing: the code lets them write any value. A style prop takes any number of pixels. A utility class system takes any arbitrary value in square brackets. A colour can be any hex code. The agent picks something close, and close is how a product slowly stops looking like itself. Tokens fix that, but only if the agent can't step around them.

Tokens as props, not as a suggestion

In Once UI, spacing, colour, radius and type are props with a fixed set of values. Spacing takes the tokens in the scale ("4", "8", "12", "16", "20", "24", "32", "40" and up) and nothing in between: there is no "6" and no "10". Colours are a scheme and a weight, like brand-medium or neutral-alpha-weak, never a hex value. An agent writing this can't drift off the scale, because there is nowhere off the scale to write. When the type checker knows the values, a made-up token is a compile error instead of a subtle visual bug.

Colour in pairs

Text colour in Once UI is onBackground, and it is meant to pair with the background behind it: onBackground="neutral-weak" on a neutral page, onSolid on a solid fill. An agent that follows the pairs gets readable contrast in both themes without ever looking at a colour value. We wrote more about this in Colour arrives in pairs.

The rules agents actually break

The compact rules file that ships with Once UI has a table of what to write and what never to write, built from the mistakes agents make most. Two of them are about tokens:

width="32" is 32 pixels, a spacing token. width={32} is a number, which means rem: 512 pixels. Agents mix these up constantly, so the rule says it plainly.
Inline SVGs use currentColor or a CSS variable such as var(--brand-solid-strong), never a raw colour, so icons follow the theme too.

Rules like these are short, but without them an agent has no way to know.

The theme stays in one place

Because every screen refers to tokens, the theme lives in one config file: the brand and neutral scales, the page and surface colours, the border style. Change it there and every screen an agent ever wrote follows. Nothing has to be found and replaced, because no screen ever held the value itself.

Try it

The token values are in ai/tokens.json inside the package, and the docs for AI coding agents show where each file fits. What an agentic design system is covers the rest of the picture.

Read the agent docs

How coding agents read the Once UI component catalog

<Column background="surface" border radius="l" padding="24" gap="16"> <Text variant="label-default-s" onBackground="brand-medium">Pro</Text> <Heading variant="heading-strong-l">Everything in Stack</Heading> </Column>