Skip to content

For AI agents

Why this library is easy for coding agents — and how to point yours at it.

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.

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.

Was this page helpful?