Design Tokens Are Agent Instructions

This module sets the foundation for the whole course: the design system only works for agents to the degree that its decisions are exposed as inspectable project material. Tokens are the smallest, most concrete unit of that material, which is why the course starts here rather than with DESIGN.md or audits.

Be explicit about the reframe in the title. Most teams treat tokens as a styling convenience — a way to avoid repeating hex values and to support theming. That framing undersells them. When an agent generates UI, the token file is one of the few places it can learn what the product has actually decided: which red means escalated, how tight a table row should be, what radius a chip is allowed. The name and description carry the instruction; the value is almost the least interesting part.

Set expectations on prerequisites. Participants should already run a design system of some kind — even a small one — and should have seen an agent generate UI at least once. The module does not require any particular token tooling; the examples use the DTCG JSON format and CSS variables because they are the most portable, but the principles apply to Tailwind themes and canvas variables equally.

Open with the failure everyone has seen: the agent produces something polished and plausible, and it does not look like your product. The instinct is to write a longer prompt asking for better taste. That rarely works, because the problem is not eloquence — it is that the actual decisions live in someone's head, in Figma comments, or in chat history, none of which the agent reads at generation time.

The definition to land is that a token is a named design decision, not a variable that holds a colour. The Design Tokens Community Group format makes this explicit: a token has a type, a value, and a description, and the description is where the meaning lives. For agentic work the practical point is that the agent reads the name and the description and decides where the value belongs — which is exactly the behaviour you cannot get from a palette swatch.

Close with the limit so nobody overclaims: tokens make taste applicable and testable, they do not generate it. Choosing that escalated work gets a hot foreground colour while blocked work stays muted is a design decision a person makes once. The token is how that decision survives contact with the next hundred agent runs.

This is the core distinction of the module, so take time with it. Primitive tokens — blue-500, gray-900, spacing-4 — are real and necessary; they define the raw ingredients. But if primitives are all the agent can see, it still has to guess when each value belongs, and its guess will be the statistically average answer rather than your product's answer. Semantic tokens carry the product meaning: status.escalated, surface.panel, table.row.compact. Component tokens go one step further and carry local rules, like the radius a status chip uses in dense tables.

The last two rows are where the payoff for agentic work sits. Propagation: when a semantic token aliases a primitive, a rebrand or a contrast fix is a one-line change at the source rather than a hunt across components. Verifiability: a reviewer — human or scripted — can check that a status chip uses the status token, because the name encodes the expectation. With raw values, there is nothing to check against; any red is as legal as any other.

Be honest that maintaining a semantic layer costs effort, and small teams often skip it. The argument of this course is that agents change that calculus: the semantic layer is no longer documentation overhead, it is the interface through which most generated UI will be produced.

The four dimensions on the slide — surface, emphasis, state, density — are not the only possible taxonomy, but they cover the decisions agents most often get wrong: putting content on the wrong surface level, making everything equally loud, reusing a status colour as decoration, and defaulting to roomy spacing in products that need to be dense. If the token names answer those four questions, the agent has far fewer gaps to fill with guesses.

Contrast intent-carrying names with appearance-carrying names. brand-red-dark, blue-light, big-padding all describe what the value looks like, which the agent can already see from the value itself; the name adds nothing. status.escalated.foreground, surface.panel, spacing.table.row.compact describe when the value applies, which is exactly the information the value cannot carry on its own.

Descriptions matter more for agents than they ever did for humans, because the agent actually reads them at generation time. A one-sentence description that states the rule and the boundary — escalated is for immediate attention, do not reuse it as decoration — is the cheapest piece of agent instruction you will ever write. The DTCG format has a dedicated description field; Tailwind themes and CSS variables can carry the same information in adjacent comments or in DESIGN.md, which Module 2 covers.

Walk the table as a stack rather than a list of alternatives. Source token files — DTCG-style JSON split into primitives, semantics, component tokens, and theme overrides — are the layer a person edits deliberately. Build tooling such as Style Dictionary, or a Tailwind v4 theme, turns those into the CSS variables and utility classes the application actually consumes. Component code maps those variables into props and classes. Canvas tools hold the same decisions as design variables: Figma variables reachable over MCP, and connected-canvas formats like .pen and .op, which store variables as readable JSON and generate CSS custom properties on export. DESIGN.md sits alongside all of it and carries the judgment — which tokens are preferred, which are dangerous — which is Module 2's subject.

The instruction that matters for agents is the source-versus-generated distinction. If the agent cannot tell which files are edited and which are built, it will eventually edit a generated file, and the next build silently erases its work — or worse, the edit survives and the source and output disagree. State it explicitly in the harness: edit tokens/, never edit src/styles/tokens.css.

Do not resolve the multi-tool sync question here. Module 5 covers choosing a source of truth across Figma, canvas, and code, and keeping the mirrors honest. For this module it is enough that the agent can find the token contract in the repository it is working in.

This slide names the default behaviour so it stops being surprising. Agents are completion systems: when the project does not state a decision, the model supplies the most statistically common answer for that kind of UI. That is where the recurring tells come from — the soft blue accent, the large rounded card, the generous padding, the marketing gradient. None of it is wrong in general; it is just not your product.

The drift mechanics are worth spelling out. A hardcoded near-miss value has no name, so nothing connects it to the system. The next run, or the next teammate's run, picks a slightly different near-miss. Each one passes a quick visual review, because each one is internally consistent and polished. Six weeks later the audit finds eleven reds that mean four different things, and unwinding them is a project. The school's audit article and Module 4 of this course deal with finding that drift; this module is about not creating it.

Also flag the subtler failure: misuse of meaningful colours. If warning orange is the most exciting colour in the palette, an unconstrained agent will use it to add visual interest. Only a token rule — warning is for recoverable risk, never decoration — gives a reviewer or a script something to point at when that happens.

Walk the top row first. The decision is made once, by a person, in the token source file: the name says what it means, the description says when it applies, and the value is an alias to a primitive. The build turns it into a CSS variable with the same name — generated, never hand-edited. The agent, with the token contract in its context, reads the name and description and writes var(--color-status-escalated-foreground) into the component. The outcome card is the point: one change at the source updates every use, a reviewer or a script can verify the usage mechanically, and themes and dark mode come along for free because the component points at the system rather than at a value.

Then the bottom row. Without a contract, the decision arrives as a phrase in a prompt — use our red for urgent — or not at all. The agent fills the gap with a plausible value, the value lands in the component as a raw hex, and from that moment it has no name, no owner, and no connection to anything. When the system's red changes, this one stays. The audit finds it months later as a finding to fix, multiplied by every unbriefed run in between.

Emphasise the highlight: on day one, screenshots of the two paths look almost identical. That is why screenshot-only review does not catch this class of problem, and why the token rules in the next slide are written as harness rules rather than review reminders.

The harness here means the standing material the agent loads at the start of every session: DESIGN.md, the platform's instruction file (CLAUDE.md, AGENTS.md, or equivalent), and the token files those documents point at. The distinction from prompting matters operationally — anything that has to be repeated per task will eventually be forgotten, and the run that forgets it is the run that introduces the drift.

Walk the rules and why each earns its place. Read the token files first: output quality tracks what the agent can see. Semantic over primitive: the meaning is the instruction. Never hardcode and never invent: these are the anti-slop rules — the same pattern brand-spec approaches use, where all generated markup references var(--token) and nothing else. Propose missing tokens before using them: this is the most important behavioural rule, because it converts the agent's gap-filling instinct into a visible design decision a human approves. Source versus generated: prevents silent overwrites. Run the verification script: a small script that flags raw hex, rgb(), arbitrary radius and spacing values gives the agent mechanical feedback before a human spends attention on the work.

Keep DESIGN.md guidance short and pointed at the files; do not paste the whole token set into it. Module 2 covers the full document; Module 3 covers how the review gate uses these same rules as entry criteria.

Each row pairs a sentence that feels like guidance with one that actually constrains behaviour. The left column is not wrong, it is just unenforceable: the agent can satisfy use our blue palette with any blue in any role, and a reviewer cannot point at a violation because no rule was stated. The right column gives the agent a token name, a scope, and in the strongest rows a verification step.

The warning-versus-escalated row deserves a comment because it is the most common semantic failure in real audits: one orange doing the work of three different meanings. The fix is rarely a new colour — it is usually splitting one token into tokens whose names carry the distinction, and writing one sentence about the boundary.

The last row is the bridge to review. Match the design system is a hope; run the script and attach the screenshots is an instruction whose completion can be checked. That pattern — every rule paired with the evidence that proves it was followed — is the backbone of the review gates in Module 3 and the audits in Module 4.

This audit is small enough to run in an afternoon and it is worth doing before any of the later modules, because everything downstream — DESIGN.md, review gates, drift audits — assumes the token names mean what they say. An agent is a literal reader: a token named brand-red-dark will be used wherever a dark red seems nice, because that is all the name claims.

The overloaded-token check usually produces the most valuable findings. When one colour serves overdue, blocked, and escalated, no instruction can teach the agent the distinction, because the system itself has not made it. The fix is a design decision, not a renaming exercise — which is exactly why this work belongs to the design system lead rather than to whoever maintains the build.

The last bullet is the inverse problem and the easiest to miss: decisions the team makes constantly that have no token at all. Density is the classic one. If compact table rhythm exists only as a habit in two senior designers' heads, every agent run and every new hire re-decides it. Listing those missing tokens is as valuable as fixing the misnamed ones. You can run this audit with the agent itself — ask it to read the token files and report names it finds ambiguous, with reasons — and treat its misreadings as data about where the names fail.

This example follows the dashboard scenario from the school's token article. The component is deliberately small — a status chip in a support queue table — because small components show the mechanism clearly. The prompt was held constant across both runs: build the status chip for the queue table, follow the design system.

Before the cleanup, the project exposed only a primitive palette. The agent produced a competent chip: a rounded-full pill, raw hex colours, and one orange carrying every non-normal state. Each review round consisted of re-explaining meanings the project had never written down — escalated is hotter than blocked, chips stay compact in dense tables — and each explanation lived only in that conversation, so the next run would need it again.

After the cleanup, the same prompt hit a project with semantic status tokens, a component token for chip radius, a density token for the queue rows, and the harness rules from earlier in this module. The implementation referenced the variables by name, the verification script passed, and the one review round that remained was a real design conversation: the agent proposed a missing token for a state nobody had specified, and the human decided what it should be. That is the shape of the division of labour this course is building towards — the agent surfaces the gap, the human makes the call, the token records it.

Keep the scope tight: five tokens, not a taxonomy redesign. The learning is in the discipline of writing a name and a single sentence that would survive being read by a literal-minded agent with no other context. Most participants find the sentence harder than the name — stating the boundary (and not for decoration, only in dense tables, never on the page background) is where the actual design decision gets made explicit.

The third bullet is there so the exercise stays honest about cost. A rename touches the source file, the generated output, every component that referenced the old name, and possibly canvas variables in Figma or a connected canvas. That is not a reason to avoid renaming; it is a reason to know the blast radius before proposing it, and it previews the migration and sync work in Module 5. Renaming is also a task agents do well under supervision, since it is mechanical once the new name is decided.

If participants try the optional step, the agent's review of the new names is the most useful feedback in the exercise. Where the agent still hesitates or misapplies a token, the name or the description is still carrying too little. Collect those cases if running this live — they make excellent material for the DESIGN.md drafting session in the next module.

Recap by connecting the bullets into one argument rather than re-reading them. Tokens are how the system speaks to an agent at the level of individual decisions; semantic naming is what makes that speech precise; missing or vague tokens get answered with plausible guesses that compound into drift; and the rules that prevent the guessing belong in standing harness material, where they apply to every run rather than to the runs someone remembered to brief.

Name the limit honestly: tokens carry decisions, but they cannot carry judgment. A token file cannot say that the dashboard should never be wrapped in decorative cards, that warning colour is being overused as visual interest, or what the product should refuse to do. That judgment needs prose a human can read in ten minutes and an agent can load in every session — which is exactly what DESIGN.md is for, and why it is the next module rather than an afterthought.

If participants did the exercise, ask them to bring the five renamed tokens and the one new token to Module 2. The token section of their DESIGN.md draft starts from that list, and Module 4 turns the same list into audit rules with evidence requirements.