Handbook
AI agents
The files and the links that give the rules of ferry-ui to an AI agent.
Handbook
The files and the links that give the rules of ferry-ui to an AI agent.
ferry-ui is for people and for AI agents. An agent gets the documentation as plain text from three sources.
| Source | Content | Location |
|---|---|---|
AGENTS.md | The full reference in one file. | The repository and the package. |
llms.txt | The list of the pages of this site. | /llms.txt |
| Markdown pages | One page of this site as Markdown. | The URL of the page, then .md. |
AGENTS.md is the reference for an agent that builds UI with ferry-ui. The package contains this file. An agent that works in your app reads it there.
node_modules/ferry-ui/AGENTS.md| Section | Content |
|---|---|
| 1. Rules | The rules to read before you write UI. |
| 2. App setup | The CSS, the providers and the router. |
| 3. Design language | The sizes, the space and the type scale. |
| 4. Tokens | Each token with its class and its CSS variable. |
| 5. Which component for which job | Tables that give the correct component for a need. |
| 6. Recipes | Full modules for the usual screens. |
| 7. Catalog | Each export with its props and its values. |
| 8. Accessibility | The parts that depend on your code. |
| 9. Do and don't | A list to review the result. |
| 10. Extending ferry-ui | The conventions for a change in the repository. |
In the repository, the CLAUDE.md file points Claude Code to AGENTS.md.
This site serves llms.txt. The file follows the llms.txt format.
The file lists each page with its description, in the groups of the sidebar. Each link opens the Markdown version of a page.
The repository has a second llms.txt file. It lists AGENTS.md, README.md and the Storybook pages.
Each page of this site has a View as Markdown link below its title. The address is the URL of the page with .md at the end.
/docs/components/button
/docs/components/button.mdIn the Markdown version, each demo is its source code and each props table is a Markdown table. Give this address to your agent when you work with one component.
An agent copies the snippets of AGENTS.md. A snippet with a type error gives the agent a wrong instruction. The repository has a script that finds these errors.
$ npm run check:docs| Check | Rule |
|---|---|
| Snippets | The script type-checks each tsx block of AGENTS.md, README.md and the Storybook introduction with the current sources. |
| Catalog | AGENTS.md must name each export of src/index.ts. |
Each snippet is one full module. It imports what it uses and declares its own data.
The script is scripts/check-docs-snippets.mjs. Run it after each change to a component or to AGENTS.md.
className.