The assumption that just broke
Every design system ever written assumes a reader who can fill gaps. Someone who can search Figma, skim a few implementations, ask in Slack, notice that the last three modals in the product all look a certain way, and infer the rule that was never written down. That reader is very good at recovering intent from incomplete documentation, and design systems were built knowing it.
An agent recovers nothing. It has a prompt, a retrieval step, and a strong prior from every public codebase it was trained on. When your system does not answer a question, it does not stop and ask. It answers from the prior, which is to say it builds a generic component that looks plausible and matches nothing you own.
The result is not obviously broken code. It is worse than that: it is code that passes review because it looks fine in isolation, and which quietly moves your product away from its own system, one pull request at a time.
Five failure modes
These are the patterns that come up again and again, in systems that are otherwise in good shape.
1. The component that cannot be found
An agent finds components by retrieval, and retrieval follows names, exports and documentation. A component that is exported from a deep path, absent from Storybook, and mentioned nowhere in a README is functionally invisible. The agent does not conclude it is missing. It concludes it needs to be written.
This is why duplicate implementations of the same empty state accumulate across a codebase. Nobody decided to duplicate anything.
2. The description that describes nothing
“Card component.” “A button.” “Modal dialog.” These are the most common descriptions in design systems and they carry no information an agent did not already have from the name. Useful descriptions answer a different question: what decision does this component exist to serve, and what makes it different from the component next to it.
3. The missing negative
Systems document what a component is for. They almost never document when to use something else. For a person, that is fine, because the wrong choice usually feels wrong. An agent has no feeling. Given Modal and Drawer with equally positive descriptions, it will pick on surface cues, and it will be confidently wrong a predictable share of the time.
A single line, “not for filtering or navigation, use Drawer”, is worth more to an agent than three paragraphs about the component's purpose.
4. The rules that only exist as numbers
Every hard-coded hex, every magic pixel value in the implementation is a rule with no name. When an agent reads that code as an example, it copies the literal. Your tokens describe the system; your literals describe what the system actually does, and the agent believes the second one.
5. The drift nobody logged
Figma has Dialog. The codebase has Modal. They started as the same thing, then the code grew a variant that design never got, and design added a size that code never implemented. No single change was wrong. There is now no reliable way to say which Figma component becomes which React component, which means design intent cannot be used to guide implementation at all.
What actually helps
Ordered by how much readiness they buy per hour spent. None of this requires a tool.
Moves the needle
- One sentence of negative guidance per component
- A Storybook story for every exported component
- Consistent, predictable export paths and names
- Replacing literal values with named tokens
- Recording which Figma component maps to which implementation
- Deleting or clearly deprecating the component nobody uses
Does not move the needle
- Rewriting component descriptions to be longer
- A new documentation site with better navigation
- Adding a rules file that restates your principles in prose
- Pasting the whole design system into the context window
- Prettier Figma files with no descriptions on the components
The pattern in the left column is that each item makes something retrievable or decidable. The pattern in the right column is that each item adds volume without adding a distinction. Agents are not short of text. They are short of the specific sentence that rules out the wrong answer.
Why more context is not the answer
The obvious fix is to give the agent everything: dump the documentation, the token file and every story into the context window and let it sort them out. This works in a demo and degrades badly in practice. Retrieval quality falls as irrelevant context grows, the cost scales with every request, and nothing in the dump distinguishes a current rule from a deprecated one.
The alternative is structure. If the system knows that DateRangePicker exists, that DatePicker handles single dates only, and that one supersedes the other for range selection, then the answer to “let someone pick a date range” is a short query with a short response. That is the difference between searching a library and photocopying it.
A useful test. Take the last five components your team built and ask, for each: if an agent had only what our system publishes, would it have found the existing component instead? Where the answer is no, you have found the gap that matters, and it is almost never a missing component.
Where Onefold fits
Everything above is work you can do by hand, and a small system maintained by one team probably should. What does not scale by hand is knowing where the gaps are across hundreds of components, keeping that knowledge current as the code changes, and reconciling two sources of truth that drift independently.
That is the part Onefold automates. It reads what you already have, scores it across eight dimensions, points at every specific gap it found, and then makes the parts that are ready available to the agents your team already uses.
Find your gaps before an agent does
Connect a repository and see which of the five failure modes your system has, with the specific components behind each one.
Request early access