---
title: For AI agents
description: "Why this library is easy for coding agents — and how to point yours at it."
sidebar:
  order: 5
---

Agent-friendliness is a design requirement here, not marketing. Two things
make a component library easy for a coding agent: **the source is in the
repo** (the agent can read the real implementation instead of guessing at a
package's internals) and **every component follows the same conventions**
(one pattern learned, fifty components covered).

## The contract

Every component keeps the same shape:

- `variant` and `size` props where meaningful, typed as string unions.
- A `style?: StyleXStyles` prop, merged **last** via `stylex.props(...)` —
  caller overrides always win. No `className`, ever.
- All values come from tokens: colors/radius/shadows from
  `lib/tokens.stylex.ts` (themable), spacing/type/z/duration/easing/breakpoint
  scales from `lib/constants.stylex.ts`. No magic numbers or raw colors in
  styles.
- No `fontFamily` in component styles: components inherit the page's font
  (set on `<html>`, so portaled popups get it too). Kbd's `'inherit'` is the
  one exception: it undoes the reset's monospace `<kbd>`.
- Icons are `lucide-react`, sized with the `icon` styles from
  `lib/stylex-utils.ts` (`{...stylex.props(icon.md)}`) — no hand-drawn SVG,
  no `size` prop.
- Base UI state (open/checked/highlighted/transitionStatus) is styled with
  attribute-selector condition keys — the equivalent of Tailwind's
  `data-[state=open]:` selectors, declared inside `stylex.create`:

```tsx
backgroundColor: { default: 'transparent', '[data-popup-open]': colors.muted }
```

## AGENTS.md

`madeui init` appends a conventions section to your project's `AGENTS.md`
covering exactly these rules (tokens over literals, variants over escapes,
`[data-*]` condition keys, theming on `<html>`, the CSS layer gotcha). Agents
that read
`AGENTS.md` — Claude Code, Cursor, Codex, and friends — pick the rules up
automatically.

## Checking for updates

`npx @madeui/cli diff --json` reports every installed file as `same`,
`differs` (with a unified patch toward the registry), or `missing`, plus the
command that restores each item. `--exit-code` makes a difference fail the
run. The AGENTS.md section tells agents to read the patch before
overwriting: a file that differs may carry the project's own edits. See
[CLI → diff](/docs/cli#diff).

## Extending components: the rules agents follow

1. **Add a variant, don't fork.** New look = new entry in the component's
   variants map + the type union, using tokens.
2. **Layout tweaks go through `style`.** One-off spacing/width belongs at the
   call site, not in the component.
3. **Never hardcode values.** If a token is missing, add it to the token
   files — that keeps theming intact.
4. **Registry JSON is generated.** Component source is the source of truth;
   nothing edits `public/r/*.json` by hand.

## Why compile-time styles help agents

StyleX styles are plain typed JavaScript objects co-located with the
component. An agent editing `components/ui/button.tsx` sees the complete
style surface in one file, gets type errors for invalid properties, and
cannot leak styles into other components — there are no global class-name
collisions to reason about.

## Pointing an agent at the docs

Each component page documents only what this library adds; everything else
links to the Base UI reference. The docs are static and crawlable, and every
example is a standalone `.tsx` file the agent can copy verbatim.