A design token is a named design decision.

Before the experiment: the cast. These six components cover the full space of “something the user needs to know.” They differ in persistence, scope, prominence, and whether they require action. None of that is in the name.

What an AI reads when given this list with no additional context: six words. What a designer reads: six years of accumulated intuition about when each one is right. The experiment is about closing that gap.

The four roles — ephemeral, persistent, blocking, inline — are the real taxonomy. But that taxonomy isn't in the names. Toast, Alert, and Banner all sound like variations on the same thing. The experiment will show what it takes to get an AI to understand the difference.

The experiment holds the briefs constant and varies only what the model knows about the design system. At level one, it has component names. At level four, it has a full usage spec. The reasoning shown at each level reflects the structure of what a frontier model actually produces — not paraphrased, but representative of the pattern.

The rendered output matters: when the wrong component is picked, it's not just the wrong name. It's a fundamentally different interaction — one that persists when it should disappear, or disappears when it should stay, or allows dismissal when it should require acknowledgment.

Component names are identifiers, not descriptions. Toast comes from Android's notification system. Alert comes from browser window.alert() and Bootstrap. Banner comes from marketing. All three have different implied semantics from their origin systems — and the LLM's prior for each one is whatever it absorbed from millions of Stack Overflow posts, UI libraries, and changelogs.

When you give the model only a component name, it doesn't read your system — it reads its own history with that word. That's why the errors are systematic, not random.

At context level 2 — names plus one-line descriptions — the model does marginally better. But descriptions tend to describe appearance or general function: “a brief notification,” “a message displayed to the user.” These are still too similar to disambiguate the hard cases. The information that actually breaks the tie isn't what the component is — it's when you're supposed to use it, and when you're not.

A description answers “what is this?” A when-to-use clause answers “when should I reach for this?” The second question is the one an AI agent is actually trying to answer when it's building a UI from a brief.

The when-to-use clause works because it's written in the same terms as the brief. “Ephemeral confirmations that don't require user action” matches directly to “confirm a file was saved.” “Product-wide messages the user must be aware of across their entire session” matches directly to “they need to see this across the whole app.” The model isn't inferring — it's matching.

Positive examples add information about where to go. Negative examples add information about where not to go. In probability terms: a positive clause shifts probability mass toward one option. A negative clause removes it from others. When the confusion is between two plausible options — Toast vs Alert, Alert vs Dialog — removing one from the candidate set is more efficient than strengthening the other.

This is the same reason RLHF uses human preference comparisons instead of absolute ratings. “A is better than B” carries more signal per annotation than “A is good.” The do-not clause is writing that kind of signal into your documentation.

The do-not clause also has a practical effect for human readers: it names the trap. “Alert disappears when the user navigates away” is something a senior designer knows. A new hire doesn't — and will reach for Alert for persistent messages and wonder why users keep missing them. The same sentence serves both readers.

The context layer doesn't need a new format — it needs the right fields in whatever format you already use. The three examples below show the same component spec in three different shapes. Pick the one that fits your toolchain.

What most design systems actually ship: a Storybook demo with a controls panel and no prose. Sometimes a one-line description. Rarely a when-to-use clause. Almost never a do-not. The tooling exists; the content is the gap.

The four context levels in the experiment held the number of components constant at one. Most real briefs don't. When an AI composes a UI with multiple components — even with accurate when-to-use and do-not clauses for each — it still needs to know how they relate. Which can contain which. Which can co-appear. Where each must sit in the layout hierarchy.

These aren't component-level questions. A Banner's do-not clause can say “don't use for transient feedback.” It can't say “don't be a child of Dialog” — because that constraint involves another component. That's the composition layer: cross-component rules that the intent layer can't encode alone.

Relationship rules follow the same principle as when-to-use and do-not clauses — they encode knowledge that exists in the heads of experienced designers but isn't written anywhere an AI can read. The format is a natural extension: a relationships block added to the same component spec.

Three dimensions cover most of the cross-component constraints that produce visible failures: containment (what can parent what), region (what can share visual space), and position (where within a layout hierarchy). The examples below add these to the Banner spec from the previous module.