AI-ready component contracts: reconciled research analysis

Type: Synthesis
Status: Active
Canonical for: Cross-system conclusions about AI-exposure, AI-readiness, potential component-contract information, evidence gaps and open research questions
Depends on: Canonical terminology, system profiles, semantic-naming reconciliation, semantic-naming evidence ledger, and distinct topic findings

No component-contract format, PDS API change, naming change, ontology, governance model or implementation architecture is recommended here.

Primary naming evidence: Research-bundle reconciliation and evidence ledger. These portable records preserve the corrections from the original external synthesis; the source archive retains the underlying inputs without making their older wording canonical.

Corpus boundary: This analysis reconciles the later semantic-naming synthesis with the preserved Atlassian, Carbon, Figma, Microsoft/Fluent, SAP and Storybook corpus and the earlier cross-system work. Public absence is recorded as “not found,” not proof that an organization has no internal capability.

Terminology: Use the shared canonical research terminology. Terms describing role/function remain provisional except when quoting a source system’s vocabulary.

1. Working definitions

The exact definitions are owned by canonical terminology. This synthesis uses them as follows:

State	Research use
AI-exposed for an access path	The agent can reliably discover, retrieve and inspect current governed artifacts. Selection meaning or decision logic may remain implicit.
AI-ready for a capability and context	Enough governed knowledge is explicit, addressable, current, retrievable and checkable that the agent need not invent design-system rules.
AI-optimised under tested conditions	Performance against an exact contract/artifact version, task set, model, harness and retrieval setup has been measured and meets stated criteria.

The component contract is logical and version-linked, not necessarily one file, record, schema or repository. These working states are capability- and context-specific rather than universal certifications.

Supported: agents need more than appearance or API syntax to make selection decisions. Across the corpus, types, source, stories and mappings reliably expose existence and implementation; authored guidance supplies purpose and boundaries; relationship and constraint artifacts supply legal composition; retrieval determines whether those facts reach an agent. Machine readability, composition, system profiles

Challenge 1 — “enough” is task-relative. The information needed to reproduce an existing Figma instance is smaller than the information needed to select a component for a novel workflow. Readiness must therefore be stated against a capability and context, not treated as an intrinsic property of a component.

Challenge 2 — “does not have to guess” cannot mean zero uncertainty. Product intent may be incomplete, multiple designs may be acceptable, and business policy may sit outside the shared system. Operationally, the phrase should mean that the agent is not required to infer governed facts from appearance, conventional terminology or undocumented organizational knowledge. Residual ambiguity must be detectable and support rejection, clarification or escalation.

Challenge 3 — possession is not delivery. A contract can contain the right facts while retrieval omits them. Carbon Builder and Storybook show that identity, targeting, source/version context and exposure curation affect whether a decision receives the relevant information. Retrieval/access belongs in the readiness chain even if it is not embedded in the component record. Carbon query protocol, Storybook manifests

Challenge 4 — legal is not correct. Types, schemas and constrained decoding can prevent nonexistent fields or values while still producing a valid but semantically wrong choice. The reconciled evidence documents direct adjacent evidence for this validity–correctness split. Research-bundle reconciliation, evidence ledger AI-07

Operational implication: “current” and “addressable” require provenance, version, status and source authority even though the short definition does not enumerate them. Carbon reconciles code and documentation through canonical identity and freshness; Code Connect carries mapping sources; Storybook manifests carry paths and imports; package status and deprecation can diverge across artifacts.

AI-optimisation is deliberately separate from readiness. A structurally rich contract is not proven effective merely because it looks complete. Its unresolved terms are substantial:

capability-specific performance criteria require a gold policy, uncertainty bounds and separate semantic/structural metrics;
optimisation is model-, harness-, task-, retrieval- and version-specific;
success includes appropriate no-match and clarification, not only positive selection;
schema-key wording produced effects in opposite directions across the model families tested in one study, so model interaction must remain exploratory rather than being generalized into one preferred wording;
tuning for selection can harm maintainability, human comprehension or another lifecycle stage;
an optimisation result expires when components, guidance, retrieval or models change.

Boundary: exposure concerns access and inspectability; readiness adds sufficient explicit and checkable governed meaning for a stated capability; optimisation concerns measured performance under defined conditions. Exposure does not imply readiness, and readiness alone does not establish optimisation.

2. What an agent may need to know about a component

This taxonomy is provisional and derived from jobs performed by current artifacts. It is not a proposed contract schema.

Information class	Decision it supports	Existing forms in the corpus	What it does not settle
Identity and provenance	Find the canonical concept and authoritative artifact	component IDs/keys, names, package/import, source paths, Code Connect mappings, Storybook IDs, URLs, versions	whether the concept is appropriate
Purpose and selection boundary	Choose or reject the component	purpose prose, when/avoid guidance, alternatives, prohibitions, skill rules, decision trees	exact legal API configuration
Semantic dimensions	Interpret properties without conflating appearance, hierarchy, role, tone, consequence or state	prop names, enum groupings, documentation definitions, semantic token grammar	which factorization is optimal for agents
API shape	Emit an existing implementation	TypeScript props, required/default values, enum unions, events, schemas, imports	semantic correctness of legal values
Behaviour and lifecycle	Predict what interaction does over time	event contracts, native semantics, stories, tests, state machines, async/streaming code	product policy for when behaviour is appropriate
State	Represent current condition separately from enduring intent	disabled/loading/selected/error props, ARIA states, visual/interaction stories	why the state occurred or what action follows
Composition	Build legal local structures	children, slots, subcomponents, discriminated APIs, templates, nested Figma mappings	coherence of a novel page or workflow
Relationships	Connect the component to parents, peers, targets, alternatives, patterns and tokens	slots, `commandFor`-like targets, component mappings, linked docs, rule prose	a shared relationship vocabulary or agent benefit
Accessibility	Preserve role, label, focus, keyboard and assistive-technology behavior	semantic HTML/ARIA, accessibility guidance, stories/tests, component defaults	accessibility of every generated composition
Content	Supply understandable labels and bounded copy	voice/tone, content guidance, examples, localisation assets	product-specific language and every locale
Visual and token realization	Apply system appearance consistently	typed/semantic tokens, variables, themes, references and aliases	selection intent unless semantics are authored
Examples and counterexamples	Ground expected use and boundaries	stories, snippets, MDX, templates, screenshots, positive/negative prose	exhaustive validity or causality
Constraints and validation	Prevent or detect illegal configurations	TypeScript, JSON schemas, skill hard rules, parsers, linting, story/a11y/interaction tests	the correct choice among legal configurations
Lifecycle metadata	Avoid obsolete or unsupported assets	version, preview/stable status, deprecation, aliases, replacements, changelogs	migration fitness for a particular product
Retrieval context	Deliver the smallest decision-relevant slice	MCP tools, manifests, query protocols, skills, curated tags, rules files	optimal packet size and ordering

The important finding is not that every component needs every class. It is that current “component truth” performs different jobs in different artifacts. Collapsing those jobs into one generic metadata category would lose the distinctions the research is trying to preserve.

3. Cross-system evidence matrix

Reading the matrix

This is a derived comparative view. The six system profiles own the factual interpretation of each external system; the semantic-naming reconciliation and ledger own the AI-evidence classifications. This matrix does not create a second source of vendor facts.

E — Explicit: directly represented in an inspectable artifact, or explicitly documented where public implementation is unavailable.
P — Partial: present for some components or represented incompletely.
I — Implicit: can be inferred by a knowledgeable user from examples, structure or convention, but is not directly represented for the decision.
N — Not found: not found in the preserved public evidence; not a claim of organizational absence.

Short references identify the evidence source in each cell:

A: Atlassian profile and context-engine article
C: Carbon profile, Builder skill and framework rules
F: Figma profile, Code Connect integration and mapping fixtures
M: Microsoft profile, agent guidance and Fluent source
S: SAP profile, recovered official evidence and OpenUI5
B: Storybook profile, manifest specification and MCP API
AI: semantic-naming reconciliation and evidence ledger
Std: controlled-vocabulary analysis, WAI-ARIA, DTCG, SKOS, MCP and JSON Schema as cited there and in the new synthesis.

Identity, purpose and semantics

Potential information	Atlassian	Carbon	Figma	Microsoft/Fluent	SAP	Storybook	AI/LLM research	Standards
Component identity	E [A]	E [C]	E [F]	E [M]	E [S/OpenUI5]	E [B]	Component/tool names causal [AI §§8,21]	Concept/tool identifiers [Std]
Stable cross-artifact identity	P [A]	E for indexed code/docs; P system-wide [C]	E for mapped design/code [F]	P via packages [M]	P conventional code only [S]	E within manifest; P across design [B]	Retrieval relevance adjacent [AI §18]	Identity/label separation [Std/SKOS]
Purpose	E in guidance [A]	P, strong for selected rules [C]	P only via authored instructions [F]	P in docs [M]	E documented [S]	P/conditional on JSDoc [B]	Descriptions useful [AI §§12,17]	Descriptions/definitions [Std]
When to use	E documented [A]	P explicit docs/skills [C]	P custom rules [F]	P human guidance [M]	E documented, schema unavailable [S]	P authored docs [B]	Boundary evidence adjacent [AI §18]	Annotation precedent only [Std]
When not to use / no-match	P [A]	P explicit prohibitions [C]	P custom rules [F]	P behavioral boundaries [M]	P documented [S]	P authored docs [B]	Relevance/abstention adjacent [AI §§18,23]	Not generally mandatory
Functional role	P [A]	P in rules/docs [C]	I from mapped implementation [F]	P native/agent guidance [M]	E documented, not inspectable [S]	P JSDoc/native code [B]	Component naming selection adjacent/direct [AI]	E in ARIA/native semantics [Std]
Contextual fit/scope	P, tier/app context [A]	P in prose [C]	I from node surroundings [F]	P product guidance [M]	E documented, not inspectable [S]	I from story/docs hierarchy [B]	Retrieval packet hypothesis [AI §18]	Scope notes precedent [Std/SKOS]
Hierarchy/emphasis	E in docs/tokens [A]	E but mixed in `kind` [C]	E as variant/property values, meaning library-dependent [F]	E in APIs/docs [M]	P [S]	E if API exposes it; semantics author-dependent [B]	Enum-name effect unestablished [AI §10]	No common DS vocabulary
Appearance/style	E [A]	E [C]	E, strongest dimension [F]	E [M]	E [S/OpenUI5]	E through args/stories [B]	Not equivalent to intent [AI/case studies]	DTCG types/tokens [Std]
Tone/impact/consequence	P [A]	P, e.g. danger [C]	E if property exists; local meaning [F]	P [M]	P [S]	E if documented API [B]	Value-name causality unestablished [AI §10]	MCP behavioral hints/ARIA states are adjacent [Std]
Aliases/replacements	P through migrations [A]	E in code/history for some assets [C]	P multiple mappings/labels [F]	P package deprecations [M]	P code deprecation [S]	P via names/paths, no general concept alias field [B]	Name alignment causal for tools/params [AI]	E concept/label mappings [Std/SKOS]

API, behaviour, state and composition

Potential information	Atlassian	Carbon	Figma	Microsoft/Fluent	SAP	Storybook	AI/LLM research	Standards
Property definition	E in typed code; semantic quality varies [A]	E in types/docs [C]	E property types/mappings [F]	E typed APIs [M]	E OpenUI5 metadata [S]	E prop extraction/JSDoc [B]	Parameter/key wording causal [AI §9]	Schema property annotations [Std]
Enum-value definition	P docs/code [A]	P docs/stories [C]	P mapping, description not inherent [F]	P docs [M]	P docs/code [S]	P only when authored [B]	Direct isolated evidence absent [AI §10]	Enums define legal symbols, not intent
Required/default/optional values	E typed code [A]	E types/stories [C]	P mapping/property metadata [F]	E typed APIs/schemas [M]	E OpenUI5 metadata [S]	E manifests [B]	Hard structure improves validity [AI §§14–16]	JSON Schema/type systems [Std]
Events/actions	E code/tests [A]	E code/tests [C]	P snippets/mappings [F]	E APIs/cards [M]	E OpenUI5 [S]	E prop/event metadata and stories [B]	Parameter filling adjacent [AI]	Native/ARIA behaviour constraints
Interaction behaviour	E code/tests/docs [A]	E code/tests/docs [C]	P inherited from mapping [F]	E code and guidance [M]	E conventional controls [S]	E for documented/tested stories [B]	Agent effect mostly untested	ARIA interaction semantics [Std]
Interaction/state values	E [A]	E [C]	E properties/variants when modeled [F]	E [M]	E [S]	E stories/args/types [B]	Legal value generation distinct from semantic choice [AI]	Role/state/property split [Std/ARIA]
State transitions/async lifecycle	P component-specific [A]	P, strong in AI Chat [C]	I from frames/mappings [F]	P agent guidance/components [M]	P control events [S]	P interaction stories [B]	Not directly established for DS contracts	State-machine/planning precedent adjacent
Parent/child/slot structure	E selected components [A]	E selected APIs/rules [C]	E nested instances/children/slots [F]	E component/card schemas [M]	E OpenUI5 aggregations; claimed composition layer [S]	E subcomponents/stories [B]	Agent benefit under-tested [AI §§15,20]	Structural schemas/type systems [Std]
Cross-property constraints	P code/types/prose [A]	P hard skill rules/types [C]	P variant restrictions [F]	P types/schemas [M]	P code; compositional rules unavailable [S]	P types/controls, not exhaustive [B]	Validity benefit and constraint tax demonstrated [AI §§15–17]	JSON Schema/feature models [Std]
Cross-component relationships	P slots/tiers [A]	P explicit selected pairings [C]	P nested mappings [F]	P compositions/cards [M]	E claimed, not inspectable [S]	P subcomponents/examples [B]	Selection benefit unestablished	SKOS relations/graph constraints adjacent [Std]
Invalid combinations/anti-patterns	P docs/context claims [A]	P prohibitions/guardrails [C]	P mapping restrictions/custom rules [F]	P guidance/types [M]	E claimed guardrails, unavailable [S]	P authored docs/tests [B]	Showing vs enforcing unresolved [AI §17]	JSON Schema/SHACL expressible [Std]

Accessibility, content, tokens and implementation

Potential information	Atlassian	Carbon	Figma	Microsoft/Fluent	SAP	Storybook	AI/LLM research	Standards
Accessibility role/requirements	E docs/code [A]	E docs/skill/code [C]	P inherited/custom [F]	E docs/code [M]	E conventional code; guardrails claimed [S]	P docs + addons/tests [B]	Direct selection benefit unestablished	E WAI-ARIA/native [Std]
Keyboard/focus/screen reader	E component-specific [A]	E component-specific [C]	I unless mapped/documented [F]	E guidance/code [M]	E conventional controls [S]	P testable when authored [B]	Direct agent evidence sparse	E ARIA/APG/platform [Std]
Content/label guidance	E Rovo/content docs [A]	E component content docs [C]	P text properties/custom rules [F]	E strongest agent-content guidance [M]	E human guidance [S]	P MDX/JSDoc [B]	Description effects adjacent, not UI-copy causality	Accessibility-name requirements [Std]
Localisation	E code resources [A]	E selected components [C]	I from design text [F]	E conventional packages/guidance [M]	E OpenUI5 [S]	I, source-dependent [B]	Not established for contract selection	Language-tag/label precedent [Std/SKOS]
Token identity/type/value	E tokens [A]	E token packages/MCP [C]	E variables/mappings [F]	E tokens/themes [M]	E theming/code [S]	P via MDX/docs, not intrinsic [B]	Naming effect on token selection unestablished	E DTCG explicit `$type` [Std]
Token semantic role/alias/reference	E semantic foundations [A]	E semantic tokens [C]	E when variables configured [F]	E semantic tokens [M]	P [S]	P source-dependent [B]	Direct LLM evidence absent	E DTCG reference/type precedent [Std]
Package/import/framework binding	E code [A]	E MCP/code [C]	E Code Connect [F]	E code [M]	E code [S]	E manifest [B]	Grounding/retrieval adjacent [AI]	OpenAPI/schema precedent
Examples/stories/snippets	E code/story assets [A]	E [C]	E snippets [F]	E [M]	E samples [S]	E core capability [B]	Examples can reduce parameter errors [AI/EASYTOOL]	Example annotations are optional
Source/tests/version/status	E repository [A]	E repository/MCP/history [C]	E mapping source/version [F]	E repository [M]	E repository; compositional layer N [S]	E paths/tests; preview status [B]	Optimisation must be version-specific [inferred]	Deprecation/version vocabularies vary

Retrieval, validation and evaluation

Potential information	Atlassian	Carbon	Figma	Microsoft/Fluent	SAP	Storybook	AI/LLM research	Standards
Machine retrieval mechanism	E documented, runtime incomplete [A]	E MCP/skill [C]	E MCP/search/context [F]	N Fluent-specific semantic layer [M]	P reportedly deployed [S]	E manifests/MCP [B]	Decision-local retrieval adjacent [AI §18]	MCP is delivery, not ontology
Exposure/context curation	P skills/files [A]	E routing/filters [C]	E selection/tool scopes [F]	P docs/schema surfaces [M]	N mechanism unavailable [S]	E manifest tags/toolsets [B]	Full-document dumping can be weaker [AI §18]	Access policy separate
Deterministic validation	P tests/types [A]	E tests/checklists/parsers [C]	E mapping parsers/CI [F]	E types/tests/schemas [M]	E OpenUI5; claimed generation validation [S]	E story tests/addons [B]	Validity gains direct; correctness may fall [AI §§16–17]	JSON Schema/SHACL/type systems
Semantic selection evaluation	P reported, method unavailable [A]	N public benchmark [C]	N [F]	N [M]	N public results [S]	N unless authored externally [B]	Tool selection direct; DS enum selection gap [AI]	No DS standard
Agent testing/eval results	P aggregate vendor claims [A]	N [C]	N semantic results [F]	N [M]	N public [S]	N general semantic results [B]	Multiple adjacent benchmarks [AI]	Not a standards function

This matrix is not a maturity ranking. It shows a recurring asymmetry: implementation truth is often explicit; selection and composition truth is either authored in prose, represented selectively, claimed but not inspectable, or absent from public evidence.

4. System-by-system findings

The profiles below own the detailed factual findings. This synthesis retains only the cross-system role each source plays and the central remaining inference gap.

System	Cross-system contribution	What remains implicit or unverified	Canonical profile
Atlassian	Documented connection among intent, composition, portable context, MCP and evaluation	Public schema, runtime payloads and evaluation protocol	Atlassian
Carbon	Strongest inspectable operational chain joining discovery, code/docs retrieval, selected rules and validation	System-wide selection schema and public semantic-selection evaluation	Carbon
Figma	Strong design/code identity, property mapping and selected-context delivery	Why a component is appropriate and broad composition fitness	Figma
Microsoft / Fluent	Mature typed implementation plus strong agent-behaviour, content and accessibility guidance	One connected Fluent component-selection context layer	Microsoft / Fluent
SAP	Strongest public articulation of role, intent, contextual fit and relationship logic	Inspectable compositional schema, retrieval, validators and results	SAP
Storybook	Strongest general component/docs/story/test serialization and retrieval	Mandatory selection semantics and exhaustive composition policy	Storybook

The broader naming sample demonstrates that systems structure properties differently; it does not show that one structure improves agent accuracy. The variant matrix and property-model matrix own that comparison.

5. AI research mapping to possible contract elements

Potential ingredient	Evidence classification	What the evidence supports	What remains unknown
Component name	Empirically supported for analogous tool/component selection	Names causally affect tool selection with descriptions fixed; noisy/opaque/conflicting names can hurt	design-system effect sizes and optimal wording
Property/parameter name	Empirically supported for parameters/schema keys; adjacent for DS props	Parameter names and schema-key wording can change identification/generation; direction varies by model family	`variant` vs `tone` vs `intent` with identical DS values/descriptions
Enum-value name	Unestablished directly	Tool naming, semantic anchors and enum-filling benchmarks make the mechanism plausible	aligned vs opaque vs misleading DS values under controlled conditions
Per-value description	Plausible hypothesis / adjacent	Descriptions and documentation affect tool use and parameter adherence	whether descriptions override misleading enum names and which format works best
Purpose and when/avoid boundaries	Adjacent AI evidence + standards/industry supported	concise, collision-focused documentation and relevance examples help related routing tasks; mature systems author boundaries	structured fields vs equivalent prose and the minimum sufficient boundary packet
Types and finite choices	Empirically supported for validity	enforced shape/enums reduce structural inventions	selection of the semantically correct legal value
Structural/cross-field constraints	Standards/industry supported; mixed adjacent AI evidence	many formalisms can express rules; hard constraints improve validity	whether displaying rules improves selection; constraint tax and optimal timing
Deterministic validation	Standards/industry supported; AI validity evidence	detects illegal outputs independently of model obedience	repair strategy and semantic validation of legal outputs
Examples	Adjacent empirical support	concise documentation plus an example can reduce parameter errors	coverage, counterexample benefit and transfer to DS decisions
Counterexamples / no-match	Adjacent	relevance/abstention work supports negative evidence in related tasks	isolated DS value-selection effect
Relationships/composition	Standards/industry supported	systems represent slots, subcomponents, mappings and relationship concepts	direct agent performance benefit and a suitable scope
Stable IDs/aliases	Standards/industry supported; naming evidence adjacent	concept/label separation supports evolution; names are model signals	whether aliases improve retrieval without increasing candidate interference
Accessibility semantics	Standards/industry supported	roles, states and properties are explicit and enforceable in platform semantics	incremental agent performance from inclusion in a component packet
Content/localisation	Industry supported	clear labels and content rules carry intent and accessibility	how much content compensates for ambiguous component metadata
Token types/semantic roles	Standards/industry supported	DTCG explicitly rejects inference of type from arbitrary grouping/value	direct token-selection and composition benefit for agents
Implementation binding	Industry implemented; adjacent grounding evidence	Figma, Carbon and Storybook connect abstract assets to real code/imports/examples	effect on semantic component selection rather than implementation fidelity
Version/provenance/deprecation	Industry supported; plausible hypothesis for AI	prevents silent use of stale or incompatible artifacts	measured contribution to agent success
Retrieval packet/curation	Adjacent empirical support	relevant schema/document slices can outperform noisy full context; fields contribute unequally	optimal DS retrieval unit and ordering
Agent evaluation results	Required by the working AI-optimised definition, not a readiness ingredient	measures whether a given contract/harness works	benchmark design, thresholds and generalisation

The strongest convergence is independent rather than causal: mature systems and standards repeatedly separate identity, description, type, state, relationship and implementation; AI research independently shows that names, descriptions, schema wording, context selection and constraint delivery affect related model tasks. The convergence justifies evaluation. It does not establish a particular contract architecture.

6. Recurring contract patterns

Frequency below describes the six primary systems, not industry prevalence.

Pattern	Observed frequency	Evidence type	Qualification
Typed component API with finite values/defaults	5/5 component systems; Figma maps them	Implemented	strongest for legality, not intent
Source/import/package identity	5/5 component systems; Figma mapping	Implemented	cross-artifact identity is less complete
Usage examples/stories/samples	5/5 component systems plus Figma snippets	Implemented	examples are not exhaustive rules
Human-readable purpose/usage guidance	5/5 systems plus Figma custom rules	Documented/conditional	quality and machine delivery vary
Accessibility semantics/guidance	5/5 systems; Figma inherits when mapped	Implemented/documented	generated compositions remain a gap
Tokens/variables with semantic naming	Atlassian, Carbon, Fluent, OpenUI5, Figma	Implemented	direct agent-selection evidence absent
Local composition through children/slots/subcomponents	all primary systems in some form	Implemented/documented	broad intent-driven composition is not established
Version/deprecation/history	component repositories and mappings	Implemented, uneven linkage	rarely one canonical lifecycle record
Machine retrieval of component information	Carbon, Figma, Storybook implemented; Atlassian/SAP documented	Emerging	Microsoft corpus lacks equivalent public layer
Explicit selection/prohibition rules for agents	Carbon partial; Atlassian/SAP documented; Storybook/Figma conditional	Emerging	no common schema or coverage bar
Agent-facing validation loop	Storybook/Carbon/Figma implementation checks; Atlassian/SAP claims	Emerging	semantic correctness evaluation sparse

Recurrence indicates shared pressure, not a mandatory field list.

7. Major tensions and contradictions

Distributed truth versus unified contract. Existing systems gain authority from code, docs, design and tests, but an agent may see only one. Unification reduces fragmentation but risks creating a stale duplicate source.
Rich prose versus typed metadata. Prose currently carries the richest selection judgment; types carry the strongest legal enforcement. Neither substitutes for the other.
Generic properties versus narrow axes. variant, appearance and kind enable concise APIs but often mix dimensions. Narrow properties are clearer but expand the schema and valid-combination problem.
Mixed values versus factorized values. GitLab/Shopify/Spectrum demonstrate separation; Carbon/Atlassian/Primer demonstrate mixed namespaces. There is no direct AI comparison.
Agent-selected presentation versus policy-resolved presentation. Product intent may map to presentation through context-specific policy rather than exposing every business meaning as a component prop.
Flat component APIs versus compositional APIs. Storybook and Code Connect excel locally; SAP and Atlassian argue for relationship/context layers. General composition may over-centralize product judgment.
Generation-time constraints versus post-generation validation. SAP emphasizes generation guardrails; Storybook emphasizes executable tests; the constraint-tax evidence warns that hard constraints can increase wrong-but-valid outputs.
Full documentation versus minimum sufficient context. More material increases coverage but can introduce candidate interference, stale conflicts and context cost. Carbon’s targeted protocol and Storybook curation suggest selective delivery.
Authored versus generated metadata. Extraction keeps APIs current but cannot create missing intent; authored semantics can express intent but drift.
Global vocabulary versus product-local meaning. Central semantics improve consistency; Atlassian’s app tier and SAP’s contextual fit acknowledge legitimate local variation.
Examples versus grammar. Stories/templates preserve known good states; constraints describe legality; neither alone proves product fitness.
Human/model alignment versus stable public APIs. Naming or schema wording effects may not transfer across model families, while public renaming also imposes migration cost. Stable IDs and aliases are an adjacent option, not an established remedy.

8. Potential AI-readiness dimensions

These dimensions are provisional analytical categories, not requirements.

Dimension	Information represented	Corpus evidence	AI relevance evidence	Unknown
Canonical identity	stable concept, source, package, version and artifact links	Carbon, Storybook, Code Connect strongest	tool/API-method naming direct in tested tasks; DS component transfer and retrieval implications adjacent	required granularity and cross-layer authority
Selection semantics	purpose, when/avoid, alternatives, no-match	Carbon rules; Atlassian/SAP claims; Storybook conditional	documentation/relevance adjacent	minimum boundary form and coverage
Semantic axis clarity	what a property/value denotes: hierarchy, appearance, role, tone, state	cross-system naming matrices	parameter/key evidence; enum evidence gap	whether factorization improves DS decisions
Legal API shape	props, types, finite values, defaults and events	all code systems; Storybook serialization	strong validity evidence	semantic value choice
Behaviour/state model	action, navigation, state and lifecycle behavior	code/tests/docs; ARIA precedent	mostly industry/standards	which behavior must be surfaced at selection time
Composition/relationships	parents, children, slots, peers, targets, incompatibilities	local implementations; SAP/Atlassian direction	unestablished directly	scalable representation without freezing judgment
Accessibility/content	roles, labels, focus, keyboard, copy, localisation	mature system practice	standards/industry supported	contribution to agent choice and dynamic composition
Token realization	typed semantic tokens, aliases and mappings	all foundation systems/Figma	standards supported, AI direct gap	how much belongs in selection packet
Implementation traceability	design-to-code mapping, imports, examples and tests	Figma, Carbon, Storybook strongest	adjacent grounding evidence	semantic versus implementation benefit
Constraint/checkability	rules that can be enforced or deterministically tested	types, schemas, skill rules, tests	validity evidence plus constraint tax	timing and semantic validator design
Context delivery	retrieval trigger, projection, curation, freshness	Carbon, Storybook, Figma; Atlassian/SAP claims	adjacent RAG/tool-retrieval evidence	smallest decision-complete packet
Uncertainty handling	no-match, clarification, escalation and provenance	partial in guidance	relevance/abstention adjacent	readiness threshold and policy ownership

Minimum sufficient contract tension

The evidence argues against equating readiness with maximum metadata:

EASYTOOL in the new synthesis reports better outcomes with concise normalized instructions and substantially fewer tokens.
Retrieval studies summarized there suggest focused schema rows/fields can outperform full-schema dumping.
Storybook deliberately excludes human-only stories from manifests.
Carbon prescribes small targeted queries and stopping once relevant accessibility headings are covered.
Duplicated semantics across code, docs and a sidecar can conflict or become stale.
In Constraint Tax’s tested small models, hard schemas raised validity while lowering semantic or executable accuracy; this is not a universal model-size law.

The plausible target is therefore decision-sufficient and source-linked, not “all documentation in structured form.” What constitutes sufficient remains an evaluation question.

9. Potential AI-optimisation measures

The research suggests that optimisation would need multiple measures rather than one aggregate “accuracy” score:

correct component selection;
correct no-match, abstention or clarification;
correct property interpretation;
correct enum/concept selection;
schema/API validity;
semantic correctness among valid outputs;
prohibited/invalid combination rate;
correct local composition and relationship use;
correct behaviour/state implementation;
accessibility-role, label, keyboard and focus correctness;
content-rule and localisation compliance;
correct token family and avoidance of raw/invented values;
correct implementation binding/import/framework;
unnecessary custom-component rate;
invented component/property/value rate;
rationale alignment with the governing source;
confidence calibration and high-confidence error rate;
consistency across repetitions and prompt paraphrases;
robustness to option order, aliases, renaming and name–description conflict;
robustness across model families, sizes and harnesses;
retrieval recall of the governing rule and closest alternative;
context/token cost, latency and tool-call count;
repair success after deterministic validation feedback;
stability across component/design-system/model versions.

These are candidate capabilities to measure, not an evaluation framework. Visual similarity alone is insufficient, and schema validity must remain separate from semantic correctness.

10. Evidence gaps

Gaps in design-system practice

No shared public model for selection intent, alternatives, prohibitions and compositional relationships.
Selection semantics are rarely mandatory in component tooling.
Cross-artifact concept identity and version linkage are incomplete.
Product-local policy and shared-system semantics are not cleanly bounded.
Few systems expose machine-readable invalid combinations beyond local types/slots.
Semantic evaluation results are rarely public.

Gaps in public documentation and inspectability

Atlassian’s schema files, runtime payloads and evaluation protocol are unavailable.
SAP’s compositional metadata, relationship vocabulary, retrieval and enforcement are unavailable.
Figma public mappings show correspondence but not a mandatory intent model.
Storybook’s manifests are preview, React-only in the preserved evidence and schema-unstable.
Carbon’s operational rules cover selected cases rather than the entire library.
Microsoft exposes strong guidance and APIs but not a connected Fluent decision-context layer.
Public Figma library schemas and code APIs cannot always be audited at the same version.

Gaps in direct LLM evidence

Enum-value names have not been isolated with property, descriptions, behavior, tasks and available values fixed.
Per-value description override of misleading names is untested.
Design-system property names have not been compared with identical values/descriptions.
Structured useWhen/avoidWhen fields have not been compared with information-matched prose.
Relationship and composition metadata have not been causally tested for DS agents.
In-prompt constraints versus post-generation validation lack DS-specific comparison.
Accessibility, content and token semantics lack direct component-selection evidence.
Retrieval packet size/order and negative-guidance retrieval remain adjacent hypotheses.
Model-family and model-version effects prevent a universal wording conclusion.

11. Questions the next phase must answer

What exact decisions will “AI-ready” cover: discovery, selection, configuration, composition, implementation or all of them?
What is the minimum explicit information needed for each decision, and what can remain in surrounding product context?
Which source owns each fact, and how are derived representations kept synchronized and versioned?
What should a component expose directly versus what should a pattern, composition, product policy or retrieval service supply?
How should an agent distinguish governed ambiguity from missing documentation and respond with no-match or clarification?
Do semantic property and enum names improve selection when descriptions are fixed?
Can concise descriptions and decision boundaries compensate for conventional or locally conflicting names?
Do factorized semantic axes improve decisions enough to offset schema length and invalid-combination risk?
Which constraints should guide generation, which should deterministically validate, and which require runtime/product policy?
What is the smallest decision-complete retrieval packet, including closest alternatives and applicable constraints?
How should identity, aliases, versions, deprecations and Figma/code/docs mappings be linked without creating a second stale source of truth?
Which accessibility and content facts must be present before selection versus inherited from the canonical implementation?
What gold policy and metrics distinguish semantic correctness from structural validity and visual fidelity?
What threshold, model set, task distribution and expiration policy would justify the label “AI-optimised”?
What evidence would falsify the need for richer contracts—for example, descriptions eliminating name effects or retrieval dominating metadata structure?

12. Sources

Primary synthesis and earlier analysis

System evidence

Empirical and standards references

The primary synthesis contains the provenance, correction log and evidence classifications for PA-Tool, RoTBench, Hood, Hammer, schema-key wording, ACEBench, IFEval-FC, EASYTOOL, Constraint Tax, JSONSchemaBench and adjacent retrieval work. Claims in this analysis inherit those limits; items marked “re-verify” there have not been promoted here.

Analytical conclusion

The public corpus supports a precise but limited claim: mature systems already encode many potential ingredients of an AI-ready component contract, but they encode them in different artifacts and for different jobs. Identity and implementation are comparatively explicit, making many components AI-exposed for particular access paths. Selection boundaries, cross-component relationships, contextual fit and semantic evaluation remain fragmented, conditional or privately implemented, so exposure cannot be promoted to readiness for those capabilities.

The LLM research independently supports the relevance of names, descriptions, schema keys, context selection and validation, while leaving the closest design-system question—enum-value selection under controlled naming and description conditions—unanswered. Standards demonstrate that identity, labels, types, states, relationships and constraints can be represented separately; they do not demonstrate that any particular representation improves agent performance.

The working AI-ready definition therefore identifies the right problem but is not yet operational enough to serve as a certification state. The working AI-optimised definition identifies the right empirical transition but requires capability-specific measures, model/harness/version scope and explicit treatment of semantic correctness, abstention and robustness.

The next phase can defensibly explore candidate contracts only if it treats them as alternative hypotheses over this evidence map, preserves source authority across distributed artifacts and evaluates the minimum sufficient information rather than assuming that more metadata is better.

Personal Research

Explorer

ai-ready-component-contract-research