Component.md
A design system is the set of rules, behaviors, and relationships that govern how a design language expresses itself. Components are an expression of that language, on a surface, at a specific moment. In the last decade, the field has used the terms "design system" and "component library" as if they were synonyms. They never were. This conflation worked when the reader of the artifact was a human engineer capable of filling in the gaps in the file. It ceases to work the moment the reader becomes a tool.
Over the past year, I've been testing AI tools on my Figma files: Figma Make, Claude Code, and Lovable. Last week, Claude Design was released, and I was eager to try it out.
The design never turns out exactly as I imagined. It's similar, but never perfect. The optical alignment is wrong. The font is incorrect. The spacing between elements is a few pixels off. The details that make a component unique were defined by guesswork: micro-interactions, behaviors, and specific token assignments.
This is what happens when a project is delivered to a tool without a specification. A Figma file is full of information. A tool that works only with this information has to guess everything the file doesn't say.
This is not a problem unique to Claude Design. It's a problem with all tools in this category, and the origin of the problem lies in the model itself. This gap is the dividing line between a toy and a tool that can be marketed.
LLMs are good at overall structure. They miss the essence, the part that makes a component unique, the part that a screenshot and a prompt can't convey. Figuring out what went wrong and fixing it costs more time and tokens than building the component.
I create and maintain design languages and component libraries that hundreds of engineers and designers use daily in their projects. The gaps I will describe below are not a theoretical exercise. They are the problems that occurred this week and that I needed to fix. Fixing them is my job.
The quality of these tools is determined by the design team during the transition to the model, and not by the modeling team itself.
Workarounds are already everywhere. We paste screenshots into prompts. We run MCP servers that extract frames from Figma and hope the tool will stitch them back together into something coherent. They exist because the Figma file was never designed to be read by a tool. It was made to be read by a human who could fill in the gaps. The reader has changed.
Why does this keep happening?
Something has quietly changed regarding what a designer's job entails. Not long ago, the final product was a frame. On the other side, a human, usually an engineer, would read, interpret, fill in the gaps, and send the code. This layer of interpretation was understood, budgeted for, and part of the job.
This interpretation layer is now a tool. When a designer delivers a component to Claude Design or Figma Make, there is no longer a human translator in the middle. The tool reads the artifact directly and generates the code. Most design systems haven't reached that point yet. We're still sending frames to a reader that needs a specification.
The source of truth for a component these days is scattered: partly in the Figma file, partly in the designer's head, the rest in Slack conversations and code reviews. Most design teams don't think of this as a source of truth problem. But that's exactly what it is.
Figma is a source of information, not the source of truth.
It's a good starting point for defining what a component should be: moving pixels efficiently, testing variants, and sharing ideas. It provides a lot of information to the tool: dimensions, colors, variants, the layer tree. But it doesn't tell which token controls which state, how the focus moves, or what the component communicates to a screen reader. A tool that reads the file gets the appearance and tries to guess the rest. That's where the guesswork begins.
What has to be true
Two things need to be true for all of this to work. The component needs to become the artifact, not just an image of it.
The components need to self-evaluate. The old model was one of static documentation, read the same way by everyone and interpreted individually. The new model is one of interactive documentation, which adapts to whoever reads it. Same file, different readers, different answers.
The components need to be compilable. Any LLM should be able to read a component and produce a faithful implementation on any platform. There's no need to guess the intent, as the tool is reading a specification rather than interpreting a rendering.
This is the change. A system where each component can be consulted, analyzed, and used for construction, both by humans and by LLMs (Learning and Learning Machines), without the need for a human translator at each stage of the process.
Component.md
The Component.md file is the artifact that makes both statements simultaneously true. One Markdown file per component. Platform independent. Designed to be the source of truth that the Figma file was never intended to be. A repository of the knowledge necessary for a component to be built on any platform.
The plan is as follows:
- API specification: properties, subcomponents, configuration examples
- Structural specifications: dimensions, spacing, how values vary depending on density, size and shape.
- Color assignment: the tokens that govern each element in each state.
- Voice/screen reader specifications: order of focus, ads, differences between platforms (VoiceOver, TalkBack, ARIA)
- Behavioral specification: Dismissal rules, error states, empty states
In addition to the schema, the file adapts to the component. Movement specifications. Decision trees for when to use each variant. Counterexamples of how the component should not be used. Migration notes. The schema is the contract. What fills it is the component.
This is how an error state manifests itself in practice. The color specification and the screen reader specification are in the same file, belong to the same component, and are distributed together.
# Text field ## When validationState === 'error' ### Color | Elements | 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 its place. Figma remains where it's most efficient. The .md file stores the decisions after they've been made.
Because it's Markdown, any code editor can read it. It can be exposed through MCP. You can deliver it to Claude Design, Claude Code, Figma Make, or any other tool that emerges in the future and receive back an implementation that matches your intention, regardless of the platform you are targeting.
Humans read it too. A designer or engineer consults it when they need an answer.
A feature designer creating a checkout flow asks: what is the order of actions in a group of stacked buttons?
An engineer reviewing a pull request encounters a different question: can I mix button sizes in a stacked group?
Static documentation websites were built on the assumption that the reader was a human being with twenty minutes to spare and the necessary context to interpret a page. This premise no longer holds true. The reader is sometimes a tool without context, and often a designer or feature engineer who has a question and needs an answer, not a page to analyze. A specification that a person can consult is the same specification from which a tool can build.
The specification is the interface. Anyone, or anything, can consult it.
How it works
Two stages: deterministic extraction, agentive creation.
The extraction is done through the plugin. uSpec For Figma, it guides you through the subcomponents of the element you're specifying and asks which ones need their own specifications and which are merely decorative. A text field has a label, an input, and a hint text. Each of these elements can be worthy of specification on its own, or it can be just an add-on. You decide. The end result is a set of JSON files that describe the essence of the component.
When creation begins, most of the work is already done. The plugin has extracted all the information from the Figma file: layout, variants, tokens, the layer tree, everything. What remains is interpretation.
Creation is done through a new skill: create-component-md . It forwards the extracted data to a set of specialized agents, each analyzing a different part of what Figma generated: one for structure, one for color, one for screen reader behavior. They run in parallel. None of them needs to wait for the other to complete its task.
Only then are the results converged and analyzed into a single component.md file. A reconciliation step identifies any gaps and re-runs the specialized program responsible for them.
The same text field, in three different ways: the Figma file that the tool reads today, the version the tool sends from that file alone, and the version it sends with the component.md file included. The difference is the variation between the two versions, now visible.
Why is separation important?
A script can extract numbers from any Figma file, organized or not. But it can't explain the meaning of those numbers. That's the gap. The way a component is built in Figma rarely matches how it's built in code. Real files have inconsistent names, workarounds created to circumvent Figma's limitations, and structural patterns that carry semantic meaning that the layer tree can't express.
A common example: a list item with a boolean option that toggles the initial content. When the boolean option is enabled, the designer can choose between an image, icon, or text.
Programmatically, Figma reads this as
leadingContent: true,
subcomponent: icon In engineering, it is a single enum:
leadingContent: "icon" | "image" | "text" | "none". Mechanical extraction provides the first result. Arriving at the second requires interpretation.
Extracting data without reasoning is like dumping data without thinking. Reasoning without extracting data is an illusion.
Extracting numbers from a Figma file doesn't require a model to reason about them. It requires a script, and scripts are free.
Reasoning only comes into play where it truly matters: in interpreting the meaning of these numbers. LLM never performs tasks that a script can do automatically and never needs to keep the raw data dump in its context window while attempting to process the data. The result is a specification that returns faster and less costly results, and a model capable of thinking where reasoning is essential.
What changes when the components can respond?
The target audience for the design system has doubled. In the last decade, we built it thinking about the humans who would use it. Now, we build it thinking about both the humans and the tools those humans use. This second audience is growing rapidly, and its criteria are different: it needs decisions to be documented, not implied.
The team ceases to be the bottleneck. Questions are answered without anyone from the systems design team needing to be online. What remains is the work that drives the system forward.
Are design tools dead?
Every week I get asked a similar question. By engineering managers. By designers. By project managers. By my wife, last Sunday. The answer is always the same.
No. Their role is about to change.
Design tools are where the planning happens. Where details are easy to iterate on, where variants are tested, where the structure is refined before anything is implemented. The details are the work, and Figma is where you can worry about them without consequences. That work matters even more now.
What's changing is the transition. For the first time, the builder isn't a human interpreting a file. It's a tool reading a specification. Figma isn't dying. It's simply ceasing to be asked to perform a task it was never designed for.
Where is this leading us?
An architect doesn't start a project from a sketch. They sketch in the studio, model variations, test the structure, and then record the decisions in a blueprint. The blueprint is what every contractor reads. Nobody calls the architect at midnight. Figma is the studio. The specification is the blueprint. The building is what is delivered.
The work of design systems has always aimed to ensure that the design intent is maintained in the implementation. This approach is different now that the implementation layer is an LLM (Learning and Learning Machine). The components cease to be images in a file. They become objects from which any tool can build and objects that anyone can query.
Anyone leading a design system faces the same question: will its components still be human-readable a year from now?
The design system has always been the language. Finally, it has a place to live.
