Skip to content
UI

AI agents

How coding agents find and use the design system, in this repository and in the apps that consume it.

Markdown

The design system is written to be read by coding agents as well as people. Everything an agent needs is plain text, versioned with the package, and reachable without a browser.

In an app that uses the package

The package ships its own documentation in node_modules/@zenoxai/ui/ai/:

File What
USAGE.md Setup, the rules (tokens, composition, accessibility) and which component to use for which job. Hand-written.
components.md Every export and its props, generated from the sources of the installed version.
components.json The same, as JSON.

Point the app’s agents at it. In the app’s AGENTS.md or CLAUDE.md:

## UI

Build UI with @zenoxai/ui. Before writing UI code, read
node_modules/@zenoxai/ui/ai/USAGE.md; for props, node_modules/@zenoxai/ui/ai/components.md.
Do not create a component the library already has.

Because the files come from the installed version, an agent never reads documentation for a newer API than the one the app has.

On this site

URL What
/llms.txt An index of every page, following the llms.txt convention.
/llms-full.txt Every page in one file.
Any page + .md The Markdown twin of the page, with each live example replaced by its full source. For example /components/button.md.
/registry.json The component registry of the documented version.

In this repository

AGENTS.md at the root is the source of truth for conventions, commands and what never to do. packages/ui/AGENTS.md and apps/docs/AGENTS.md add the rules for each package, and CLAUDE.md imports the root file for Claude Code. The checks that matter run locally with pnpm check and are enforced in CI, so an agent gets the same feedback a person does: lint rules for tokens and layers, browser tests, axe on every docs page, and commitlint on every commit.

Keeping it accurate

  • Props are documented once, with JSDoc in the component source. The registry, the API tables on this site and components.md all come from it.
  • USAGE.md is checked by a test: every module must appear in its table.
  • Token tables on the foundations pages are read from theme.css at build time.