README

AI design-system research

This repository examines how design systems can make intent, rules, semantics, relationships, constraints and implementation explicit enough for AI agents to use the system correctly rather than merely imitate its visual style.

Start here

Understand the research quickly

How LLM agents understand and use design systems is the plain-language entry point for designers, developers, product leads and leaders.

Read the current research synthesis

AI-ready component contracts: reconciled research analysis owns the cross-system conclusions, potential readiness dimensions, evidence gaps and next research questions.

Understand terminology

Canonical research terminology owns shared definitions, including component contract, AI-exposed, AI-ready, AI-optimised, structural validity and semantic correctness.

Inspect a specific external system

The system profiles are the canonical factual summaries for Atlassian, Carbon, Figma, Microsoft/Fluent, SAP and Storybook. Higher-level documents link to these profiles rather than maintaining separate vendor reviews.

Review semantic-naming evidence

The semantic-naming research stream owns naming-specific evidence, the claim ledger, comparative matrices, controlled-vocabulary work and the active Button experiment.

Review candidate component contracts

The Design and Development Contracts are downstream proposal work. Their requirements and examples are candidate architecture, not source evidence or a proven optimum.

Inspect preserved evidence

The corpus/ tree contains captured documentation, public source snapshots, manifests and source indexes. Its status record documents preservation coverage and limitations.

Understand the corpus method

Corpus method explains capture, provenance, evidence labels and preservation boundaries.

Evidence flow and authority

corpus/ and primary external sources
    ↓
analysis/systems/ and distinct topic findings
    ↓
semantic-naming evidence + cross-system synthesis
    ↓
plain-language explanation
    ↓
contracts/ candidate proposals
    ↓
experiments and validation

Use this authority order when documents disagree:

1. Verified primary evidence or an inspectable first-party implementation.
2. The relevant analysis/systems/ profile for a factual claim about that system.
3. The semantic-naming reconciliation and evidence ledger for naming claims.
4. The current cross-system synthesis for research conclusions.
5. The plain-language explainer.
6. Candidate contract documents.
7. Archived research intermediates.

The dependency is one-way: a candidate contract must not be cited as evidence that its own architecture is required.

Active authored structure

analysis/
├── terminology.md
├── ai-ready-component-contract-research.md
├── how-llm-agents-understand-and-use-design-systems.md
├── accessibility.md
├── agentic-lifecycle.md
├── composition.md
├── machine-readability.md
├── systems/
│   ├── atlassian.md
│   ├── carbon.md
│   ├── figma.md
│   ├── microsoft.md
│   ├── sap.md
│   └── storybook.md
└── archive/
 
semantic-naming/
├── README.md
├── research-bundle-reconciliation.md
├── evidence-ledger.md
├── executive-answer.md
├── comparative views and supporting findings
├── button-enum-naming-experiment-v0.2.md
├── sources/
└── archive/
 
contracts/
├── README.md
├── shared-contract-kernel.md
├── design-contract.md
├── development-contract.md
├── button-example.md
├── practical-walkthrough.md
├── research-traceability.md
└── ai-optimisation-record.md

Topic findings

• Machine readability owns the comparison of current agent-access mechanisms and the gap between AI-exposure and semantic readiness.
• Composition owns composition-specific findings and maturity.
• Accessibility owns accessibility-specific implications and evidence gaps.
• Agentic lifecycle is supporting product-facing research and is not evidence that an agent can consume the design system.

Archives

Completed audits, earlier syntheses and superseded experiments are retained under analysis/archive/ and semantic-naming/archive/. They preserve research history but are outside the canonical evidence chain.

Preservation boundaries

• Some documentation hosts rejected automated capture. Their manifests preserve public URLs and access boundaries without bypassing controls.
• Figma community or library assets requiring authentication remain external references; no private workspace was accessed.
• Repository captures are source snapshots whose manifests record upstream and captured revision.
• Forum and practitioner material is supporting evidence and does not become organizational policy without direct verification.