Set up your coding agent

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

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.

- 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.

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

@AGENTS.md

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:

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 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.

What the agent reads

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

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

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.

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.