AI agents

Mako ships version-matched documentation inside the mako-ui package. An AGENTS.md file at your project root points agents at those bundled docs, so they write real Mako code instead of inventing an API that looks plausible.

Agents have seen a lot of React component libraries, and Mako looks similar enough that they guess. Pointing them at the bundled docs fixes this at the source.

Step 1: Point agents at the bundled docs

When you install mako-ui, the documentation is bundled at node_modules/mako-ui/dist/docs/:

Copynode_modules/mako-ui/dist/docs/
├── index.md                      # entry point: rules, workflow, component index
└── references/
    ├── component-registry.md     # which component for which task
    ├── components/<name>.md      # one guide per component
    ├── rules/                    # styling, forms, composition
    ├── package.md · icons.md · fonts.md · portal-props.md

Create an AGENTS.md at the root of your project and paste this in:

Copy# Mako UI
 
Mako UI is Rubix's design system. Its API is its own: it does not match the React
component-library patterns in your training data, and it changes between major
versions. Read the guides bundled with the installed package before writing any
Mako code:
 
- Start at `node_modules/mako-ui/dist/docs/index.md`.
- One guide per component in `node_modules/mako-ui/dist/docs/references/components/<name>.md`.
- Styling, forms and composition rules in `node_modules/mako-ui/dist/docs/references/rules/`.
 
These docs match the version of `mako-ui` installed in this project. Upgrading
the package upgrades the docs.

Then point Claude Code at the same file, so you maintain one copy:

Copy@AGENTS.md

Most coding agents — Claude Code, Codex, Cursor, GitHub Copilot — read AGENTS.md automatically when a session starts. Already have an AGENTS.md? Append the block to it; the file is plain Markdown and the sections are independent.

Commit both files. Everyone on the project gets the same setup, and there is nothing machine-specific in the diff.

Everything above is a pointer, not a copy of the documentation. The detail stays in node_modules and is read on demand, so your always-on context cost is a few lines rather than 280 KB.

Step 2: Let the docs track the version

The docs live in the package, so they always describe the Mako you actually have. Upgrading mako-ui upgrades the docs in the same step — nothing to re-run, no drift between what your agent reads and what your components do. AGENTS.md only holds a path, so it never needs updating either.

This is the whole reason the docs ship in the package rather than only on this site. Once a breaking change lands, a model's training data contains both the old and the new API forever, and it cannot tell which one your project is on. Version-matched files on disk settle it.

Step 3: Read the docs over the network

For agents that fetch pages instead of reading node_modules:

Every page also carries a Copy Markdown button.

The component guides cite examples by id (p-dialog-1, p-accordion-4, …). Those examples are not part of the npm package, and a docs page fetched as Markdown returns the <ComponentPreview /> tag rather than the code — so /examples/<id>.tsx is how an agent reads one.

What the agent gets

Component guides. One reference per component — imports, the minimal pattern, worked examples, composition rules and the pitfalls specific to that component. The agent knows when to reach for Dialog over Sheet over Drawer, how to compose trigger-based overlays, and how to structure forms with Field.

Styling conventions. Tailwind v4 token usage, the semantic color system, icon sizing rules, data-slot selectors, --alpha() syntax, and the font variable contract.

Package usage. Entry points, what each one exports, and the theme and font setup.

The root index.md holds the core rules and an index of every component; per-component guides are read on demand, only when the task needs them. That keeps the always-on cost small while the detail stays one file away.