A component spec file — one machine-readable file holding props, variants, states, token bindings, and usage rules — turns prose documentation that an agent must interpret into a contract it can parse and validate against.
That sentence is the whole argument of this post. Everything below unpacks it: what prose docs look like to an agent, what the spec file actually contains, where the data to build one already lives in your toolchain, and where the honest gaps remain.
What an agent can’t perceive in prose docs
Start with the perception question, because it frames everything else. When an agent reads your documentation site, it is reading natural language. A paragraph that says “the Button accepts a size of small, medium, or large, and a disabled flag” is unambiguous to a human who already knows the system. To an agent, it is a passage of prose from which props must be extracted by inference — with no schema to check the extraction against, no enumeration to confirm it is complete, and no constraint that stops the agent from inventing a plausible-sounding fourth option.
This is not a claim that prose documentation is bad. Prose is excellent for the humans on your team. The problem is a mismatch of medium. Prose carries intent; it does not carry structure. An agent asked to generate a component instance from prose must do three things in sequence: read the words, guess the shape of the data, and hope the guess matches your code. At no point does anything validate that guess.
The fix, in the framing this post argues for, is a contract layer: an artifact that sits between the design system and the agent, expressed in a form the agent can treat as authoritative rather than suggestive. The phrase “component contracts” also appears in blog posts; the framing below is this post’s own and rests on the primary documentation linked here.
Contrast the two approaches directly:
| Dimension | Prose documentation | Component spec file |
|---|---|---|
| Machine-readability | Natural language; agent must interpret | Structured, parseable data the agent can validate against |
| Prop constraints | Described in words; no enforced bounds | Values constrained (as Storybook argTypes constrain accepted values) |
| Tool-to-tool exchange | None; docs live outside the toolchain | DTCG token format designed for exchange between tools |
| Link to actual code | Indirect; agent infers the mapping | Direct references to real code (Code Connect’s stated purpose for MCP guidance) |
| Source of truth | Hand-maintained unless generated from code | Derivable from existing artifacts (argTypes inference, Code Connect mappings) |
| Variants & states | Prose lists; agent may miss or invent them | Enumerated in one file alongside props |
What a component spec file is
A component spec file is a single file that consolidates five things about one component: its props, its variants, its states, its token bindings, and its usage rules. The format is negotiable — YAML, JSON, or a TypeScript object all work — because what matters is that the shape is machine-readable and that an agent can load it in one read.
Here is an illustrative example for a Button. This is a construct written for this post, not a file from a shipped design system:
# button.spec.yaml — illustrative only
component: Button
props:
size:
type: enum
values: [sm, md, lg]
default: md
control: radio
description: Visual density of the button.
disabled:
type: boolean
default: false
text:
type: string
required: true
variants: [primary, secondary, ghost]
states: [default, hover, focus, active, disabled, loading]
tokens:
background: color.action.primary
foreground: color.action.on-primary
radius: radius.md
usage:
- One primary Button per view.
- Disabled must not be the only signal of an unavailable action.
- Loading state preserves the button's width.Notice what has changed relative to prose. The enumeration of sizes is closed — values: [sm, md, lg] is a list, not a sentence. The states are declared as a set, so a validator can flag a missing or invented state. The token bindings name your actual tokens rather than describing a color. And the usage rules, the one genuinely prose-like section, are at least enumerated as discrete, quotable constraints rather than buried mid-paragraph.
Prose vs. spec, dimension by dimension
The comparison table is an analytical construct drawn from the sources below, not a measured comparison. Machine-readability is the load-bearing row: everything else — constraint, exchange, code linkage, drift resistance, completeness of variants — follows from whether the artifact is data or text.
The three sources you already have
Most design systems can produce much of this file without writing it from scratch. The question is which tools they already have: three artifacts that exist in a mature system, with no new platform.
Storybook argTypes
Storybook’s Args are JSON-serializable objects — string keys with valid value types — passed into a component, definable at story, component, or global level, where component-level args apply to all stories unless a story overrides them. JSON-serializable is the operative phrase: that is exactly the property a spec file needs.
ArgTypes go further, describing the metadata around those values. Storybook infers argTypes from the component via static analysis — react-docgen by default for React, react-docgen-typescript as an alternative, vue-docgen-api for Vue, custom-element.json for Web Components, and compodoc for Angular under Webpack. ArgTypes constrain the values a prop can accept, and carry a description plus a control type — for example control: radio with a set of options, which is where variant enumeration comes from. Manually specified argTypes override the inferred ones, so you can correct anything the parser got wrong. One deprecated detail to avoid: defaultValue inside argTypes is deprecated, and the docs say to define the value in args instead.
Figma Code Connect mappings
Figma Code Connect connects components in a repository to components in Figma design files. Its stated purpose is worth quoting closely: it enhances the Figma MCP server’s ability to guide AI agents with more precise implementation details by giving them direct references to actual code. That is the “link to actual code” row of the table above, straight from the documentation.
There are two surfaces. Code Connect template files are TypeScript files named *.figma.ts that you write and publish with the CLI (see the template-file docs and the quickstart guide); the Code Connect UI is a GitHub integration supporting one-to-many mapping. The template example maps Figma properties — a Size enum, a Disabled boolean, a Text Content string — directly onto JSX props, which is precisely the mapping a spec file needs to record.
Plan limits matter if you are scoping this: Professional plans can have one active framework, Organization and Enterprise plans can have multiple, and connections for a deactivated framework show a Deactivated badge in Dev Mode and are not returned by the MCP server.
DTCG design tokens
The DTCG Format Module 2025.10 is a Final Community Group Report dated 28 October 2025, describing a file format to exchange design tokens between tools. Important caveat, and the docs say so themselves: this is a Community Group report, not a W3C Standard, and not on the Standards Track. Treat it as a stable, documented Community Group specification with a defined status, not as a web standard. Its development happens in the community-group repository.
For the spec file, that exchange purpose is the relevant property. The token bindings section of your spec can simply reference tokens expressed in the DTCG format, and any tool that reads that format can resolve them.
Assembling the spec from the three sources
The assembly is mostly transcription:
- Props and variants come from Storybook. Read the argTypes for the prop names, types, control types, and constrained value sets; read Args for defaults. Variant options often fall out of an argTypes entry with
control: radioand an explicitoptionsarray. States are not covered by the argTypes or Args sources cited here, so declare them yourself as a closed set, as the illustrative example does. - Code mappings come from Code Connect. The
*.figma.tstemplate entries tell you which Figma property maps to which JSX prop — carry those into the spec as an explicitfigma:block so an agent jumping from a design file to code has a direct line. - Token bindings come from your DTCG-format token files. Resolve each visual property to a token name rather than a hardcoded value, keeping the Community Group report status in mind as you document the choice.
One limit has to be stated alongside the recipe: spec quality is bounded by Storybook’s framework-dependent inference. A spec built from argTypes is only as good as the component’s TypeScript types. If a prop is typed as plain string where it should be a union of three literals, inference has nothing to narrow, and your spec will inherit the looseness. This is exactly where the manual override path earns its keep — hand-written argTypes tighten what inference left loose.
How the agent consumes the contract
On the consumption side, the Figma MCP server gives AI agents design context to generate code from Figma files, and can extract design context — variables, components, and layout data — into the IDE. With Code Connect in place, that context also includes direct references to actual code.
The spec file slots in as the local, system-authored half of that exchange. The MCP server brings design-file context; the spec brings your design system’s constraints. Together, an agent working in the IDE has both what the designer drew and what the system permits.
For completeness of context: the MCP server also offers a write-to-canvas feature. It requires the remote server and a Full seat to write outside your drafts, is free during the beta, and will eventually become a usage-based paid feature. That is background, not a recommendation.
What we don’t know yet
No measured benchmark exists showing that agents hallucinate fewer props when given a component spec file. This is a hypothesis to test, not a result.
The mechanism is sound on paper — closed enums, declared states, and direct code references are harder to misread than paragraphs — and that is a reason to try it. It is not evidence that it works. Anything you read, including in this post, that suggests an agent will produce fewer invented props with a spec file is describing an expectation. The honest position is that the mechanism is grounded and the outcome is unmeasured.
Two further unknowns belong here. First, we do not know how much of the benefit survives when inference is weak: a spec assembled from loose TypeScript types inherits that looseness, and no one has measured the downstream effect. Second, we do not know how agents weight a spec file against other context in the window — a question that only an experiment on your own system can answer.
FAQ
Is the DTCG token format a web standard? No. The DTCG Format Module 2025.10 is a Final Community Group Report dated 28 October 2025. The document states it is not a W3C Standard and not on the Standards Track. It remains a usable, documented file format for exchanging design tokens between tools — just describe its status accurately.
Should I hand-write argTypes or rely on inference?
Inference is the cheaper starting point, and Storybook’s static analysis covers React, Vue, Web Components, and Angular. But manually specified argTypes override inferred values, so hand-writing is the correction mechanism for anything inference gets wrong. In practice: infer first, then hand-write to tighten. Also remember that defaultValue in argTypes is deprecated — put defaults in args.
Does Code Connect work on every Figma plan? Code Connect has plan limits: Professional plans can have one active framework, while Organization and Enterprise plans can have multiple. Connections belonging to a deactivated framework are not returned by the MCP server, so those mappings drop out of agent context. Dev Mode shows them with a Deactivated badge.
Will a spec file stop my agent from hallucinating props? No measured data exists on that. Treat it as a hypothesis to test: build the file, run a representative set of generation tasks with and without it, and compare. Do not assume the outcome in advance.
The Bottom Line
Spec files are a pragmatic, buildable contract layer assembled from artifacts most mature systems already have: Storybook argTypes and args, Figma Code Connect mappings, and DTCG-format design tokens. No new platform is required.
The benefit to agents is plausible and mechanistically grounded — parseable constraints, closed enumerations, direct references to real code, an exchange format for tokens. It is also unmeasured. So the recommendation is two steps, in order: build the file, then run the test. The first step is engineering you can do this quarter; the second is the only way anyone learns whether the contract layer earns its name.
How This Guide Was Built
This guide is based on official specifications and vendor documentation: the DTCG Format Module 2025.10 report, Storybook’s Args and ArgTypes documentation, and Figma’s Code Connect and MCP server documentation, all fetched 2026-10-18.
No hands-on testing of any live design system was performed. No benchmark of agent output was run. The hallucination-reduction claim is a hypothesis to test. The comparison table and the example spec are analytical constructs drawn from these sources, not measured results. Claims framed as expectations are labeled as such throughout.