# AGENTS.md — <DESIGN SYSTEM NAME>

<!--
  Template from https://www.designsystems.one/ai-ready/agent-files
  Fill every <ANGLE BRACKET>. Delete what does not apply. Keep it short:
  this file is loaded into context on every single turn, so every line you
  add is a line you pay for forever.

  Target: under 200 lines. If a section is a multi-step procedure, or only
  matters in one part of the repo, it does not belong here — move it to a
  skill or a path-scoped rule. See docs/agent-files-README.md.
-->

## What this package is

<ONE PARAGRAPH. What the system is, who it is for, and the one thing an agent
most needs to know before touching it.>

Install: `<npm i @scope/design-system>`
Docs: `<https://example.com/docs>`
Machine interface: `<MCP endpoint, or CLI command, or "none yet">`

## Before you write any UI code

1. Read the component allow-list below. If the component you want is not on
   it, it does not exist. Do not create it — ask.
2. Use tokens, never literal values. See "Tokens" below.
3. Run `<pnpm typecheck>` before you claim a task is done. The compiler is the
   governance layer; a passing build is the only evidence that counts.

## Components that exist

<!--
  Generate this list from the package's real exports. A hand-maintained list
  rots, and a rotted list is worse than none — agents faithfully reproduce
  documented names that no longer exist, which is a build failure you wrote
  yourself. Suggested: a CI check asserting every name here is exported.
-->

| Component | Import | Notes |
|---|---|---|
| `<Button>` | `import { Button } from '@scope/design-system'` | `<variant: 'primary' \| 'secondary' \| 'ghost'>` |
| `<TextField>` | `import { TextField } from '@scope/design-system'` | `<label is required>` |

**There is no `Box`, `Stack`, `Container`, or `Flex` in this system.** Models
reach for these names because other libraries have them. Use `<your layout
primitive>` instead.

## Components that used to exist

| Removed | Use instead | Since |
|---|---|---|
| `<OldThing>` | `<NewThing>` | `<v4.0.0>` |

## Tokens

Never write a literal colour, spacing value, radius, or font size.

- Wrong: `color: #FF3B30`, `padding: 16px`, `border-radius: 8px`
- Right: `color: var(--color-text-danger)`, `padding: var(--space-4)`

Full token list: `<path or endpoint>`.

A hardcoded hex looks correct in light mode and is wrong in dark mode and
wrong again after the next rebrand. This is the most common failure in
agent-written UI and the easiest to prevent.

## Composition rules

- `<ComponentA>` may only contain `<ComponentB>` and `<ComponentC>`.
- `<Never nest X inside Y.>`
- `<Forms must be wrapped in Form; standalone fields will not submit.>`

## Accessibility preconditions

These are not suggestions; a PR that misses them does not merge.

- Every interactive element has an accessible name that says what it does.
  `aria-label="Submit"` is not an accessible name, it is a placeholder.
- Every `<img>` has alt text describing the content, or `alt=""` if decorative.
- Link text makes sense read alone. "Learn more" does not.

Automated accessibility linters pass all four of the above when they are
wrong, because these are semantic failures rather than structural ones. Check
them by reading, not by running axe.

## Commands

| Command | Purpose |
|---|---|
| `<pnpm dev>` | `<Start the dev server. Use this while iterating.>` |
| `<pnpm typecheck>` | `<Required before finishing any task.>` |
| `<pnpm lint>` | `<Includes the token and component rules above.>` |
| `<pnpm build>` | **`<Do not run during an agent session>`** — `<reason>` |

## What not to do

<!--
  Name the specific mistake. Prohibitions that name the hallucination
  outperform generic rules, because the model can pattern-match against them.
  "Follow our conventions" is unenforceable; "there is no Box component" is.
-->

- Do not invent prop values. `<variant>` accepts exactly the values listed
  above and the type will reject anything else.
- Do not add a new dependency without asking.
- Do not edit files under `<generated/>` — they are regenerated from `<source>`.
- Do not write your own version of a component that already exists. Search
  first: `<rg "export function" src/components>`.