Using coding agents

How buttery helps coding agents build with it: instructions, a skill, every page as Markdown, and checks that say how to fix what fails.

buttery is built so coding agents get its rules right the first time: one vocabulary of props, types that reject wrong values, and checks whose messages say how to fix the problem. Point an agent at the files below before it writes any UI.

What an agent reads

• AGENTS.md

  At a project's root, it tells agents which docs to read, the rules that are never broken (tokens only, flow layout, the component contract, the motion rules) and the commands that check their work. Agents that read CLAUDE.md find it imported from there. An app made with create-buttery has one, and buttery init adds buttery's section to an app's own.

• The make-it-buttery skill

  .claude/skills/make-it-buttery/SKILL.md walks an agent through building or restyling a screen: read the system, list what's on the screen, map it to buttery from the top down, apply motion by rule, then check the result. AGENTS.md points agents without skills to the file.

• Every page as Markdown

  Each page of this site is Markdown at its address plus .md, llms.txt lists them all in the sidebar's order, and llms-full.txt holds every page in one file. A component's page gives an agent its props, examples and rules in one file.

  The packages ship the same docs for the version an app has installed, so an agent reads them with no network: @butteryui/core/dist/llms.txt lists every page, each a Markdown file under dist/docs/, and @butteryui/react/dist/manifest.json gives each component's import, props and examples, the examples as files under dist/examples/.

• An MCP server

  @butteryui/mcp answers an agent's questions about components and tokens for the version the project uses, starts pages from their patterns, and lints and checks what it builds. create-buttery and buttery init add it to each common agent's config, and MCP server sets it up by hand.

When a check fails

When something's wrong, the checks say what and how to fix it:

• expectButtery reports each layout problem with the element, the rule, the measurement and a fix, and buttery check --json writes them as JSON for an agent to read, on any page of the running app.
• Components warn in development with the fix in the message and a link to their docs, such as a dialog without a name.
• buttery's stylelint config names the token to use instead of a raw value.

This is one problem as expectButtery writes it, a link too small to tap on a phone:

[
  {
    "rule": "target-size",
    "a": "#settings > a",
    "message": "hit area is 146.3px × 19px, under 24 × 24",
    "fix": "Make the hit area at least 24 × 24: use a 28px or larger control size, or give small visuals a [data-bt-hit] child that extends the target without changing layout. Only links inside a sentence can be smaller.",
    "page": "settings",
    "viewport": "390x844",
    "theme": "light",
    "density": "comfortable",
    "engine": "chromium"
  }
]