Component.md
Design systems were built for humans. The readers changed.
A design system is the set of rules, behaviors, and relationships that govern how a design language expresses itself. Components are one expression of that language, on one surface, at one moment. For the past decade the field has used “design system” and “component library” as if they meant the same thing. They never did. The conflation worked when the reader of the artifact was a human engineer who could fill in what the file didn’t say. It stops working the moment the reader is a tool.
For the past year I’ve been testing AI tools on my Figma files. Figma Make, Claude Code, Lovable. Last week Claude Design shipped, and I was excited to try it.
The design never comes back looking the way I designed it. It’s close. But never right. The optical alignment is off. The font is wrong. The spacing between elements is a few pixels off. The details that make a component unique were guessed at: micro-interactions, behaviors, and specific token assignments.
This is what happens when a design is handed to a tool without a spec. A Figma file is full of information. A tool working from information alone has to guess at everything the file doesn’t say.
This is not a Claude Design problem. It’s every tool in the category, and the problem is upstream of the model. That gap is the line between a toy and a tool you can ship with.
LLMs are good at the high-level shape. They miss the last mile, the part that makes a component yours, the part a screenshot and a prompt can’t carry. Figuring out what went wrong and repairing it costs more time and tokens than building it did.
I build and maintain design languages and component libraries that hundreds of engineers and designers ship against every day. The gaps I’m about to describe aren’t a thought experiment. They’re what broke this week, and what I had to fix. Closing them is the job.
How good these tools get is being decided on the design system side of the handoff, not the model side.
The workarounds are already everywhere. We paste screenshots into prompts. We run MCP servers that scrape Figma frames and hope the tool stitches them back into something coherent. They exist because the Figma file was never meant to be the thing a tool reads from. It was meant to be read by a human who could fill in the gaps. The reader changed.
Why this keeps happening
Something has quietly changed about what a designer’s output is. Not long ago, the deliverable was a frame. A human on the other side, usually an engineer, would read it, interpret it, fill in the gaps, and ship code. That interpretation layer was understood, budgeted for, part of the job.
That interpretation layer is now a tool. When a designer hands a component to Claude Design or Figma Make, there’s no human translator in the middle anymore. The tool reads the artifact directly and produces code. Most design systems haven’t caught up to that yet. We’re still shipping frames to a reader that needs a spec.
The source of truth for a component today is scattered: part in the Figma file, part in the designer’s head, the rest in Slack threads and code review. Most design teams don’t think of this as a source of truth problem. That is what it is.
Figma is a source of information, not the source of truth.
It is a good place to figure out what a component should be: to move pixels cheaply, test variants, and socialize ideas. It tells the tool a lot: dimensions, colors, variants, the layer tree. It doesn’t tell it which token governs which state, how focus moves, or what the component announces to a screen reader. A tool reading the file gets the look and guesses at the rest. That is where the guessing starts.
What has to be true
Two things have to be true for any of this to work. The component has to become the artifact, not a picture of one.
Components have to answer for themselves. The old model was static documentation read the same way by everyone and interpreted individually. The new model is interactive documentation that reshapes around whoever is reading it. Same file, different readers, different answers.
Components have to be buildable. Any LLM should be able to read a component and produce a faithful implementation on any platform. No guessing at intent, because the tool is reading a spec instead of interpreting a rendering.
This is the shift. A system where every component can be queried, reasoned about, and built from, by humans and by LLMs, without a human translator in the middle of every handoff.
Component.md
Component.md is the artifact that makes both true at once. One markdown file per component. Platform-agnostic. Meant to be the source of truth the Figma file was never intended to be. A repository of the knowledge a component needs to be built on any platform.
The schema is as follows:
API spec: properties, sub-components, configuration examples
Structural spec: dimensions, spacing, how values change across density, size, and shape
Color assignment: the tokens that govern each element in each state
Voice / screen-reader spec: focus order, announcements, platform differences (VoiceOver, TalkBack, ARIA)
Behavioral spec: dismiss rules, error states, empty states
Beyond the schema, the file flexes to the component. Motion specs. Decision trees for when to use which variant. Counter-examples for how the component is not supposed to be used. Migration notes. The schema is the contract. What fills it is the component.
Here’s what an error state looks like in practice. The color spec and the screen-reader spec sit in the same file, owned by the same component, shipped together.
# Text field
## When validationState === 'error'
### Color
| Element | Token |
|------------------|--------------------------|
| Container stroke | error-border-accessible |
| Hint icon | error-content-primary |
| Hint text | error-content-primary |
### Voice (ARIA)
| Property | Value |
|------------------|-------------|
| aria-invalid | true |
| aria-errormessage| error-id |
| hint node role | alert |
Implement together, or the component ships half-broken.It sits alongside the Figma file, not in place of it. Figma stays where it’s strongest. The .md holds the decisions once they’re made.
Because it’s markdown, any LLM can read it. It can be exposed through MCP. You can hand it to Claude Design, Claude Code, Figma Make, or whatever ships next, and get back an implementation that matches intent on whatever platform you’re targeting.
Humans read it too. A designer or engineer queries it when they need an answer.
A feature designer building a checkout flow asks: what’s the order of actions in a stacked button group?
An engineer reviewing a PR hits a different question: can I mix button sizes in a stacked group?
Static documentation sites were built around the assumption that the reader was a human with twenty minutes and the context to interpret a page. That assumption no longer holds. The reader is sometimes a tool with no context, and often a feature designer or engineer who has a question and needs an answer, not a page to scan. A spec a person can query is the same spec a tool can build from.
The spec is the interface. Anyone, or anything, can query it.
How it works
Two stages: deterministic extraction, agentic creation.
Extraction runs through the uSpec Figma plugin. It walks you through the sub-components of the thing you’re speccing and asks which ones need their own specs and which are decorative. A textfield has a label, an input, and hint text. Each of those might be spec-worthy on its own, or it might be along for the ride. You decide. What comes out the other side is a set of JSON files that capture what the component actually is.
By the time creation starts, the bulk of the work is already done. The plugin has pulled everything the Figma file has to tell us: layout, variants, tokens, the layer tree, the lot. What’s left is interpretation.
Creation runs through a new skill: create-component-md. It hands the extracted data off to a set of specialist agents, each one reasoning about a different slice of what came out of Figma: one for structure, one for color, one for screen reader behavior. They run in parallel. None of them need to wait on each other to do their job.
Then, and only then, the outputs are converged and reasoned into a single component.md file. A reconciliation step catches any gaps and re-runs the specialist that owns them.
The same textfield, three ways: the Figma file a tool reads today, what a tool ships from that file alone, and what it ships with component.md in the mix. The delta is the difference between close and right, made visible.
Why the split matters
A script can pull numbers out of any Figma file, clean or messy. It can't tell you what those numbers mean. That's the gap. How a component is built in Figma is rarely how it's built in code. Real files have inconsistent naming, workarounds built against Figma's constraints, and structural patterns that carry semantic meaning the layer tree cannot express.
A common case: a list item with a boolean that toggles leading content. When the boolean is on, the designer can pick image, icon, or text.
Programmatically, Figma reads this as
leadingContent: true,
subcomponent: icon In engineering, it’s one enum:
leadingContent: "icon" | "image" | "text" | "none". Mechanical extraction gives you the first. Getting to the second is interpretation.
Extraction without reasoning is a data dump. Reasoning without extraction is a hallucination.
Pulling numbers out of a Figma file doesn’t need a model to reason about them. It needs a script, and scripts are free.
Reasoning only kicks in where reasoning actually matters: interpreting what those numbers mean. The LLM never does work a script can do for free, and it never has to hold the raw dump in its context window while trying to think. The result is a spec that comes back faster and cheaper, and a model that can think where thinking matters.
What changes when components can answer
The audience of the design system has doubled. For the past decade, we built it for the humans who use it. Now we build it for humans and the tools those humans reach for. That second audience is growing fast, and its standards are different: it needs the decisions written down, not implied.
The team stops being the bottleneck. Questions get answered without anyone on the design systems team having to be online. What’s left is the work that moves the system forward.
Are design tools dead?
I get asked some version of this every week. From engineering managers. From designers. From PMs. My wife, last Sunday. The answer is the same every time.
No. Their role is about to change.
Design tools are where the planning happens. Where details are cheap to iterate, where variants get tested, where the structure gets fine-tuned before anything commits. Details are the job, and Figma is where you get to care about them without consequence. That work matters more now.
What’s changing is the handoff. For the first time, the builder isn’t a human interpreting a file. It’s a tool reading a spec. Figma doesn’t die. It stops being asked to do a job it was never built for.
Where this is heading
An architect doesn’t break ground from a sketch. They sketch in the studio, model variants, test the structure, then capture the decisions in a blueprint. The blueprint is what every contractor reads. Nobody calls the architect at midnight. Figma is the studio. The spec is the blueprint. The building is what ships.
Design systems work has always been about making design intent hold up in implementation. That bet holds up differently now that the implementation layer is an LLM. Components stop being pictures in a file. They become objects any tool can build from, and objects anyone can query.
Anyone leading a design system has the same question to answer: are your components still readable only by humans a year from now?
The design system was always the language. It finally has somewhere to live.
uSpec 2.0 ships with the create-component-md skill and the Figma extraction plugin. It’s free and open source. Documented at uspec.design. Code on GitHub.