llms.txt

This page explains the llms.txt convention and the information in HeroGPUI's file. It puts the repository's Rust spellings, state patterns and GPUI constraints in one place for coding agents.

What llms.txt is

llms.txt is a community convention (proposed at llmstxt.org) for a markdown file placed at a site's root that is written for language models rather than for browsers: an H1 naming the project, a blockquote summarising it, then H2 sections carrying the details an agent needs — API references, conventions, usage. It complements robots.txt (which governs crawling, not comprehension) and README.md (which is written for humans who have already cloned the repository).

Documentation sites commonly publish two flavours: the index file, and a llms-full.txt bundle containing the entire documentation corpus. HeroUI itself publishes both, and the repository's audits read HeroUI's heroui.com/react/llms-full.txt bundle as upstream reference data. An agent pointed at an llms.txt gets the repository's API contract instead of having to infer it.

HeroGPUI's llms.txt

The file lives at the repository root, next to README.md. It is 573 lines (~55 KB) of plain markdown, and the repository's own agent guide designates it the public component API reference. The site serves it as text/plain — see /llms.txt.

What each section gives an agent

The file is organised top-down: crate map, bootstrap, theme system, the shared prop vocabulary, then per-component API. Sections and their purpose:

Excerpt

The per-component sections name builders with their exact Rust spellings, including the details that are easy to miss — here the note that a button's icon and label are ordered children because the API has no start/end content slots:

1Button::new("save")
2    .child(icon)          // ordered children: leading icon first, then label text
3    .child("Save")
4    .variant(Variant::Primary)
5    .size(Size::Md)
6    .is_pending(true)
7    .full_width(true)
8    .on_press(cx.listener(|this, _, _, cx| this.save(cx)))

Why this matters here

HeroGPUI combines a Rust component API with GPUI's framework rules. llms.txt records the exact spellings, state patterns and platform assumptions an agent needs to work in this repository:

• Use the supported vocabulary. There is no color × variant matrix (colors are default | accent | success | warning | danger), no radius prop, no content1..4 surfaces, and components such as Navbar and Image are not part of the library.
• Use the pinned framework assumptions. The repository targets the Zed GPUI git revision in Cargo.toml and Cargo.lock, with Rust 1.98. A newer GPUI API may not be available here. Inherited behavior follows React Aria 3.51.0, React Stately 3.49.0 and React Aria Components 1.20.0. Check this file and the repository task guides before using an API.

llms.txt describes the checked-in API in Rust spellings and names unsupported concepts instead of suggesting an equivalent that does not exist. It supplements the repository's task guides; those guides still require reading the implementation and tests when a task depends on behavior.

How the site serves it

A Next.js route handler reads the repository file once at module scope and exports the route as force-static, so next build prerenders the response on the build machine — where the Rust checkout sits next to the web app — and the deployed site serves static bytes without needing the repository at request time.

The site is deployed under the base path /herogpui, so the canonical URL is https://porabuild.com/herogpui/llms.txt; in local development it is simply /llms.txt. Either way the response body is the repository's llms.txt verbatim, served as text/plain; charset=utf-8.