Machine readability
Type: Finding
Status: Active
Canonical for: How existing artifacts expose identity, APIs, examples, semantics and retrieval surfaces to agents
Depends on: System profiles and the canonical AI-exposed definition
Machine readability is not binary. Mechanisms differ in whether they expose existence, syntax, design intent or enforceable relationships.
The canonical term AI-exposed describes the access-focused condition in this evidence: an agent can reliably discover, retrieve and inspect current governed design or implementation artifacts through a stated access path, while still having to infer some governed meaning. Machine readability can enable AI-exposure, but it does not by itself establish AI-readiness for selection, configuration or composition. See canonical terminology.
| Mechanism | Exists | API | Visual intent | Semantic intent | Usage rules | A11y | Composition rules | Machine discoverable |
|---|---|---|---|---|---|---|---|---|
| Design tokens | — | Partial | Strong | Partial when semantic | Weak | Partial | Weak | Strong |
| Component source / TypeScript | Strong | Strong | Partial | Weak–partial | Weak | Behavior partial | Parent/child partial | Strong |
| JSON schema / typed response schema | Strong | Strong | Partial | Partial | Partial | Weak unless authored | Structural | Strong |
| Storybook CSF/ArgTypes | Strong | Strong | Strong examples | Partial | Partial | Testable | Example-based | Strong |
| Storybook manifests | Strong | Strong | Via snippets/stories | Description-dependent | JSDoc/MDX-dependent | Docs-dependent | Subcomponents/examples | Strong |
| Human documentation | Strong | Variable | Strong | Strongest current source | Strong | Strong | Often narrative | Weak without extraction |
| Code Connect | Strong | Strong mapping | Strong | Weak–partial | Custom instructions | Inherited from code | Slots/variants partial | Strong |
| Figma metadata/MCP | Strong | Design properties | Strong | Weak–partial | Custom rules | Weak unless encoded | Node hierarchy, not judgment | Strong |
| DS-specific MCP | Tool-dependent | Strong retrieval | Source-dependent | Source-dependent | Strong if curated | Source-dependent | Source-dependent | Strong |
| Agent instructions / skills | — | — | Partial | Strong authored intent | Strong | Can be explicit | Can be explicit | Strong but client-dependent |
| Structured examples/templates | Strong | Strong | Strong | Partial–strong | Implicit in examples | Testable | Strong for known cases | Strong |
| Composition relationship model | Strong | Potentially | Partial | Strong | Strong | Can constrain | Strong | Experimental |
What is easy for agents to retrieve now
Across Carbon, Fluent, ADS, OpenUI5, Code Connect and Storybook:
- Component names and source/import paths.
- Props, types, required/default values and many variants.
- Token names and values.
- Concrete stories, snippets and rendered examples.
- Figma node hierarchy, variables and screenshots.
- Explicit design-to-code mappings.
- MDX/documentation text when exposed through manifests or MCP.
- Tests and known story states.
This is a major improvement over relying on model training or visual imitation.
What remains implicit
- When to choose one plausible component over another.
- Information hierarchy and task priority.
- Which components belong together outside documented examples.
- Contextual density and responsive tradeoffs.
- Product/domain intent and business criticality.
- Content expectations beyond generic voice/tone.
- Accessibility rationale and coverage gaps.
- Anti-patterns and invalid combinations unless deliberately authored.
- Whether a generated composition is coherent, not merely valid.
- How risk changes approval, interruption or explanation.
Core finding
Existing machinery is strongest at inventory and syntax. Good design requires selection and composition semantics. Types prevent a nonexistent prop; they do not prevent the wrong component. Tokens prevent an invented color; they do not create hierarchy. A screenshot preserves appearance; it does not preserve intent.
Carbon Builder demonstrates an inspectable operational layer: targeted code/documentation retrieval, explicit selection and composition rules, accessibility requirements and validation checklists. Its structured result fields strongly represent implementation identity, while much of its design judgment remains prose in a skill rather than a general semantic schema. Storybook demonstrates that descriptions and JSDoc can add selection semantics. Figma demonstrates that custom rules can add codebase intent. Atlassian proposes structured context files/skills. SAP goes furthest conceptually by naming functional role, supported intent, contextual fit and relationship logic. Atlassian and SAP remain less publicly inspectable at the semantic-schema level.
MCP’s actual role
MCP is a retrieval/tool protocol, not a design ontology. It can expose components, tokens, documentation, mappings and tests. The quality of agent behavior still depends on:
- what information the server contains;
- how current and curated it is;
- what the client retrieves;
- what instructions constrain use;
- what tests or reviews validate output.
The industry is converging on MCP as a delivery mechanism, not on a shared semantic model.