Turning Design-System Documentation Into a Reliable Knowledge Base

I did not arrive at this topic by starting with a vector database or a formal retrieval architecture. I learned it while leading Mach Core, the engineering embodiment of the Mach 1 Design System.

Mach Core did not document every Mach 1 design rule. The design team maintained a separate site for that guidance. Our responsibility was to give engineers a fast, practical way to use Mach 1: grab production-ready components and design tokens, assemble an interface with speed and ease, and remain compliant with the system.

The Mach Core documentation site used Astro Starlight. Astro is awesome, and Starlight gave us a fast, accessible foundation with navigation, search, code highlighting, and support for Markdown and MDX. The site looked like a documentation site, behaved like one, and did a decent job of helping engineers browse.

But “decent” was not the same as reliable.

The moment “good enough” stopped being enough

At the beginning of 2026, my advisory developer gave us the blunt version: our docs sucked.

He was not wrong. Important knowledge was spread across component pages, code-heavy .astro files, examples, implementation details, and conversations with maintainers. An engineer could usually piece together an answer, but only if they knew where to look and which details mattered.

He proposed a definition of done for improving the documentation. It was a solid start: the work needed clearer expectations, more complete guidance, and a consistent standard before we could call a page finished.

What I kept thinking about, though, was who, or what, would read those pages next.

The definition of done was designed for the immediate problem: helping people use the system. I could already see AI-assisted development and agentic tooling becoming part of how our engineers worked. If we rewrote the docs only for a browser, we would improve the site without necessarily improving the underlying knowledge.

I wanted our definition of done to account for both.

We still completed the documentation work we had committed to. AI enablement was not part of the assigned scope, so I kept that work moving in the background instead of allowing it to distract from the DoD. My goal was to make choices within the current initiative that would also position the team for what I believed was coming next.

We separated the knowledge from the website

When I assigned the documentation work, I asked the developers to move the heavily coded .astro pages toward simple Markdown.

That was not a criticism of Astro. The framework had done its job well. The problem was that too much of our guidance was coupled to the page implementation. JavaScript, layout code, and presentation components made the content harder to extract, inspect, and reuse outside the website.

Markdown gave us a deliberately boring source format. It kept headings, lists, code examples, tables, and links intact while making the guidance readable without rendering the entire application. It was easy to review in a pull request, easy to transform, and easy for another tool to consume.

I used Claude to help create a custom page extractor for the content we already had. That gave us a practical migration path instead of forcing the team to copy every page by hand.

Our deployment environment added another constraint. The documentation lived on internal cloud infrastructure, and our agentic tools needed to reach it from inside the company VPN. We could not serve the Markdown files exactly as we would have on a public static site, so the pipeline exported the Markdown payloads through .txt files. The extension changed, but the structure and content were preserved.

Following the llms.txt proposal, I then created an internal endpoint that acted as a directory for the generated documentation files. Each entry included the page description and useful aliases or search cues. A button page, for example, could be associated with terms such as “button,” “CTA,” or “ghost,” giving an agent more than an exact page title to work with.

We intentionally excluded some pages from that directory. The pattern I wanted was simple: the .html experience was for people, while the .txt experience was for AI. They came from the same knowledge base, but they did not need to expose identical information.

The human-facing pages prioritized explanation, navigation, examples, and the details an engineer needed while browsing. The AI-facing files could be more direct. We created a frontmatter field called llmRules for gotchas, implementation details, and constraints that would help an agent choose or implement something correctly but would add noise to the human reading experience.

That separation also let us leave out pages that did not provide useful agent context. More content was not automatically better context.

The agent could use that directory to identify the most relevant documentation and then read the corresponding Markdown content. The generated files included the details an engineering agent actually needed: when to use a component, which options it supported, how tokens related to it, and which constraints were part of the contract.

It became a lightweight, pseudo-RAG pipeline. We did not need a vector database for the first useful version. The directory provided a curated retrieval layer, the aliases connected consumer language to Mach Core’s engineering vocabulary, and the underlying files supplied the grounded context. That combination helped anchor the model before it made a recommendation.

That work did more than clean up a docs site. It helped give the Mach 1 AI Design Assistant a dependable knowledge foundation.

The sequence mattered:

1. An honest critique exposed that our documentation was not meeting the team’s needs.
2. Completing the definition of done gave us a shared quality bar.
3. Looking ahead changed that bar from “good web page” to “reliable source.”
4. Markdown made the source portable.
5. An automated export made it reachable within our infrastructure.
6. Descriptions and aliases connected consumer language to the right source.
7. Curated pages and llmRules gave the agent purpose-built context.
8. llms.txt gave agentic tools a predictable entry point.

That experience changed how I think about the engineering documentation surrounding a design system.

Thinking ahead can create friction

The AI work was not an obvious priority to everyone at the time. One of the senior developers on my team did not initially understand why I was pushing so hard for it, especially when it was not part of the stated DoD. That created some disagreement.

The question underneath that disagreement was fair: why spend energy preparing for a use case the team had not formally been asked to deliver?

For me, technical leadership includes looking beyond the literal request. I try to understand where our consumers, including development teams and business partners, are heading, translate those goals into concrete engineering work, and help my team deliver today without forcing them to start over tomorrow.

That does not mean chasing every new technology. It means noticing when a current decision can either narrow or expand the team’s future options. Moving the documentation into portable, descriptive sources completed the immediate work and opened a path for AI tooling at the same time.

The value became easier to see once the agent could retrieve a term engineers actually used, resolve it to the right Mach Core guidance, and make a better-supported recommendation. The results gave the team a shared understanding that the proposal alone could not.

That experience taught me how to pair logical anticipation with the short-term business momentum that corporate environments constantly demand. Thinking ahead only creates value if the team still delivers what the business needs now. The opportunity was to satisfy the immediate request while quietly making the result more durable and extensible.

Documentation is content before it is a website

A documentation website is one interface to the knowledge. It is not the knowledge itself.

For us, that knowledge had a deliberate boundary. The Mach 1 design team remained the authority for the system’s design rules. Mach Core documented how engineers could turn that direction into working, compliant interfaces through components, tokens, APIs, and implementation guidance.

That distinction is easy to miss because teams spend so much time making the site pleasant to browse. Navigation, search, interactive examples, and polished layouts all matter for people. But when the only trustworthy version of a rule is trapped inside a custom page component, every new consumer has to reverse-engineer the presentation layer to recover it.

A better foundation keeps the authored guidance portable and lets the site enhance it. The same source can then support:

• an engineer reading a component page;
• a maintainer reviewing a change;
• a search index finding an exact token;
• an AI assistant answering a usage question; and
• an agent gathering context before it changes code.

This does not mean every source must be Markdown. Component types, token files, tests, and release metadata may be more authoritative for particular facts. It means the prose that carries human judgment should not depend on a browser runtime to remain intelligible.

It also does not mean every output must be identical. The human and AI experiences can share an authoritative source while applying different inclusion rules and exposing different supporting context.

A definition of done should describe usable knowledge

“The page exists” is not a meaningful definition of done. Neither is “the component API is listed.”

For Mach Core, the useful questions were closer to:

• How does an engineer install, import, and use this component?
• Which component or token implements the intended Mach 1 direction?
• Which options and variants are supported?
• Which design tokens does it use?
• What accessibility behavior is required?
• What does a minimal correct implementation look like?
• Is any part of the guidance deprecated or version-specific?

Those questions work for a person, but they also give an AI system a much better chance of producing a grounded answer.

The ARIA Authoring Practices Guide is a useful model. Its patterns connect purpose, semantics, keyboard behavior, and functional examples. A screenshot cannot substitute for those relationships, and an API table cannot explain all of them.

I now think of a strong component page as an engineering contract. It should make the API, implementation path, and constraints explicit enough that a reader does not have to infer the important parts from the source code.

Structure is part of reliability

A person can reconcile a component page, a code example, a migration note, and a conversation with a maintainer. An AI system receives fragments. If those fragments disagree or lose their relationship to a version, the answer can sound authoritative while still being wrong.

That makes structure more than an editorial preference.

Each piece of guidance should carry enough context to answer:

• what it describes;
• where it came from;
• which package or product it applies to;
• whether it is current, deprecated, or experimental;
• who owns it; and
• which components, tokens, patterns, or replacements are related.

For an API signature, executable types may outrank prose. For intended usage, reviewed guidance may outrank an incidental example. For keyboard behavior, the component contract and accessibility requirements should outrank a screenshot.

The system needs those distinctions before an agent asks a question. Asking a model to choose between conflicting sources at response time is not a reliability strategy.

Generate facts; author judgment

Some documentation should be generated because the implementation already knows the answer.

Names, input types, defaults, token values, and release versions are good candidates. Generating those facts reduces drift and lets the team validate documentation against the real package.

The harder guidance still needs an owner:

• how the component should be integrated;
• which engineering tradeoffs and compatibility limits matter;
• which API and content constraints must be preserved;
• which implementation shortcuts are prohibited; and
• what accessible behavior users should experience.

No extractor could make those decisions for us. Claude helped me change the shape of the existing content, but the team still had to improve what the content actually said.

That boundary matters in two ways. AI can accelerate the mechanical work without becoming the authority, and Mach Core can document the engineering contract without replacing the Mach 1 design team’s guidance.

Access is part of the architecture

One of the most practical lessons from this work was that perfectly structured knowledge is useless to an agent that cannot reach it.

Our internal cloud and VPN requirements were not side notes. They shaped the solution. Exporting Markdown as text was not the most elegant idea on a whiteboard, but it preserved the content and worked inside the environment where our engineers and tools operated.

The llms.txt entry point also did not magically make the documentation trustworthy. It made the approved sources discoverable and gave the agent a simple way to choose which document to read. Reliability still depended on the quality, ownership, descriptions, aliases, llmRules, and freshness of the files behind it.

I have become wary of starting these projects with “Which model or database should we use?” The first questions are more basic:

1. Where does the authoritative guidance live?
2. Can it be read without reconstructing a website?
3. Can the intended tools reach it securely?
4. Does it contain enough context to support the decisions we expect?
5. How will it stay current as the system changes?

If those answers are weak, a more sophisticated retrieval layer only makes the weakness harder to see. Our pseudo-RAG approach worked because the retrieval mechanism stayed simple while the knowledge behind it became more deliberate.

Evaluate the decision, not the fluent answer

The purpose of this knowledge was not to help an agent produce nicer paragraphs. It was to help engineers make better implementation decisions.

That means evaluation should use real Mach Core engineering questions and known failure modes:

• choosing between visually similar components;
• recommending an unsupported option;
• missing a required accessible name;
• applying a raw value instead of a semantic token;
• mixing guidance from incompatible versions;
• copying an example without its constraints; and
• answering confidently when no approved implementation exists.

For each case, I want to know whether the right source was available, whether the important context survived, and whether the resulting recommendation was correct. A confident refusal is more useful than a polished answer that invents a component API.

Failures should also flow back to the documentation. If engineers repeatedly ask a question that the system cannot answer, the durable fix may be better component guidance, not another prompt adjustment.

The real product was shared understanding

Mach Core already had a documentation site. What it needed was a more dependable relationship between the implementation, the guidance, and the tools engineers were beginning to use.

The most valuable decision was not choosing Astro, Claude, Markdown, .txt, or llms.txt in isolation. It was recognizing that documentation had become infrastructure, and that finishing today’s work could also prepare the team for tomorrow’s.

Once I saw it that way, the path became clearer:

• keep authored knowledge simple and portable;
• define “done” around the decisions the system must support;
• preserve authority and context;
• automate the facts that can be derived;
• keep human judgment owned and reviewable;
• make approved sources securely accessible; and
• test whether the knowledge leads to correct decisions.

That approach produced more than better input for an AI assistant. It made the engineering path into Mach 1 clearer for the people building Mach Core, the teams using it to ship interfaces, and the agents working alongside them.

I wanted telemetry on the endpoint, but we never instrumented it, so I cannot responsibly attach a daily request count to its adoption. My sense was that usage had become substantial and was still growing, but the lesson does not need an invented number.

The domino effect started with a small decision: make the documentation portable enough to serve a second audience. That decision led to better source material, an AI-specific contract, a lightweight retrieval pattern, and a stronger foundation for the agent that followed.

It also reflects how I try to lead: listen closely to the people consuming our work, translate what they will need into something the team can build, and stay far enough ahead that the next opportunity feels like a continuation, not a scramble.