How LLM agents understand and use design systems

Type: Explainer
Status: Active
Canonical for: Plain-language explanation of the research for designers, developers, product leads and leaders
Depends on: Current research synthesis, canonical terminology, system profiles and semantic-naming evidence

Terms in this explainer follow the shared canonical research terminology. Evidence classifications and system facts remain owned by the linked synthesis, naming research and system profiles.

The short version

An LLM agent does not understand a design system in the same way an experienced designer or developer does.

It does not automatically know the history behind a component, the decisions a team made, or the local meaning of a name such as secondary. It works with the evidence available at the moment it makes a decision. That evidence might include:

a component name;
property and value names;
descriptions and usage guidance;
TypeScript types or another schema;
Figma properties and Code Connect mappings;
Storybook stories;
examples and tests;
accessibility requirements;
relationships to other components;
the product task and surrounding interface.

From those signals, the model predicts what component and configuration best fit the request. If important meaning is missing, it fills the gap using general patterns learned from other code and documentation. That can produce something that looks plausible and compiles correctly while still violating the local design system.

The clearest lesson from the research is therefore:

Giving an agent access to components is not the same as teaching it how the design system expects those components to be chosen and combined.

The industry is getting much better at exposing component inventories, APIs, examples and design-to-code mappings. It is less mature at making selection intent, contextual relationships and composition judgment explicit.

Evidence behind this overview: AI-ready component-contract research, machine readability, and composition analysis.

First, what is an agent?

In this research, an agent is more than the language model by itself. It normally combines:

an LLM that interprets language and chooses actions;
instructions that tell it how to work;
tools that can search documentation, inspect Figma, read code or run tests;
a retrieval system that decides which information to place in context;
validators that can accept or reject the result.

This distinction matters. A model may be capable of understanding a well-written component rule, but the agent will still fail if that rule is never retrieved. Similarly, an agent may retrieve every prop in the library but still lack the guidance needed to choose between Button, Link and Toggle.

MCP can be one way of delivering this information. It is a communication and tool protocol, not a built-in design-system vocabulary. An MCP server can expose excellent guidance or incomplete guidance. The protocol does not determine the quality of the content.

Evidence behind this section: machine readability and AI-ready component-contract research.

How an LLM “reads” a component schema

Imagine the agent receives this simplified component definition:

type ButtonProps = {
  variant: "primary" | "secondary" | "tertiary";
  disabled?: boolean;
  children: React.ReactNode;
};

The model can learn several useful facts from it:

a component called Button exists;
variant accepts only three listed values;
disabled is optional and boolean;
the Button needs content.

But the schema does not say:

whether Button performs an action or can also navigate;
what primary, secondary and tertiary mean in this system;
whether those values describe importance, appearance, color or product purpose;
whether a page can contain several primary Buttons;
whether destructive actions use the same hierarchy;
what makes Button preferable to Link or Toggle;
what accessible label or keyboard behavior is required.

The LLM interprets the words using the immediate schema, any descriptions and examples provided with it, and associations learned during training. Because primary and secondary commonly describe relative action hierarchy on the web, the model may adopt that interpretation even if a local system means something different.

Adding more explicit information changes what the model has to work with:

type ButtonProps = {
  /** Visual prominence within the current action group. */
  emphasis: "high" | "medium" | "low";
 
  /** Consequence of activating the action. */
  impact?: "neutral" | "destructive";
};

This version tells the model that prominence and consequence are separate dimensions. It still does not decide which value is appropriate for a particular product task. That requires context and selection guidance.

An LLM does not execute this schema as a human-written decision tree. It treats the names, descriptions, structure and nearby examples as signals. Strong structure narrows the legal answers. Clear semantics improve the evidence used to choose among them.

Evidence behind this section: semantic-naming executive answer, property-model comparison, and AI/LLM schema research.

Why names can affect an agent’s choice

There are three different naming questions:

Component name: Is this a Button, Link, Toggle or something else?
Property name: Is a decision represented as variant, appearance, tone, intent or emphasis?
Value name: Does the property accept primary, secondary, danger, ghost or another value?

These names are not interchangeable.

The property name can tell the agent what kind of meaning a value carries. Compare:

<Button variant="danger" />

with:

<Button impact="danger" />

The first says only that danger is some kind of alternative. The second suggests that danger concerns consequence. Likewise, emphasis="secondary" tells the agent that secondary is relational, even though the agent still needs to know what group it is relative to.

The cross-system study found that common property names do not have stable meanings. variant, appearance and kind often mix several dimensions. Carbon’s Button kind, for example, includes hierarchy terms, a consequence term and an appearance term. Atlassian’s Button appearance includes prominence, consequence and product-specific identity. Other systems separate some of these dimensions into properties such as category, tone, treatment or color.

The value names also collide. secondary can mean lower prominence in one system and a color treatment in another. danger more consistently signals consequence, but systems differ on whether a destructive action should also be visually dominant. ghost communicates appearance more readily than it communicates when the component should be used.

This does not prove that familiar names are bad. It shows that the words alone do not carry enough local policy to guarantee the intended interpretation.

Evidence behind this section: variant-naming matrix, semantic-collision matrix, and property-model matrix.

What the AI research proves about naming—and what it does not

Controlled studies in related tool-calling and schema tasks show that models respond to names, descriptions and schema wording. When tools have overlapping or misleading descriptions, selection can get worse. When parameter names are opaque or semantically mismatched, models can make different choices. Familiar conventions learned during training can also bias a model toward one interpretation.

That is useful adjacent evidence because choosing a Button value from a finite schema resembles choosing a tool or parameter from a finite schema.

But the research has an important limit:

We did not find a credible public experiment that changes only a design-system enum value such as secondary, holds the component, visual result, description and task constant, and measures the effect on agent selection.

The current evidence does not establish:

how large the naming effect is for real design-system work;
that secondary performs worse than a more intent-oriented name;
that meaningful enum values always outperform opaque identifiers;
that descriptions reliably override a misleading enum name;
that renaming is better than adding definitions, decision rules or metadata;
that one naming architecture works best across model families.

The safe conclusion is narrower: names are part of the evidence an agent uses, but enum-value naming remains a direct design-system evidence gap. A controlled Button experiment has been designed to test it; results must not be assumed in advance.

Evidence behind this section: research-bundle reconciliation, LLM/schema research, evidence ledger, and Button experiment design.

Why descriptions and examples matter

A name is a compressed hint. A description can explain its local meaning and scope.

Consider this legal value:

secondary

The model has to supply most of the interpretation. Now add a description:

secondary:
  description: Supporting action with less visual prominence than the
    high-emphasis action in the same action group.

The agent now knows that the value describes prominence, that the meaning is relative, and that the comparison happens within an action group.

Selection guidance goes a step further:

useWhen:
  - The action supports the main task but is not the action the interface is asking the user to complete next.
avoidWhen:
  - The action navigates to another location; use Link.
  - The action is a persistent on/off choice; use Toggle.

Examples then show the rule in use:

Place order can be the high-emphasis commit action.
Save draft can be a supporting action.
Back to cart may be navigation and therefore a Link, even if it looks button-like.

Examples help because they ground an abstract rule in recognizable situations. Counterexamples are especially useful when they distinguish plausible alternatives. They should not be mistaken for a complete grammar: a Storybook story proves that one configuration exists and can be tested, not that every unshown configuration is invalid.

Descriptions and examples can also conflict or become stale. More text is not automatically better. The relevant guidance needs to be current, specific and retrieved at the right time.

Evidence behind this section: Storybook evidence profile, semantic-naming executive answer, and AI-ready component-contract research.

How an agent decides which component to use

A capable agent’s decision can be understood as a sequence:

Understand the requested outcome. Is the user submitting information, navigating, changing a setting, opening a disclosure or selecting an item?
Find plausible components. Search the current design-system inventory instead of relying on memory or general web conventions.
Compare their boundaries. Read purpose, when-to-use, when-not-to-use and the distinctions between close alternatives.
Apply context. Consider the workflow stage, neighboring controls, platform, product policy, user risk and content.
Choose, clarify or reject. The right result may be a component, a known pattern, a request for missing information or a conclusion that the system has no match.
Retrieve the implementation binding. Find the current package, import, props, defaults and framework-specific behavior.
Configure and compose it. Apply allowed values, parent/child rules, tokens, states, content and accessibility requirements.
Validate the result. Run types, tests and design-system checks, then repair any reported failure.

The agent should not need the entire design-system corpus in its prompt. Too much unrelated or stale material can interfere with the choice. A retrieval system can first expose a small inventory, then bring in the relevant candidates, alternatives and implementation details as the decision narrows.

Evidence behind this section: Carbon evidence profile, machine readability, and AI-ready component-contract research.

Selecting the right component is different from producing valid code

This is one of the most important findings in the research.

Suppose this code compiles:

<Button appearance="primary">View account details</Button>

The import may be correct. primary may be a legal value. The Button may meet its unit tests and look exactly like the design system.

It can still be the wrong design choice if View account details navigates to another page and the system requires a Link for navigation.

There are therefore at least two different kinds of correctness:

Structural correctness: the component exists, the import works, the props are legal and the code follows the schema.
Semantic correctness: the chosen component and configuration are appropriate for the user’s task and the design system’s rules.

Visual similarity is a third thing. An agent can reproduce the appearance of a Button while using the wrong semantic element, losing keyboard behavior or hiding the navigation meaning from assistive technology.

The same distinction applies to composition. An agent can assemble individually valid components into an incoherent interface. SAP describes this as a “Frankenstein UI”: technically valid pieces without the relationships and product intent that made the original system coherent.

Evidence behind this section: composition analysis, SAP evidence profile, AI-ready component-contract research, and research-bundle reconciliation.

What types, enums, schemas and constraints do well

Types and schemas are valuable because they make legal structure explicit.

They can tell an agent or validator:

which components and properties exist;
which properties are required;
which values are allowed;
what defaults apply;
what shape an event or nested object has;
which children or slots are accepted;
which combinations are structurally prohibited.

An enum such as:

type Appearance = "primary" | "secondary" | "subtle";

can prevent the agent from inventing appearance="important". A schema can reject a missing required label. A discriminated TypeScript union can make one property required only when another value is selected. Runtime checks, lint rules and tests can enforce rules that the type system cannot express.

Constraints are strongest when failure feedback explains both the problem and a repair:

Rule button.navigation-use-link failed:
This interaction navigates to another location.
Replace Button with Link and preserve the accessible label.

That is more useful to an agent than a generic “invalid component” message.

Why a valid result can still be wrong

A schema only judges what it has been designed to express. If the schema says that primary and secondary are both legal, it does not know which one fits a particular action unless the selection rule and relevant context are also represented.

Research in adjacent constrained-generation tasks reinforces this distinction. Hard constraints often improve format validity, but they do not automatically improve meaning. In some settings they can force a model to choose a legal answer even when the best response would have been to ask for clarification or reject all available options.

This means validation needs separate questions:

Is the output shaped correctly?
Does it use real components and props?
Is the configuration allowed?
Was the correct component selected?
Is the composition coherent for this context?
Is the result accessible and behaviorally correct?

One “passed” result should not collapse these into a single score.

Evidence behind these sections: AI-ready component-contract research and research-bundle reconciliation.

Why context and relationships matter

Many design decisions are relative rather than absolute.

primary may mean the most prominent action in this action group, not the most important action in the entire product. A destructive action may be serious but intentionally low emphasis until the final confirmation step. A compact control may be acceptable in a toolbar but not in a touch-first mobile flow.

An agent may therefore need context that is not stored in the component itself:

the user’s goal;
the current workflow step;
neighboring actions;
business consequence and reversibility;
platform and viewport;
product-specific policy;
user permissions;
whether information is complete enough to decide.

Relationships make the local grammar clearer. They can state that a component:

requires a particular parent;
accepts named children or slots;
controls another element;
must appear with a label;
cannot be combined with another property;
has a close alternative chosen under different conditions;
belongs to a larger pattern that owns the workflow.

Current systems are much stronger at local relationships such as props, children and slots than at general rules for composing a whole product experience. Examples and templates preserve known good arrangements, but they do not describe every good arrangement.

Evidence behind this section: composition analysis, Atlassian evidence profile, Figma evidence profile, and SAP evidence profile.

Why accessibility, content and behavior are part of understanding

A component is more than a visual shape.

For a Button, an agent may need to know:

that it triggers an action rather than navigation;
which native element or accessibility role implements that meaning;
how it receives an accessible name;
how keyboard focus behaves;
what happens while an asynchronous action is loading;
whether repeated activation is prevented;
how errors and completion are announced;
which labels use clear action verbs;
what happens when text expands in translation.

Figma geometry and screenshots cannot fully communicate these facts. Some are expressed by native HTML, ARIA, code, content guidance and tests. Automated accessibility tests only prove the cases they cover; they do not guarantee that every agent-generated composition is accessible.

Good defaults help. When a mature component implements semantics, focus and keyboard behavior correctly, an agent using the real component inherits some of that quality. But the agent can still misuse the component, omit a required accessible label or create an inaccessible combination around it.

Evidence behind this section: accessibility analysis, Carbon evidence profile, Microsoft/Fluent evidence profile, and Storybook evidence profile.

How the major systems expose this information today

No researched system exposes every kind of component knowledge in one complete, publicly inspectable form. Each demonstrates a different part of the picture.

Atlassian ADS and Rovo

Atlassian describes a “context engine” above its design system: structured content, skills, MCP access, templates and portable documentation intended to help AI understand design intent, constraints and flexibility. It explicitly connects components to compositions, layouts and decision context. Atlassian also reports improvements from its evaluations, but the public material does not provide enough of the schemas, tasks or raw results to reproduce the claims.

What this teaches us: design-system knowledge for agents can include decision context and composition, not only component APIs. Public verification of the newest layer remains limited.

Deeper Atlassian evidence

IBM Carbon

Carbon has two different AI stories that should not be confused. Carbon for AI and AI Label guide teams designing AI experiences. They do not by themselves make ordinary Carbon components machine-readable.

The more relevant evidence is Carbon Builder and Carbon MCP. The public skill shows a concrete operating process: discover available components, find the canonical implementation, retrieve targeted guidance, apply explicit selection and composition rules, and validate the result. Carbon also exposes code, props, tokens, Storybook, accessibility documentation and some Figma Code Connect mappings.

What this teaches us: agent access works best when retrieval, canonical identity, implementation facts and authored rules are joined. Much of the design judgment still exists as operational prose rather than one shared semantic model.

Deeper Carbon evidence

Figma and Code Connect

Figma can expose node hierarchy, component properties, variants, variables, screenshots and selected design context. Code Connect can map Figma components and properties to real code components, props, imports, examples, children and slots.

What this teaches us: Figma is a strong bridge between an existing design instance and implementation. It can tell an agent what was selected and how that selection maps to code. Geometry and mappings do not inherently explain why that component was the right choice. That intent must come from authored rules, documentation or surrounding product context.

Deeper Figma evidence

Microsoft and Fluent

Fluent provides mature component code, typed APIs, tokens, accessibility foundations and usage guidance. Microsoft’s separate agent-design guidance is strong on human-centered behavior, transparency, control and content for AI experiences.

What this teaches us: a robust implementation foundation and strong AI-experience guidance are both valuable, but they are not automatically a machine-readable component-selection layer. The public evidence does not show one unified Fluent contract that joins every component’s design intent to its agent-facing implementation data.

Deeper Microsoft/Fluent evidence

SAP Fiori and the Compositional Design System

SAP states the problem most directly: an AI can combine valid components into an incoherent experience when relationships and intent remain in designers’ heads. SAP describes functional role, supported user intent, contextual fit, relationship logic and generation-time guardrails, reportedly used in Joule Work.

What this teaches us: valid components are not sufficient for valid experiences. SAP provides the strongest public theory of intent-driven composition in this corpus, but the underlying schema, validators and evaluation results are not publicly inspectable here.

Deeper SAP evidence

Storybook

Storybook manifests can expose component names, descriptions, source paths, imports, props, types, defaults, stories, snippets and subcomponents. Its MCP tooling can retrieve documentation and run story tests. Storybook specifically recommends adding meaningful JSDoc because types alone provide only basic information.

What this teaches us: existing component documentation and executable examples can become agent-queryable without inventing an entirely new documentation system. The quality of selection still depends on what authors write. Stories show known states; they do not automatically encode all valid compositions or the reason a component should be selected.

Deeper Storybook evidence

For the cross-system comparison, see AI-ready component-contract research.

Where component meaning lives today

The research found that “the component contract” already exists informally, but it is distributed.

A typical component might have:

its purpose and usage boundaries on a documentation site;
its visual options and local nesting in Figma;
its legal properties and defaults in TypeScript;
its behavior in implementation code;
its states and examples in Storybook;
its accessibility expectations in another guidance page;
its enforced rules in tests or lint configuration;
its exceptions in product documentation;
its real selection logic in the experience of senior designers and developers.

People bridge these sources through experience. They remember that one document is old, know which Figma component maps to which package, understand that a particular “secondary” is an exception, and ask a colleague when the rules are unclear.

An agent may see only one slice. If it sees code, it learns syntax more readily than intent. If it sees Figma, it learns visual structure more readily than behavior. If it sees a Storybook story, it learns one example more readily than the complete selection policy. If it sees prose without current package information, it may understand the rule but implement an obsolete API.

The problem is therefore not simply missing documentation. It is missing connections, unclear authority and incomplete retrieval. An agent needs to know which source is current, what facts that source governs, and how the pieces refer to the same concept.

Evidence behind this section: AI-ready component-contract research and machine readability.

AI-exposed, AI-ready and AI-optimised are different

The research uses three working terms. They are not established industry definitions.

AI-exposed

A component is AI-exposed for a stated access path when an agent can reliably find and inspect its current governed design or implementation artifacts. The agent may still have to infer why the component exists, when it should be selected, which alternatives are better or how it can be composed.

For example, a Storybook manifest might let an agent find Button, read its import and discover that appearance="primary" is legal. That makes the implementation inspectable. If nothing explains when primary is appropriate, how Button differs from Link or which actions may appear together, the component can be AI-exposed without being AI-ready for selection or composition.

AI-ready

A component is AI-ready for a stated capability and context when its governed knowledge is explicit, addressable, current, retrievable and checkable enough that the agent need not invent design-system rules. Remaining ambiguity must support clarification, rejection or escalation.

Readiness is not necessarily all-or-nothing. A component might be ready for code generation because its package, import and props are clear, but not ready for selection because its purpose and alternatives remain implicit. It might be ready for selecting a standalone component but not for composing a full workflow.

“The agent does not have to guess” does not mean every design decision has one objective answer. It means the agent is not forced to infer design-system rules from appearance, common web conventions or undocumented organizational knowledge. When product context is missing or several choices remain acceptable, the agent should be able to recognize that uncertainty and ask, reject or escalate.

AI-optimised

A component is AI-optimised only under stated test conditions: agent performance must be measured against an exact contract and artifact version, task set, model, harness and retrieval setup, using capability-specific criteria. Any claimed improvement must identify the change and its measured effect.

That testing would need to distinguish capabilities such as:

finding the component;
choosing it over close alternatives;
rejecting it when there is no match;
selecting the correct property and value;
producing a legal configuration;
composing it correctly;
preserving behavior and accessibility;
generating the correct implementation;
recovering from validation feedback.

An optimisation claim is limited to the models, tasks, prompts, retrieval setup and component version that were tested. It can expire when the design system or model changes. A permanent label such as AI-optimised: true would hide those conditions.

Evidence behind this section: AI-ready component-contract research and canonical terminology.

What we have learned so far

The research supports these conclusions:

Agents can already retrieve component identities, APIs, tokens, examples and design mappings from mature systems.
This often makes components AI-exposed for implementation access without making them AI-ready for selection or composition.
Names and descriptions are signals that can affect model choices in related tool and schema tasks.
Common design-system words carry different meanings across systems and sometimes mix several semantic dimensions in one property.
Types, enums and schemas improve legal structure but do not guarantee the correct design decision.
Examples help ground intended use but do not define every valid or desirable composition.
Relationships, context, behavior, accessibility and content are part of component meaning, not optional decoration around the API.
Retrieval is part of the problem. Correct information cannot help an agent if it is absent, stale or buried in irrelevant context.
Public design systems expose many needed facts, but those facts remain fragmented and important judgment is still often implicit.
Public evidence for measuring semantic component selection is much weaker than evidence for generating and testing valid component code.

The research does not yet support these stronger claims:

that renaming variants is the main solution;
that one ideal vocabulary will work for every design system and model;
that more metadata always improves agent performance;
that JSON, TypeScript, Storybook, Figma, MCP or any other single format is the complete answer;
that a structurally complete-looking record is automatically AI-ready;
that any current public design system has solved semantic selection and composition end to end;
that a component is AI-optimised before its exact contract and retrieval setup have been evaluated.

A useful mental model

For any component, imagine the agent asking six questions:

What is it? Its identity, purpose and current implementation.
When should I use it? Its selection conditions and close alternatives.
What do its choices mean? The dimension and local meaning of each property and value.
How can it be combined? Its relationships, states, slots and constraints.
How do I implement it correctly? Its package, props, tokens, behavior and accessibility requirements.
How will we know the result is right? Structural checks plus evaluation of the design decision itself.

Most mature systems can answer parts of these questions today. The central opportunity is to make the answers explicit, connected, current and retrievable enough that an agent can apply the system’s judgment rather than merely copy its visible style.

Personal Research

Explorer

how-llm-agents-understand-and-use-design-systems