# Set up your coding agent (/ui/docs/react/agents)



Coding agents are good at React and bad at guessing a design system's rules. Left
to itself, an agent writes `bg-gray-100` instead of `bg-background-muted`, forgets
the `@source` directive and then writes CSS to "fix" the unstyled components, and
rebuilds a `Dialog` it never noticed the library already ships.

None of that is a knowledge problem. Everything an agent needs is published - it
just isn't in the one place agents reliably read: **your project's own agent
instructions file.** Two minutes of setup fixes it.

## Add the rules to your project [#add-the-rules-to-your-project]

Paste this into your `AGENTS.md`. Most agents load it automatically at the start
of every session - Claude Code, Cursor, Copilot, Codex, Zed and Windsurf all read
`AGENTS.md`, and Claude Code also reads `CLAUDE.md`.

```markdown
- Tailwind CSS v4 only. Do NOT create a `tailwind.config.js` - v4 config lives in CSS via `@theme`.
  If the project is on v3, convert unsupported syntax rather than downgrading the components.
- Scan the library for class names or everything renders unstyled: `@source '../node_modules/@appica/ui-react/dist';`
  in the stylesheet that imports Tailwind. The path is relative to that stylesheet - count the `../`
  needed to reach the project root. A bare package name resolves to nothing and fails silently.
- React 19 is a hard requirement. No `forwardRef` - `ref` is a plain prop.
- Import from the subpath, one component per import:
  `import { Button } from '@appica/ui-react/button'`.
- Never write hex colors, px radii, or duration literals. Use the role-based tokens:
  `bg-background-muted`, `text-foreground-intense`, `border-border-strong`, `var(--radius-md)`.
  Full list: https://appica.dev/ui/docs/react/colors.md
- Never write hue-based utilities (`bg-gray-100`, `text-slate-600`). The palette is organized by
  role, not hue.
- Prefer v4 variant syntax (`*:`, `**:`, `data-*:`, `not-*:`) over `[&_...]` arbitrary selectors.
- For a link styled as a button, put `buttonVariants(...)` on the `<a>` - never `<Button render={<a/>}>`.
- Put `className` overrides on the wrapper component, not on the JSX passed to `render`.
- Do not hand-roll a component that exists in the library. Check the component list first:
  https://appica.dev/llms.txt
- Every documentation page is served as clean markdown at `<url>.md` - fetch that, not the HTML.
```

> **Tip - Already have an AGENTS.md?:**
>
> Append it under a heading of its own, like `## Appica UI`. Agents read the whole file, and a named
> section keeps the rules attributable when you later add rules for something else.

If your agent reads `CLAUDE.md` rather than `AGENTS.md`, a one-line pointer keeps
a single copy:

```markdown title="CLAUDE.md"
@AGENTS.md
```

## Point it at the docs [#point-it-at-the-docs]

The rules cover how to write Appica UI. For *what* the library contains - every
component, its props, its examples - add one more line so your agent fetches pages
on demand instead of guessing:

```markdown title="AGENTS.md"
Appica UI component index (fetch before using a component you haven't used before):
https://appica.dev/llms.txt
```

That file is an [llms.txt](https://llmstxt.org) index: the rules above, then a
linked list of every documentation page. Each link points at clean markdown, so an
agent that follows one gets roughly 8 KB of prose and tables rather than a rendered
HTML page.

> **Warning - Don't paste the whole documentation into context:**
>
> Every page on this site is available as markdown by appending `.md` to its URL - the
> [Button page](/ui/components/react/button) is also
> [`button.md`](/ui/components/react/button.md). Let your agent fetch the one page it needs. There is
> deliberately no bulk `llms-full.txt`: at \~92 pages it would consume most of a context window and
> crowd out your actual code.

## What the agent reads [#what-the-agent-reads]

Three sources, in the order an agent tends to reach them:

| Source                                    | Where it lives                   | What it's for                                                                   |
| ----------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| Your `AGENTS.md`                          | Your repo root                   | The rules above. Loaded every session, no fetch required.                       |
| `agent-rules.md`                          | `node_modules/@appica/ui-react/` | The same rules, shipped with the package, so they match your installed version. |
| [`llms.txt`](https://appica.dev/llms.txt) | This site                        | The page index. Fetched on demand.                                              |

The copy inside `node_modules` is the authoritative one - the block on this page
and the rules in `llms.txt` are both generated from it. If you upgrade Appica UI
and the rules change, the package tells you before this site does.

## Verify it worked [#verify-it-worked]

Ask your agent to build something small that exercises the two rules that fail
silently:

> Build a settings card with a heading, a description, a labeled text input, and a
> save button. Use Appica UI.

Check the result for three things:

* **Imports use subpaths** - `@appica/ui-react/button`, not `@appica/ui-react`.
* **No hue-based classes** - no `bg-gray-100`, `text-slate-600`, or hex colors.
  Colors should be roles: `bg-background-muted`, `text-foreground-intense`.
* **It renders styled.** If everything is unstyled, the `@source` line is missing
  or its path is wrong - see [Installation](/ui/docs/react/installation#configure-tailwind).

If the agent hand-rolled a card or an input instead of importing one, it didn't
load the rules. Confirm the file is at your repo root and that your agent reads
that filename.