For AI agents
Echo is built to be used through a coding agent. In a project, you don't brief it or connect
anything: init makes the project tell the agent it's an Echo project, and gives it a way to ask
and a check that catches it when it drifts.
npx echo-ui-cli initWhich way in
| Where you work | What to use |
|---|---|
| A project, with an agent that runs commands (Claude Code, Codex, Cursor, v0, Bolt) | init: the Echo block, the skills, the check hook and the Stop gate. The rest of this page. |
| A chat in Claude or ChatGPT | The plugin: the hosted server and Echo's three skills, in one install. |
| A tool that connects only to an MCP server on the web (Lovable, Claude Design, ChatGPT on the web) | The hosted server: the tools, without the skills. |
| A tool that only takes text | llms.txt, a component's Copy for AI agent, or a DESIGN.md from the generator. |
What the agent reads
init writes a short Echo block into CLAUDE.md or AGENTS.md, whichever your project has.
Claude Code, Codex and Cursor read those at the start of every session, on their own. It's the whole
of it, between Echo's markers:
<!-- echo-ui:start --> ## Echo UI This project's UI is built with Echo: tactile React components copied into `components/echo/` (see `echo.json`), on the grammar in the `echo-ui-core` package. - Use Echo's component for every job it has. Never imitate one with raw elements or its classes. - Before using a component, ask: `npx echo-ui-cli which "<the job>"`, then `npx echo-ui-cli docs <name>`. Add one with `npx echo-ui-cli add <name>`. - Set up once: import `components/echo/echo-theme.css` from the root layout or global CSS, give `body` `background: var(--echo-well); color: var(--echo-text); font-family: var(--echo-font-sans)`, wrap the app in `SoundProvider` from `echo-ui-core/sound`, and put `<EchoCheck />` from `echo-ui-core/check` in the root layout. - Style only with `var(--echo-*)`. Never write a colour value: the theme sets them all. - The packages are `echo-ui-cli` and `echo-ui-core`. There is no `echo-ui` or `echoui` package: never install one. - Accessibility: every control has a name: `label`, `aria-label` or `aria-labelledby` (the types require it). - Accessibility: a form error goes in words, in the field's `error`; never colour alone. - Accessibility: announce with `toast()` from `useToast()`, under one `<Toaster>`. - Accessibility: never remove a focus ring, shrink a target below 24×24px, or put `aria-hidden` on something focusable. - Building a screen? Read `DESIGN.md` (its look and decisions), then follow `.claude/skills/echo-ui/SKILL.md`. Every choice comes from a decision, Echo's default or the builder: when unsure, ask the builder. - A look of its own: a moodboard becomes a style with `.claude/skills/echo-design-eye/SKILL.md`, Style Fit picks one with `.claude/skills/echo-style-fit/SKILL.md`; `npx echo-ui-cli style set <setting> <value>` moves one setting. - After changing UI, run `npx echo-ui-cli check`, then `npx echo-ui-cli test` with the app running, and fix what they find. Only the builder keeps a slop-police finding. <!-- echo-ui:end -->
More goes in with it: DESIGN.md, this project's look in Echo's terms; a hook that runs Echo's
check on every file the agent writes or edits; and three skills. The Echo skill has the steps for
building a screen from Echo's reference screens, and for changing one setting of the look with
style set. Design Eye reads a moodboard into a style, and Style Fit picks the style a product
wears (Styles). What Echo puts in your project lists all
of it, and how each one comes back out, and The workflow shows them in use.
How it asks
Before it uses a component, the agent asks the CLI, several questions in one call. The answers come from a copy of the catalog kept in the project, so they're instant and work offline.
npx echo-ui-cli which "a settings toggle" "confirm a delete" "an image carousel"
npx echo-ui-cli docs switch alert-dialogwhich names the item for each job, and says plainly when Echo has nothing for it yet: a carousel
today, which is coming soon. docs gives each item's props, a working use with imports that resolve in your
project, what it needs for accessibility, and what not to do.
How it's caught
npx echo-ui-cli checkThe hook runs it after every edit, and the agent gets what it finds straight back: a colour
written by hand, a raw <button> where Echo has HardwareButton, a prop a component doesn't take,
a control without a name, a div with a click and no keyboard. Each line says the Echo way to do
it. check exits with 1 when it finds something, so it can run in CI too; nothing requires it.
The hook runs in Claude Code. In Codex and Cursor, the Echo block tells the agent to run check
itself after changing UI.
Some things show only once the page runs: a colour as the browser paints it, a control named at
runtime, text against whatever ends up behind it. <EchoCheck />, put once in the root layout,
prints an Echo check · line to the browser console for each, in development, and the skill tells
the agent to read them. Next.js 16's dev server prints them in its terminal too. With no browser,
check --url runs the same check headless:
npx echo-ui-cli check --url http://localhost:3000/invoicesAnd a screen can pass every rule and still look wrong: keys at three heights, a feature cut off with "…", two cards in three columns, a glow on a button. The design tests measure those on the rendered page, and axe runs its WCAG A and AA rules on the same page, for what the agent wrote outside Echo's parts. In Claude Code the agent can't call the screen done until they pass: when it tries to stop, a Stop gate runs them on the pages it changed and hands back what they find, each with the one change that fixes it.
Echo's design tests found 2 things to fix on /invoices before this is done: /invoices alignment div.echo-hw "Send": "Send" sits 312px from where the rest of its column starts, and isn't centred in it either. Start it where the content starts, under the title (an Echo Card's footer does), or centre it if everything above it is centred. Change only where the action sits, not the action, the text or the colours. /invoices icons svg: the icons in this navigation are different sizes: "Clients"'s is 20px and the rest 16px. Make it 16px like the others (`--echo-icon-*` has the steps). Change only that icon's size.
Elsewhere, npx echo-ui-cli test runs them, and the Echo block tells Codex and
Cursor to run it last.
Watch the running page has what it finds.
Tools without a terminal
Where init can't run, the same records are published in forms you can hand an agent yourself.
They are generated from the same source as these pages, so an agent and a person reading about a
component get the same description, props and anti-patterns.
| Use | When |
|---|---|
| Copy for AI agent | You are working on one component. The button on its page copies its full record as markdown; paste it into the chat. |
/llms.txt | The agent needs the overview: what Echo is, the setup, and one line per item. Small enough to paste. |
/llms-full.txt | The agent should know everything. The overview plus every item's full record. |
/e/index.json | You are building a tool and need versions. Every item, its version and its dependencies. |
/r/catalog.json | You are building a tool and need the docs. Structured data for every item and every token. |
| MCP server | The agent should look things up itself: components, the check, and styles. Run it on your machine, or connect your tool to the hosted one. |
All of them are published at https://echo-ui.com, so an agent that can fetch URLs can be given
the address instead of the content.
In each tool
What each one can take, checked against its own documentation in September and October 2026:
| Tool | What works |
|---|---|
| ChatGPT, claude.ai | No terminal. Install Echo's plugin, or add Echo's hosted MCP server as a custom connector (a remote MCP server) for the tools alone: the agent finds components and checks its code, and makes, picks and wears a style with you in the chat. The build then moves to your code tool, where npx echo-ui-cli init --style <name> sets the project up in that style. |
| v0 | It has a terminal. Run npx echo-ui-cli init there, or ask v0 to, then add what you need. v0 doesn't say it reads AGENTS.md, so paste Echo's block from it into one of v0's Instructions. |
| Bolt | It has a terminal too: init, then add. Upload the skill init writes, .claude/skills/echo-ui/SKILL.md, as a Bolt skill. |
| Lovable | No terminal. Download DESIGN.md for your seed and paste it into Project knowledge, and put the theme's CSS in the project. Or run init and add on your own machine, in the repository Lovable syncs with GitHub, and push: Lovable reads the Echo block in AGENTS.md from then on. |
| Claude Design | It doesn't run code. In Claude Code, in a project with Echo installed, /design-sync brings Echo's tokens and components in; or upload DESIGN.md. It hands the work back to Claude Code, where the CLI and its check run. |
The generator's DESIGN.md opens by telling an agent that does have a terminal to run init
instead, with your seed, so the file never replaces the components. Each of these connects only to
MCP servers hosted on the web, so give them Echo's hosted one, https://mcp.echo-ui.com/mcp: the same tools as
npx echo-ui-mcp, with nothing to install and no account. The MCP server page has the
tools and the setup.
Briefing an agent by hand
Start with this. It is the text the MCP server sends before any tool call:
A neo-skeuomorphic React component library you install into your own source tree with `npx echo-ui-cli`. Molded caps in recessed wells, emissive readouts, real press travel. Motion (GSAP) and sound (zero-dep WebAudio synth) are first-class token families alongside color and type.
Working rules:
- The Base UI package is `@base-ui/react` (per-component imports, e.g. `@base-ui/react/dialog`), NOT `@base-ui-components/react` (the old name). Training data may be stale.
- Set the project up once with `npx echo-ui-cli init`. It installs `echo-ui-core` (and `echo-ui-cli` as a dev dependency), writes `echo.json`, `echo-lock.json` and `echo-theme.css`, adds a marked Echo block to CLAUDE.md or AGENTS.md, a check hook to .claude/settings.json and three skills (building with Echo; Design Eye, which reads a moodboard into a style the project can wear; and Style Fit, which picks the style it wears), and prints the lines to paste. It never edits your source code, and `add` refuses to run before it.
- Components render with no colour until the theme is on the page. `init` writes `echo-theme.css` into the Echo folder — import it once from your global CSS or your root layout (or call `createEchoTheme().css` from `echo-ui-core/theme` to build it at runtime). Give the page the device's ground (`body { background: var(--echo-well); color: var(--echo-text); font-family: var(--echo-font-sans); }`), dark or light as the chassis makes it, and wrap the app in `SoundProvider` from `echo-ui-core/sound` — without it every component is silent. It starts muted until the person turns sound on, and remembers their choice; `defaultMuted={false}` starts with sound. Put `<EchoCheck />` from `echo-ui-core/check` once in the root layout: in development it says in the console what's still missing, and in production it renders nothing.
- Echo components are client components. In the Next.js App Router, a file that passes them a function (`onSave`, `onSubmit`, `onClick`) must start with `"use client"`.
- Echo is a REGISTRY, not an npm component package. Components are installed with `npx echo-ui-cli add <component>` and then live in the consumer's own source tree, importing each other by relative path inside one Echo folder. Never suggest `npm install` for a component. The one npm package is `echo-ui-core`, the grammar they all import (theme, sound, motion, tactile, presence).
- Installed files still receive Echo's later fixes. `npx echo-ui-cli diff` reports every installed item as up to date, behind, edited, or edited and behind; `npx echo-ui-cli update` brings them forward and merges Echo's change into files somebody edited; where an edit and Echo's change meet in the same lines, it leaves that item and prints the lines between git's conflict markers, to bring together before running it again. Never tell a user to re-run `add --overwrite` to upgrade — that discards their edits without showing them what it is discarding.
- Style only through the Layer-3 semantic vars (`var(--echo-*)`) from `createEchoTheme`. Never hardcode a hex, and never invent a token name — call get_tokens for the real list.
- Read a component's anti-patterns before using it. They exist because the obvious thing is wrong for this material system (a screen readout does not ease smoothly; severity is not red/amber/green).
Accessibility is part of the grammar, not a review step. Echo guarantees WCAG 2.2 AA, and these are the parts a consumer can still get wrong:
- Every control needs a name. `Switch`, `Checkbox`, `Slider`, `Segmented`, `Select`, `RadioGroup` and `Progress` take `aria-label` (or `aria-labelledby` pointing at visible text); `Field`, `Textarea` and `OtpField` take a visible `label`. Without one they do not compile.
- An icon-only `HardwareButton` (`iconOnly`) needs `aria-label`: it has no text to read.
- Forms: put the help text in `description` and the problem in `error`, both on the field. They are linked to the input and set `aria-invalid` for you. Never signal an error with colour or a red border alone.
- Announcements: mount `<Toaster>` once and call `toast()` from `useToast()`. A message rendered into the page when it happens is usually never announced.
- Sign-in: `Field` with `autoComplete` (`email`, `current-password`), and `OtpField` for a one-time code — it allows pasting, which people rely on.
- State is never colour alone: Echo has one accent, and its components already carry state in shape and words. Do not add a red for danger; use `AlertDialog`, which asks before anything destructive.
- Do not remove a focus ring, shrink a target below 24×24px, or set `aria-hidden` on something focusable.
Every component is tested against WCAG 2.2 AA: axe, keyboard, focus-visible, forced-colors, target-size, reflow — and each item's `/e/` record carries the same block. Not covered: screen-reader: not yet verified by a person.Then, for the task at hand:
- Name the components. "Use Echo's Modal and Field" gets better results than "make a dialog".
- Ask it to read before writing — the component record, or
get_component— especially the anti-patterns. - Keep it on the tokens. Every colour is a
var(--echo-*)role and every duration is a motion token; a hex code or a300msin its output is a sign it stopped reading. - Check the install. Components come from
npx echo-ui-cli add …, nevernpm install, and the project has to be set up first. The one npm package isecho-ui-core, the grammar every component imports.