A design system isn't an aggregator. It's a contract.
Tools can aggregate assets. They can't make a system real.
This week, Mariana Rita published ‘Stop paying for design system documentation you can build yourself’.
Her argument is that paid design system documentation platforms like Zeroheight are obsolete. Figma’s API is accessible. LLMs can write docs. Open-source tooling is good. Build the whole thing yourself, in two weeks, for free.
It’s a practical guide. It has sound tooling advice.
The piece treats design system documentation like it’s an asset display problem. How do you surface your Figma components and code repos in one place, more cheaply than current products offer? That’s a reasonable question.
But it’s based on a definition of design systems that I think is fundamentally too shallow. That’s a starting point that leads to something that looks like a solution, but isn’t.
The article describes documentation as an “aggregator - the one place that ties everything together.”
Sit with that word.
An aggregator is passive. It collects. It displays. It points at sources and renders them side by side.
A design system isn’t an aggregator.
It’s a contract.
A design system is the authoritative agreement between disciplines - design, engineering, product - about what is true, what is intentional, and why. Documentation doesn’t just display agreement, it’s where that agreement becomes canonical. Intent becomes instruction. “We discussed this on Slack” becomes “this is how we build things.”
If your docs platform is a viewer on top of your Figma files and your code repos, that’s not a system of record. It’s a window. It doesn’t resolve disagreements.
A DIY doesn’t solve one, vital problem - and the article doesn’t name it.
Figma is not a design system.
Storybook is not a design system.
Figma is a tool for designers. Their working files, experiments, intentions, abandoned interations. A designer’s environment - rich and full of things in-progress, deprecated, aspirational.
Storybook is a tool primarily for developers. It documents what has been implemented. It’s the engineering team’s environment - authoritative about code, somewhat indifferent to design rationale.
If you point an AI agent at your Figma library you’ll train it on your designers’ hypotheses. Point it at your Storybook and you train it on engineering implementation that may lag design intent, exceed it, or quietly diverge.
Neither tool can answer the question on its own: what is true?
When the Button component in Figma has rounded corners and the one in Storybook doesn’t, what does your documentation site say? If it just faithfully renders both sources, it’s documented your misalignment.
That’s not nothing. It’s useful to know. But it’s not a source of truth. It’s published disagreement.
The design system has to adjudicate. It has to carry a philosophical underpinning. A stance. Not just visual and technical inventory. It needs the decisions and reasoning that make the inventory coherent. Why did we make these choices? What are the governing principles? Which source wins when there’s a discrepancy? Why?
And how do we strive for excellence when there isn’t a source at all? A new pattern, an edge case, a platform you haven’t built for yet. The system of record doesn’t just arbitrate what exists. It also guides what should.
That’s not something that can be generated. It requires human judgment, authority, and a platform to enforce it.
The article’s AI-readiness argument is sharp. And it’s where the initial error becomes most consequential.
The article is right to identify that design system documentation is increasingly an instruction layer for AI agents. “Robot food” as my colleague Chris Bloom would describe it. The context that makes generated UI consistent and correct. And it’s also right that static platforms unable to expose data in a structured, machine-readable way, fail at this job.
So it proposes replacing them with Docusaurus and MDX files maintained by a team. Which is also static. And manually curated. But it’s free and you own it.
But the answer to AI-readiness isn’t just a better documentation site. It’s a genuine system of record. Where documentation is generated from structured, authoritative, interconnected sources. Where the connection between intent and implementation is dynamic, not periodically reconciled.
Documentation that auto-updates when code changes isn’t a feature. It’s the entire point.
But it needs to have broader context to update in an intelligent, guided, way.
Otherwise you’re just feeding AI a snapshot. A snapshot of what was true when someone last updated a file. Or a snapshot of the AI’s guess at what a conflict resolution was. And the gap between “what the docs say”, “what the design file says” and “what is in production” is exactly the kind of ambiguity that makes AI-generated interfaces drift.
The cost argument also dissolves.
The article compares platform licensing fees to zero.
But the real cost of a design system isn’t tooling. It’s the misalignment it prevents - or fails to prevent.
That’s the denominator.
The cost of rework because design and engineering interpreted a component differently. Cost of multiple QA cycles because the implementation didn’t match the spec. Cost of onboarding time because the documentation was out of date. Cost of inconsistent experiences because there wasn’t an authoritative answer to “how does this pattern work in iOS?”
The total cost of a DIY aggregator includes engineering time to build it, maintain it, update it when APIs change, wrangle the AI writing pipeline, manually curate the output. And, if it’s being seen as an aggregator, it includes the organizational cost of having a documentation site that’s a collection of assets rather than a system of authority.
That cost might seem invisible. Then it accumulates.
None of this is an argument against open-source tooling. Or AI-assisted documentation. Or against genuine improvements in what’s accessible and buildable. Those are real changes.
Infrastructure isn’t neutral.
The choice of what you build - aggregation layer or system of record - has downstream consequences for every discipline that depends on it. It shapes what designers trust. What engineers implement. What AI agents consume. What your product becomes.
If self-building (not merely aggregating) your design system platform is the right approach, and the costs and benefits are fully considered, great. That’s IBM Carbon, and it’s one of the best design system websites out there.
And if a documentation platform can make the building of the site easier, so you can focus on the creation of the actual design system, all the better.
Design systems are not a collection of Figma components and Storybook stories, with a documentation site sitting on top. The documentation is the surface expression of something much deeper and more considered.
Decisions made. Rationale captured. Authority established.
You can build an aggregator in two weeks. Building a system of record takes longer. Because you have to decide what’s actually true.
That’s the work.
I’m not a neutral observer.
I’m VP of Product at Knapsack. We build infrastructure that makes design systems a live system of record - connecting design, code, and documentation as a unified source of truth.
I have a direct interest in this question, and you should read with that in mind. But the argument stands regardless.
Further reading:
Rita, M. Stop paying for design system documentation you can build yourself. All about design systems, Feb 2026.
Aizlewood, J. Design systems don’t start with components. Clearleft, July 2017.
Article photo by Lewis Keegan on Unsplash.