# Agents

How coding agents read these docs and the source, and the rules they follow.

## Overview

Coding agents read the same guidance as people. This site serves every page as Markdown, and the library source documents every export, so an agent can work from the docs or from your codebase.

The rules on this page turn that guidance into requirements for generated UI, and type checks and lint rules verify what a tool can check.

## Point Your Agent at the Docs

Give your agent one of these entry points.

* **Agent Prompt:** The [Getting Started](/docs/introduction/getting-started#agent-prompt) prompt points your agent at the home page, which returns the page index.
* **Page Index (/llms.txt):** [The index](/llms.txt) lists every page in sidebar order, with its Markdown link and description.
* **Full Text (/llms-full.txt):** [One file](/llms-full.txt) holds every page's Markdown, each after a `---` line and a `Source:` URL.
* **Copy Page:** On wide screens, Copy page copies the page's Markdown, and View markdown opens it.
* **In the Package (dist/docs):** The package ships the Markdown for its version in a few files by topic, with an agent guide that holds these rules.

### Markdown Twins

Every page has a Markdown twin. The page URL returns the twin or the HTML page, depending on the request.

```sh
curl https://ds.tehq.dev/docs/components/button
```

* **Markdown Path:** A page path that ends in `.md` returns the twin, such as `/docs/components/button.md`.
* **Terminal Clients:** Requests from curl, Wget, HTTPie, and xh receive the twin at the page URL.
* **Agents and Crawlers:** Requests from a known AI agent or crawler receive the twin at the page URL.
* **Accept Header:** Ranking `text/markdown` or `text/plain` at or above `text/html` returns the twin.
* **Search and Previews:** Search engine crawlers and link previews still receive the HTML page.
* **Canonical Link:** Each Markdown response carries a canonical `Link` header to the HTML page.

### What Changes in Markdown

A twin keeps the page's text, headings, and tables, and turns interactive parts into plain text.

* **Do and Don't:** Each Do and Don't card becomes a plain paragraph in the twin, starting with **Do:** or **Don't:**.
* **Live Examples (tsx):** Each live example becomes a code block with its full source and a link to the example.
* **Source Links:** Component pages link to the source on GitHub, whose TSDoc documents every prop.
* **Setup Options:** Each setup option on Getting Started takes its own heading, so the agent reads every one.

## Documentation in the Source

Each public component and part carries TSDoc with its purpose, accessibility behavior, and a short example, so an agent in your codebase reads it without fetching this site. Check the type declarations too, since prop and default coverage is still growing.

```tsx
/**
 * An inline message tinted by `intent`. The `negative` and `warning`
 * intents render `role="alert"` and interrupt screen readers.
 */
export function Alert(props: Alert.Props) {}
```

## Rules for Generating Tempo UI

These rules are requirements, and so are the Guidelines, Content, and Accessibility sections of every page. If a request conflicts with a guideline, follow the request and point out the conflict.

### Use Library Components First

* **Catalog First:** Check the [Components](/docs/components) overview, which compares similar ones, before you write markup.
* **Intent First:** Choose each component by the job of its content, as [Building From Intent](/docs/foundations/intent) describes, not by the old markup.
* **Public Entrypoints:** Import `@tempoxyz/ds` on Web and `@tempoxyz/ds/mobile` in React Native, with icons from `/icons`.
* **No Rebuilds:** Don't rebuild a library component or swap in a raw Base UI primitive or another library.
* **Named Parts:** Build larger components from their named parts, such as `Dialog.Root` and `Dialog.Title`.

### Style With Tokens

* **Style Definitions:** Style your own markup with `style` and `variants`, grouped in a `namespace styles` block.
* **Tokens:** Set colors, spacing, type, and radii with tokens, such as `content.primary` and `'24'`.
* **Custom Values:** Mark the rare literal that no token fits with `!custom`, as in `'24rem !custom'`.
* **One Styling System:** Don't add utility classes or a separate stylesheet to UI built with the library.
* **Variable Scopes:** Components inherit variables, so apply `vars()` only to override values or fix a color scheme.

### Set Type With Few Sets

* **Component Type:** Let each component set the type of its parts. Pass text as children and don't restyle it.
* **One Set per Style (typography):** Set your own text with one `typography` set, never a separate family, size, or weight.
* **Few Sets per Screen:** Use at most five styles on a screen, and Pilat only for titles.
* **Expressive Sets:** Follow [Typography](/docs/foundations/typography#reserve-the-expressive-sets) before you use display, value, utility, or mono.

### Use Only Documented APIs

* **Documented Props:** Use only the props, parts, and values that a component page or its TSDoc documents.
* **Missing Pieces:** Build a missing variant or token locally with `style`, and flag it for a [proposal](/docs/introduction/faq#how-do-i-request-a-component-variant-or-token).
* **Installed Package:** Don't patch the installed package or target the class names that it generates.

### Follow the Guidelines

* **Guidance First:** Read a component's Guidelines, Content, and Accessibility before you use it, not only its examples.
* **Patterns:** Before you build a screen, read the patterns it uses, such as [Forms](/docs/patterns/forms) and [Tables and Lists](/docs/patterns/tables-and-lists).
* **Native Semantics:** Keep native semantics, and meet every item on the [Accessibility](/docs/foundations/accessibility#checklist) checklist.

### Write Copy to the Content Guidelines

* **Labels and Terms:** Use sentence case and verb-first button labels, as [Writing Style](/docs/foundations/content/writing-style#write-labels) describes.
* **Amounts and Addresses:** Format amounts with [Amount](/docs/components/amount) and a `currency` or `symbol`, and addresses and hashes with [Hex](/docs/components/hex).
* **Errors:** Write error messages that state the fix, as [Writing Style](/docs/foundations/content/writing-style#write-messages) describes.

## Checks

If a tool can check a rule, run it as a check.

* **Types (tsc):** Token names are typed, so an unknown token fails to compile.
* **Lint (@tempoxyz/ds/oxlint):** Checks styles, imports, accessible names, and hand-built components, as [Linter](/docs/foundations/linter) lists.

## Add Rules to Your Project

Add instructions like these to your project's AGENTS.md or CLAUDE.md file, so every agent session starts from the docs.

```md title="AGENTS.md"
## UI

- Build UI with Tempo Design System: `@tempoxyz/ds` on web, `@tempoxyz/ds/mobile` in React Native.
- Read https://ds.tehq.dev/llms.txt first. Before using a component, read its page as Markdown, such as https://ds.tehq.dev/docs/components/button.md.
- Treat each page's Guidelines, Content, and Accessibility sections as requirements.
- Choose each component by what its content means, not by the markup it replaces. Read https://ds.tehq.dev/docs/foundations/intent.md before you port a screen.
- Style with `style` and TDS tokens. Don't hardcode colors or spacing.
- Set text with one `typography` set, and let components set the type of their own parts. Use Pilat only for titles, and at most five styles on a screen. Read https://ds.tehq.dev/docs/foundations/typography.md before you style text.
- Read the pattern pages that a screen uses, such as https://ds.tehq.dev/docs/patterns/forms.md and https://ds.tehq.dev/docs/patterns/tables-and-lists.md.
- Write interface copy with the Content foundations, such as Writing Style.
```

## Writing for Agents

Keep documentation readable for both audiences.

* **Title and Description:** Start each page with a title and a one-sentence description of the page.
* **Shared Headings:** Use the same headings across pages, such as Overview, Guidelines, and Accessibility.
* **One Rule per Sentence:** Put each rule in its own sentence, so an agent can quote it on its own.
* **Do and Don't Cards:** Use Do and Don't cards for guidance, so their verdict survives in Markdown.

## Related

[Getting Started](/docs/introduction/getting-started)

Covers setup and the agent prompt.

[FAQ](/docs/introduction/faq)

Covers common questions.

[Components](/docs/components)

Covers the component catalog.

[Building From Intent](/docs/foundations/intent)

Covers choosing a component by the job of its content.

[Linter](/docs/foundations/linter)

Covers the lint rules that check library use.

[Voice](/docs/foundations/content/voice)

Covers how Tempo UI copy sounds.
