Skip to content

llms.txt for component libraries: what to put in it

What a UI component library's llms.txt should contain: quick start, code rules, a one-line index, llms-full.txt and Markdown pages, generated from the source.

By , MiniDev10 min read

An llms.txt file is a Markdown index at the root of a site that tells language models what the site is and where the useful pages are. For a component library it does more work than for most sites, because the agent reading it is about to write code. A good one gets a correct install on the first try and code that looks like the rest of the project. This guide covers what the format requires, what a component library should add, and how MiniDev UI generates its own.

What the format requires

The llms.txt proposal from Jeremy Howard (September 2024) is deliberately small. Only the H1 is required. The full order is:

  1. An H1 with the project or site name.
  2. A blockquote with a short summary.
  3. Any Markdown except headings: paragraphs and lists explaining the project and how to read the linked files.
  4. H2 sections, each a list of links in the form - [name](url): notes.
  5. Optionally an H2 named Optional for links an agent can skip when context is short.

The proposal also suggests a clean Markdown version of each useful page at the same URL with .md added, and lets a file live at a subpath to cover the pages under it. It does not define llms-full.txt; that is a common convention for "everything in one file".

What a component library should put in it

SectionWhy the agent needs itKeep it
Summary blockquoteDecides in one read whether this library fits the task: framework, styling, licence, sizeTwo or three sentences
Quick startExact commands to install and wire up styles, in orderNumbered, copy-pasteable
Rules for generating codePrimitives, prop patterns, tokens, shadows, motion, accessibilityOne checkable rule per bullet
Machine-readable linksPer-component Markdown, catalogue JSON, registry index, llms-full.txtURL patterns, not every URL
Docs linksGetting started, gallery, templatesA handful
Component indexFind the right component by need, not by nameName, link, one line

Here is the top of MiniDev UI's llms.txt, trimmed. The quick start and rules come before the long index on purpose: an agent that stops reading early still installs correctly.

llms.txtbash
# MiniDev UI

> Free, MIT-licensed React + Tailwind CSS v4 components, blocks and motion pieces for product UI.
> Built on Base UI. Every component is one TypeScript file you own, installed with the shadcn CLI.

## Quick start (follow exactly)

1. A React project with Tailwind CSS v4 and the `@/*` alias. Run `npx shadcn@latest init` once.
2. Tokens: `curl -o app/minidev.css https://ui.minidev.pro/r/styles.css`, then import it after tailwindcss.
3. Add components: `npx shadcn@latest add @minidev/button @minidev/dialog`.

## Machine-readable

- Per-component Markdown: `https://ui.minidev.pro/docs/<name>.md`
- Everything in one file: https://ui.minidev.pro/llms-full.txt

## Rules for generating code with MiniDev UI

- Built on Base UI, not Radix: pass `render={<a href="/pricing" />}`. There is no `asChild`.
- Semantic tokens only: bg, surface, raised, sunken, fg, fg-muted, accent... Never hex or blue-500.
- Icon-only buttons need aria-label.

## Components

- [AgentTrace](https://ui.minidev.pro/docs/agent-trace.md): An AI agent run as a timeline of tool calls and steps.
- [AiComposer](https://ui.minidev.pro/docs/ai-composer.md): A chat input for AI apps: prompt, suggestions, model picker...

Write rules an agent can follow

Most llms.txt files stop at links. For a component library the rules are where the value is, because they cover the mistakes models make from habit: Radix props on a Base UI library, palette colours instead of tokens, a shadow typed by hand. A rule earns its place if you could check it with a grep or the type checker.

VagueCheckable
Use the design system coloursUse semantic tokens only: bg-surface, text-fg-muted... Never hex, blue-500, bg-white or bg-black
Make it accessibleIcon-only buttons need aria-label. Dialogs always get a title
Follow our patterns for linksRender a link as a button with render={<Link href="/x" />}. There is no asChild
Keep animations subtleSprings from the presets only: snappy { type: "spring", bounce: 0.18, duration: 0.42 }. Nothing animates on page load
Use our componentsExports are named, PascalCase of the file name: chat-thread exports ChatThread

Put the same rules in an AGENTS.md or Cursor rule that users can drop into their project, so the agent sees them on every task and not only when it happens to fetch your llms.txt. The AGENTS.md guide covers that side.

Per-component Markdown and llms-full.txt

The index line tells the agent a component exists. The Markdown page tells it how to use it: purpose, when to choose it over its neighbours, the install command, props with types and defaults, and one or two examples. Serve it at the docs URL plus .md, as plain text with no navigation, so a fetch tool gets content rather than chrome. llms-full.txt concatenates those pages for agents that prefer to load or search one file.

In Next.js, a rewrite maps the .md URL to a route that renders the page as Markdown. MiniDev UI uses this in its next.config.ts; the comment explains why a rewrite is needed at all.

next.config.tsts
async rewrites() {
  // afterFiles: runs before dynamic routes, so /docs/button.md never reaches /docs/[name]
  return [{ source: "/docs/:name([a-z0-9-]+)\\.md", destination: "/docs/:name/md" }]
},

Point to the Markdown version from the HTML page too, so agents that land on the page can find it. In the Next.js metadata API that is an alternate type:

app/docs/[name]/page.tsxts
export async function generateMetadata({ params }: { params: Promise<{ name: string }> }) {
  const { name } = await params
  return {
    alternates: { types: { "text/markdown": `/docs/${name}.md` } },
  }
}

Generate it from the source

If your components are a shadcn registry you already have the data: registry.json lists every item with its name, title, type and description. Write the quick start and rules by hand once, and let a script append the index on every build. MiniDev UI goes one step further and builds descriptions and props tables from the doc comments in each component file, so what an agent reads in llms.txt matches what it sees when it opens the source, and the build fails if those comments go missing.

scripts/build-llms.mjsts
import { readFileSync, writeFileSync } from "node:fs"

const SITE = "https://ui.example.com"
const { items } = JSON.parse(readFileSync("registry.json", "utf8"))
// Hand-written: H1, summary, quick start and rules
const head = readFileSync("docs/llms-head.md", "utf8").trim()

const section = (title, type) => {
  const list = items.filter((i) => i.type === type)
  return [`## ${title} (${list.length})`, "", ...list.map((i) => `- [${i.title ?? i.name}](${SITE}/docs/${i.name}.md): ${i.description}`)].join("\n")
}

writeFileSync(
  "public/llms.txt",
  [head, section("Components", "registry:ui"), section("Blocks", "registry:block")].join("\n\n") + "\n",
)

Run it before next build so the file never drifts from the registry. Fail the build if any item has an empty description; an index line with no description is a component the agent will never pick.

Test it like an agent would

  1. Open a new, empty project and a fresh agent session with no other context.
  2. Prompt: "Read https://your-site/llms.txt. Install what you need and build a sign-in page with email, password and a forgot password link."
  3. Watch which URLs it fetches. If it never opens a component's Markdown page, the index lines are not telling it enough.
  4. Run npx tsc --noEmit and grep for raw colours. Each failure points at a rule that is missing or unclear.
  5. Fix the file, start a new session and repeat. Two or three rounds usually settle it.

Common mistakes

  • Marketing copy in the summary. "Beautiful, blazing fast" tells the agent nothing. Say the framework, the styling system and the install method.
  • Install steps buried below the index. Agents stop reading long files early. Put the quick start first.
  • Links to HTML pages only. Tabs, client-rendered examples and navigation make docs pages hard to read through a fetch tool. Link the .md versions.
  • One giant file and nothing else. llms-full.txt is useful, but an agent with limited context needs the short index to find the one page it wants.
  • Rules that contradict the examples. If an example uses bg-white, the agent will copy the example. Lint your docs examples with the same rules.

Components used in this guide

Frequently asked questions

What is llms.txt?

A proposed standard from llmstxt.org: a Markdown file at /llms.txt with an H1, a short summary, optional notes and sections of links that help language models understand and use a website.

What is the difference between llms.txt and llms-full.txt?

llms.txt is a short index with links. llms-full.txt is a common convention for the full content in one file. Component libraries benefit from both: the index for finding a component, the full file for searching props and examples.

Do AI coding agents actually read llms.txt?

Agents read it when they are pointed at it, by a rules file, a prompt or an MCP server that fetches it. That is why a library should link it from its AGENTS.md and README and keep the most important instructions near the top.

Should llms.txt include code rules or only links?

For a component library, include rules. Short, checkable rules about props, tokens, imports and accessibility prevent the most common generated-code mistakes, and they cost a few hundred words.

More guides