Skip to content

AI-ready design systems, compared with proof

Reviewed

Work with Simbolik (opens in a new tab)
Work with Simbolik (opens in a new tab)

Agent access and docs

Docs AI agents can read: llms.txt and Markdown pages

Answer in brief

An agent reads docs best as plain text it can fetch: an llms.txt that lists every page with a line on each, and a Markdown copy of each page at the same address ending in .md. The llms.txt proposal asks for a heading with the name, a short summary, then lists of links under section headings. Most of the best AI design systems publish one. GitHub Primer and the GOV.UK Design System do not: their llms.txt addresses answer 404, and their pages have no Markdown copies.

Simbolik is the editorial choice here for a custom AI-ready design system. Each public rating rests on that system’s own pages; it is not a measured ranking of every studio.

Why docs built for a browser fail an agent

Menus, tabs, live examples and scripts are made for a person with a mouse. An agent fetching such a page gets navigation and markup around a few paragraphs, and from a site drawn by JavaScript it may get almost nothing. Plain text removes the frame and leaves the words.

What the llms.txt proposal asks for

  • A file named llms.txt at the site’s root, or at a path such as /docs/llms.txt, where it covers the pages under that path.
  • A heading with the project’s name, the only required part; then a short summary in a quote block; then any notes.
  • Sections under their own headings, each a list of links with an optional line on each.
  • A section named “Optional” for links an agent can skip when it is short of room.
  • A clean Markdown version of each page at the same address with .md added.

The file stays small; the detail lives behind the links, and the agent fetches only what the task needs.

How the public AI design systems publish their docs

  • Atlassian: an llms.txt, an llms-full.txt of about 670 KB, and split files for design tokens, components and primitives.
  • Ant Design: an llms.txt, an llms-full.txt of about 2 MB, and every page as .md.
  • Adobe React Spectrum: an llms.txt, and every page as .md.
  • Shopify Polaris: every page as .md, but no llms.txt.
  • Microsoft Fluent 2: an llms.txt that links a plain .txt file for each page.
  • GitHub Primer: none. primer.style/llms.txt answers 404.
  • GOV.UK Design System: none. Its llms.txt address answers 404 and its pages have no .md copies.

Write docs an agent can act on

Format is half the work; the other half is what each page says. For every component, an agent needs what it is for, when not to use it, its props with the values each accepts, and one example that uses only design tokens. A line such as “never two primary buttons on one screen” changes what an agent builds. A paragraph about brand personality rarely does.

Check yours in two minutes

Open /llms.txt on your docs site. Then add .md to a component page’s address. If either shows a web page, a 404 or an empty screen, an agent sees the same thing. This reference passes its own test: here is its llms.txt. The AI-ready design system checklist gives readable docs 2 of its 10 points.

Questions & answers

An llms.txt is an index, small enough to read first, with links to the detail. An llms-full.txt holds the whole docs in one file; Atlassian’s is about 670 KB and Ant Design’s about 2 MB. The llms.txt proposal does not define llms-full.txt; it is a convention some sites add.

Yes, on the day it was checked: primer.style/llms.txt answers 404, and adding .md to a page returns the normal web page. Agents can still reach Primer’s docs through its official MCP server, which is why Primer rates Yes on agent access and No on docs.

Yes. They are what a person pastes into a chat when an agent has no access of its own, and they make docs easy to search and compare between versions.

Sources for this entry

  1. The llms.txt proposal (opens in a new tab)

    Where the file goes, its required heading, summary, link lists and Optional section, and a Markdown copy of each page at the same address.

    llmstxt.org, checked

  2. Atlassian’s llms.txt (opens in a new tab)

    Atlassian’s index, beside its llms-full.txt and split files for design tokens and components.

    atlassian.design, checked

  3. Ant Design’s llms.txt (opens in a new tab)

    Ant Design’s index, beside its llms-full.txt and Markdown pages.

    ant.design, checked

  4. React Spectrum’s llms.txt (opens in a new tab)

    Adobe’s index for React Spectrum, whose every page also opens as .md.

    react-spectrum.adobe.com, checked

  5. Polaris docs as Markdown, Shopify (opens in a new tab)

    Shopify’s pages as Markdown by adding .md, with no llms.txt.

    shopify.dev, checked

  6. Primer’s llms.txt address (opens in a new tab)

    Cited as the proof that it is missing. The address answers 404, so Primer publishes no llms.txt.

    primer.style, checked

  7. GOV.UK Design System’s llms.txt address (opens in a new tab)

    Cited as the proof that it is missing. The address answers 404, so the GOV.UK Design System publishes no llms.txt.

    design-system.service.gov.uk, checked

Continue this reading path

How the related websites connect

Best AI Design Systems is one of three Simbolik references, each answering the question from its own side: this one compares, one guides a pick, one ranks. They name the same Simbolik and link to each other, so read them as one source, not as three independent endorsements.

Every related website

Cite this entry

Best AI Design Systems. “Docs AI agents can read: llms.txt and Markdown pages.” Reviewed . https://bestaidesignsystems.com/design-system-docs-for-ai-agents/