Personal Research

ai-design-system-research

9 min read

Making design-system decisions legible to AI agents

Type: Introduction
Status: Active
Canonical for: Narrative introduction to the research and its proposed path forward
Depends on: Current research synthesis, canonical terminology, semantic-naming evidence, and candidate contracts

The question behind this research

Design systems already help people build consistent products. They provide components, tokens, guidance, examples, accessibility foundations and implementation code. Experienced designers and developers also carry a great deal of unstated knowledge: why one component is appropriate, what a property means locally, which combinations are coherent and when a familiar pattern should not be used.

AI agents do not automatically inherit that organizational understanding.

An agent may be able to find a Button, inspect its TypeScript properties and generate code that compiles. It may still choose Button where the system requires Link, interpret secondary using a common web convention that conflicts with the local system, or combine valid components into an incoherent workflow.

The primary research question is therefore:

How do mature design systems make their intent, rules, semantics, relationships, constraints and implementation explicit enough that an AI agent can use the system correctly rather than merely imitate its visual style?

This is not primarily research about components that identify AI-generated experiences. Carbon’s AI Label, for example, is a product-facing component. The central concern here is the information an agent needs to understand and apply any governed component correctly.

The central finding

The public design-system ecosystem is much better at exposing implementation truth than design-decision truth.

Agents can increasingly retrieve:

  • component identities, packages and imports;
  • typed properties, finite values and defaults;
  • tokens and variables;
  • Figma structure and design-to-code mappings;
  • Storybook stories, examples and tests;
  • documentation through manifests, skills and MCP tools.

They are less consistently given:

  • the component’s purpose;
  • observable conditions for choosing or rejecting it;
  • distinctions from plausible alternatives;
  • the local meaning and scope of properties and values;
  • parent, child, peer and pattern relationships;
  • prohibited combinations and contextual constraints;
  • what belongs to the design system versus product policy;
  • when the available evidence is insufficient and the agent should clarify, reject or escalate.

This gap matters because valid code is not necessarily the correct design decision. Types can prevent an invented property. They cannot, by themselves, establish that the correct legal component or value was selected.

Three states in the research

The exact definitions are owned by canonical terminology. In simple terms:

AI-exposed

An agent can reliably find and inspect current governed design or implementation artifacts through a stated access path. Some governed meaning may still need to be inferred.

Example: Storybook exposes Button, its import and its legal appearance values, but does not explain when Button should be chosen over Link.

AI-ready

For a stated capability and context, enough governed knowledge is explicit, current, retrievable and checkable that the agent does not have to invent design-system rules. Remaining ambiguity can be detected and handled through clarification, rejection or escalation.

Example: the agent can compare Button and Link using explicit purpose, use and avoidance conditions, then retrieve the correct implementation binding.

AI-optimised

Agent performance has been measured against an exact contract and artifact version, task set, model, harness and retrieval setup, and it meets defined capability-specific criteria.

These states are a conceptual progression, not a universal maturity score. AI-exposure does not imply AI-readiness, and a component that appears AI-ready is not AI-optimised until performance is tested.

What the evidence establishes

The research currently supports the following conclusions:

  • Mature systems already express many relevant facts, but those facts are distributed across documentation, Figma, code, Storybook, tokens, tests and organizational knowledge.
  • Carbon provides a strong inspectable example of agent-specific discovery, code/documentation retrieval, selected decision rules and validation instructions.
  • Storybook provides strong component, documentation, example and test serialization, while depending on authors to supply meaningful selection guidance.
  • Figma and Code Connect provide strong design-to-code identity and property mappings, but correspondence does not establish appropriateness.
  • Atlassian publicly describes a broader context layer joining intent, composition, skills and agent tooling, although important schemas and evaluation details are not inspectable in this corpus.
  • SAP most directly articulates the need for functional role, supported intent, contextual fit and relationship logic, while its compositional implementation remains largely unavailable for public verification.
  • Microsoft combines mature Fluent implementation foundations with strong agent behavior, content and accessibility guidance, but does not expose one connected public Fluent selection layer.
  • Component and tool names affect model choices in tested adjacent tasks. Property and parameter names have narrower direct evidence. Direct effects of design-system enum-value names remain unproven.
  • Descriptions add local meaning, but they are not proven to reliably override conflicting enum labels.
  • Types, schemas and constraints improve structural validity. They do not guarantee semantic correctness.
  • Standards such as WAI-ARIA, SKOS, DTCG and JSON Schema show that roles, states, labels, types, relationships and constraints can be represented. They do not prove that a particular representation improves LLM performance.

The current synthesis owns the complete evidence boundaries. Detailed naming claims live in the semantic-naming reconciliation and evidence ledger. Facts about each external system live in the system profiles.

What remains unproven

The research does not yet establish:

  • one optimal AI-ready component-contract architecture;
  • that public variants should be renamed;
  • that structured useWhen and avoidWhen fields outperform equivalent prose;
  • that more metadata always improves agent decisions;
  • that factored properties are better for agents than a mixed property plus strong guidance;
  • the best balance among in-context instructions, constrained generation and post-generation validation;
  • a universal schema, serialization or delivery protocol;
  • a general benchmark for semantically correct component selection and composition;
  • that any public system has solved the problem end to end.

The candidate Design and Development Contracts are therefore a testable response to the research—not the result the evidence has already proven.

Proposed path forward

1. Define the first capability boundary

Do not attempt to certify an entire design system as AI-ready.

Choose a bounded capability such as:

  • discovering approved components;
  • selecting among Button, Link and Toggle;
  • configuring Button hierarchy correctly;
  • composing one known action group;
  • generating a framework-specific implementation.

Define what the design system governs, what product context must supply and when clarification or no-match is correct.

Exit condition: a written capability scope, decision policy and authoritative source list.

2. Establish the AI-exposed baseline

For the chosen component family, verify that an agent can reliably discover and inspect the current artifacts:

  • canonical identity and lifecycle;
  • documentation and usage guidance;
  • Figma component and property definitions;
  • package, imports, types and implementation source;
  • Storybook examples and tests;
  • accessibility and token references;
  • version and deprecation information.

Record what is explicit, derivable, human-inferred and missing. This establishes access without pretending that access equals understanding.

Exit condition: a repeatable access path and a version-linked inventory of authoritative artifacts.

3. Define and validate the human gold policy

Before evaluating an agent, experienced designers and developers must agree on the governed decisions being tested.

For Button, Link and Toggle, this could include:

  • purpose and selection boundaries;
  • close alternatives;
  • the intended semantic dimension of each relevant property;
  • known context requirements;
  • legal and prohibited configurations;
  • acceptable ambiguity and clarification cases.

The gold policy should not be reverse-engineered from whatever answer the model produces.

Exit condition: versioned scenarios and expected outcomes with sufficient expert agreement.

4. Test naming as its own question

Run the active Button enum-value and property-name experiment only after its label pretest, expert review and power simulation are complete.

Keep implementation, descriptions, tasks and legal concepts fixed so the experiment can isolate naming rather than mixing hierarchy, consequence, navigation, appearance and constraint architecture.

Exit condition: measured evidence about naming under stated models and conditions—not a predetermined rename decision.

5. Compare minimum-sufficient contract conditions

Treat the candidate contract fields as experimental conditions rather than one indivisible package. Compare, for example:

  1. current implementation artifacts only;
  2. names plus concise descriptions;
  3. descriptions plus decision boundaries and alternatives;
  4. the same information in structured fields;
  5. relationship and constraint information added;
  6. focused retrieval versus broad documentation delivery.

Measure whether each addition improves the targeted capability and whether it introduces context cost, stale duplication or candidate interference.

Exit condition: evidence about the smallest decision-sufficient information set for the chosen capability.

6. Prototype one connected contract path

Use the candidate contracts as one prototype model for linking distributed authoritative facts. Do not duplicate facts that can be derived reliably from code, Figma or Storybook. Concentrate human authorship on meaning and judgment that those sources do not express.

A pilot should connect:

  • stable component identity;
  • purpose, useWhen, avoidWhen and alternatives;
  • semantic property/value definitions;
  • Figma and implementation mappings;
  • relationships and constraints;
  • accessibility requirements;
  • version, provenance and validation links.

Exit condition: a maintainable, versioned pilot for a small component family—not a system-wide migration.

7. Test the complete agent workflow

Evaluate the agent across distinct stages:

  • discovery and retrieval;
  • component selection and correct no-match;
  • property and value selection;
  • valid configuration;
  • local composition;
  • implementation and imports;
  • accessibility and behavior;
  • repair after validation feedback.

Keep structural validity, semantic correctness, behavioral correctness and visual fidelity as separate measures.

Exit condition: a reproducible baseline tied to exact artifacts, models, prompts, tools and retrieval configuration.

8. Optimise only from observed failures

If evaluation reveals a recurring failure, test competing remedies:

  • clearer names;
  • better descriptions;
  • examples or counterexamples;
  • explicit alternatives;
  • structured metadata;
  • retrieval changes;
  • relationship or constraint records;
  • deterministic validation and repair.

Record the changed artifact, hypothesized mechanism, measured effect and any regression. Only then is an AI-optimised claim justified—and only under the conditions tested.

Exit condition: measured improvement with scope, uncertainty, costs and expiry conditions recorded.

9. Decide whether and how to adopt

After the pilot and evaluations, decide what belongs in:

  • the component’s logical contract;
  • authoritative implementation sources;
  • design guidance or patterns;
  • the retrieval/access layer;
  • product context and policy;
  • deterministic validators;
  • the evaluation record.

Only at this stage should the organization consider a production format, governance model, broader migration or public API change.

Begin with one controlled action family—Button, Link and Toggle—and two connected but separate workstreams:

  1. complete the hierarchy-only naming experiment prerequisites; and
  2. establish an AI-exposed baseline and minimum-sufficient selection contract for the same family.

This combination tests both sides of the central question:

Does the name change the agent’s decision, and is the deeper problem that the system has not explicitly encoded what the component means?

The work should stop short of a production naming change or system-wide contract rollout until those questions have measured answers.

Where to continue reading

6 items under this folder.