Design system docs AI agents can read: llms.txt and Markdown pages

A docs site is built for people, with menus, tabs, live previews and code that loads after the page does. An agent that fetches it gets the noise, or very little. Some public docs sites return almost nothing to a plain request. The SLDS site returned only its page title when this Site checked it, and Material 3’s guidelines site had no readable version at all. Whatever an agent cannot read, it fills in from memory, which is usually an older version of your system.

An llms.txt is a Markdown file at the root of a site. The proposal at llmstxt.org asks for little: an H1 with the name is the only required part. After it come a short summary in a blockquote, then sections under H2 headings, each a list of links with a note on what the page holds. A section titled Optional holds what an agent can skip when it is short of room.

# Example Design System

> Design tokens, 40 React components and the rules for using them. Start with the guidance for agents.

## Start here
- [Guidance for agents](https://design.example.com/agents.md): what to use first, what never to do
- [Design tokens](https://design.example.com/tokens.tokens.json): every value, in the W3C format

## Components
- [Button](https://design.example.com/components/button.md): variants, sizes, when to use each

## Optional
- [Changelog](https://design.example.com/changelog.md)

The same proposal suggests a Markdown copy of each page at the page’s address with .md added. React Spectrum does exactly that, so /Button.md returns its button docs as text. Shopify serves every docs page as Markdown and has no llms.txt, which still earns full Docs points here. Fluent 2 publishes a text file per page, listed from its llms.txt.

Some systems also publish everything in one file. Atlassian’s llms-full.txt is about 670 KB, and Ant Design’s about 2 MB. That is convenient for a search tool and too big for most agents to read at once, so the better systems also split by subject: Atlassian publishes separate files for design tokens, components and primitives, and Chakra UI one for theming. Give an agent the smallest file that answers its question.

• GitHub Primer has an official MCP server but no llms.txt and no Markdown pages, so it scores 0 on Docs.
• The GOV.UK Design System has neither, and no .md versions of its pages.
• Salesforce Lightning has plain-text docs on Salesforce’s developer portal, not on the SLDS site, so it gets half.
• Material 3 for the web has Markdown docs on GitHub for its web components only, also half.

The best AI-ready design systems, ranked links each of these to its proof.

1. Generate the Markdown at build time, from the same source as the HTML, so the 2 never disagree.
2. Write the llms.txt by hand the first time. Give it the name and a summary of 1 or 2 sentences, then sections for the guidance, the design tokens, the components and the rest.
3. Link the token file and the guidance from it, so the index leads to the parts an agent needs first.
4. Test it like an agent would. Request /llms.txt and one .md page with a plain command-line request, and read what comes back.

This Site follows its own advice: its llms.txt lists every page, and each has a Markdown copy. For a design system that needs all of this built around a brand, Work with Simbolik (opens in a new tab).