Documentation · Auis Design

Overview

Auis Design is a code-native design builder. The design system, the screens, the UX flows and the review process all live in your repository, and AI agents (Claude Code, Codex, Cursor) do the building under rules written as skills. You keep the final word: an agent's change is done only when you approve it.

A new Auis project gives you:

A living styleguide at /auis/styleguide: tokens, foundations and components rendered from the real code.
Review Mode: drop visual comments on any screen; they become a local queue that agents resolve, and you approve or reject the result.
Edit Mode: non-destructive visual edits (text, tokens, variants, icons) that agents turn into real code.
UX Flows as code: a hub at /auis/ux-flow of navigable flow diagrams that are React pages, with comments, structural suggestions and multi-scenario views.
State Mode: every registered screen in every state, side by side at /auis/states, driven by URL parameters.
Agent skills: execution contracts that make any agent reuse components, respect tokens and register what it builds.

The template is Next.js (App Router), Tailwind CSS v4 and shadcn/ui, desktop-first. That is the shape of a new project, not a requirement for yours: the skills and the rulebook are plain files and work in any repository.

Requirements

Node.js 20 or later, and npm (or pnpm, yarn, bun).
An AI coding agent for the full experience: Claude Code, Codex or Cursor. The builder UI runs without one, but the skills are the point.
Optional: the Figma MCP server, for the flow and design import skills.
In an existing app, the builder UI needs React 18 or later.

Quick start: a new product

One command unpacks the template, renames the project to yours, runs git init with a first commit and installs dependencies. The install generates the agent skill trees.

npx @auis/cli@latest my-product

cd my-product
npm run dev            # http://127.0.0.1:3000

Then open /auis/welcome, or ask your agent to run /auis-setup. It walks you through your project name, a one-line description of your product and your logo, and then sets up brand, tokens and voice.

Prefer a clone? That works too:

git clone https://github.com/gregoriombp/AuisDesign.git my-product
cd my-product && npm install && npm run dev

Adding Auis to an existing product

See what Auis can do in your repository

npx @auis/cli@latest doctor

doctor reports, capability by capability, what Auis can do in that codebase, what runs degraded and what is unsupported, each with the reason and the alternative. It never writes, installs or asks. --json gives the full report.

Install Review

In a Next.js App Router app, init asks what to install as a checkbox menu of every module. Review (pins, comments, the drawer and agent mentions) is the one that installs today; State Mode, Edit Mode, Styleguide and UX Flows are listed, dimmed, with the reason they cannot be picked yet.

npx @auis/cli@latest init --dry-run              # pick, then print what it would touch
npx @auis/cli@latest init                        # install
npx @auis/cli@latest init --only review --yes    # no menu, for CI and scripts

init writes one route file (app/api/review-bridge/[...path]/route.ts), two lines in your root layout, one dependency (@auis/next), a block in .gitignore and a .auis/ folder with the manifest and the comments (gitignored). It never touches AGENTS.md, globals.css, tsconfig.json or your components, and the review chrome brings its own scoped styles, so your pages look exactly as before.

Remove it

npx @auis/cli@latest uninstall

uninstall reads the manifest and restores every file it edited. Your comments move to ~/.auis/review-bridge-backups/ instead of being deleted, unless you pass --purge.

CLI reference

The CLI is @auis/cli, and the binary it installs is auis. Run it with npx @auis/cli@latest; there is no unscoped auis package, so npx auis does not work.

Commands

Command	What it does
`npx @auis/cli@latest [directory]`	Scaffold a new project (create and new are the same command). With no directory it asks for one (auis-app with --yes); . means the current directory.
`npx @auis/cli@latest doctor [directory]`	Read an existing repository and report what Auis can do in it. Writes nothing.
`npx @auis/cli@latest init [directory]`	Pick modules and install them into an existing Next.js App Router app.
`npx @auis/cli@latest uninstall [directory]`	Reverse init from .auis/manifest.json.

Flags

Flag	Applies to	What it does
`-r, --ref <ref> (--branch)`	create	Branch, tag or commit of the template (default: main).
`--pm <npm\|pnpm\|yarn\|bun> (--use)`	create, init	Package manager (default: detected).
`--no-install (--skip-install)`	create, init, uninstall	Skip installing dependencies.
`--no-git (--skip-git)`	create	Skip git init and the first commit.
`--force`	create, uninstall	create: scaffold into a directory that is not empty. uninstall: also remove files you changed since init.
`--json`	doctor	The full report as JSON, without the banner.
`--only <a,b>`	init	Install these modules and skip the menu (review, states, edit, styleguide, flows; only review installs today). A module that cannot install says why and nothing is written.
`--dry-run`	init	Print what it would touch, write nothing.
`--purge`	uninstall	Delete the comments instead of moving them to ~/.auis/review-bridge-backups/<project>/.
`-y, --yes`	create, init	Take the defaults, never prompt (init: every module that installs here).
`-h, --help`	all	Show usage.
`-v, --version`	all	Print the CLI version.

Builder surfaces

The Review Bridge, the Flow Bridge and the State Mode API are same-origin Next.js routes, so npm run dev is all you need. With the dev server running, open:

Surface	Route
Welcome and first-run setup	`/auis/welcome`
Styleguide (design system)	`/auis/styleguide`
Review Bridge dashboard	`/auis/review-bridge`
Review inbox	`/auis/styleguide/review`
UX Flow hub	`/auis/ux-flow`
State Mode matrix	`/auis/states`
Projects workbench	`/auis/projects`
Builder roadmap	`/auis/roadmap`

The repository ships a neutral, documented first layer: the foundations and components the builder itself is made of. Your product's own components start empty and grow through the component and page skills.

Starting your own design system

Each step is a skill your agent runs. Brand, tokens and voice are the three things Auis never invents for you.

auis-setup: the recommended first move. A guided orchestrator that runs the three creators below in order (brand, tokens, voice), checking in between each.
auis-brand: your app name, one-line positioning and logo, wired into the app chrome.
auis-foundation: hand it a visual reference (screenshot, Figma URL, Dribbble or Behance capture) and it extracts colors, typography, spacing, radius and shadows into globals.css. The only skill allowed to create tokens.
auis-voice: hand it your product (an app, a site, a tone-of-voice document, or six answers) and it fills PRODUCT_CONTEXT.md with your language, voice and vocabulary.
auis-component: checks the shadcn registry, wraps primitives into Au* components and registers each one in the styleguide.
auis-page: full pages from a screenshot, Figma URL, wireframe or written description, mapping every element to existing components first.
auis-flow and auis-create-ux-flow: feature flows as navigable diagrams tied to real routes; auis-update-states registers each screen's states for State Mode.
auis-ux-writing: makes every string on a screen sound like your product.
Review Mode and auis-review-bridge-solve: comment visually on the running app, agents resolve the queue, you approve. You can also mention @claude or @grok in a comment to hand it to that agent directly.
auis-audit: verifies every component used in the app is documented in the styleguide.

Full walkthrough: Getting started.

Skills

Skills are the execution contracts agents follow. Their source of truth is skills/<capability>/<name>/SKILL.md, with a Codex variant where Codex differs. The .claude/skills/ and .agents/skills/ trees are generated from it; never edit them.

They cover six capabilities: design system (including State Mode), UX flows, bridges (review, flow, edit, project), build and handoff, content, and support. The recommended core is auis-setup, auis-brand, auis-foundation, auis-voice, auis-component, auis-page, auis-flow, auis-audit and auis-handoff. The full matrix is in the skills catalog.

Project commands

Command	What it does
`npm run dev`	Dev server on 127.0.0.1 (predev syncs the skills).
`npm test`	Unit tests for the app, the scripts and the kit.
`npm run build / typecheck / lint`	Build, types and lint.
`npm run ds:check`	Design-system lint: hardcoded values, hand-rolled overlays. Takes file paths and --json; exits 2 on findings, 1 if the scan fails.
`npm run ds:hook -- on`	Optional, off by default: run ds:check as Claude Code hooks while an agent works. off removes it; status reports it.
`npm run skills:sync`	Regenerate the agent discovery trees (.claude/skills, .agents/skills).
`npm run skills:catalog`	Regenerate skills/registry.json and skills/CATALOG.md.
`npm run states:pdf`	Print the State Mode matrix to a PDF (needs a Chromium).

Architecture

AGENTS.md: the rulebook every agent follows (the Au* prefix, the shadcn wrapper flow, tokens are sacred, the component lookup order).
AUIS.md: the mental model and the surfaces.
PRODUCT_CONTEXT.md: the template for your product's voice and vocabulary, read by the writing skills.
docs/ARCHITECTURE.md for engine internals, and docs/component-map.md for the "need X, use Y" index.

Security

The bridges are same-origin routes of the dev server, which binds to 127.0.0.1 only. Never expose it on a network or bind it to 0.0.0.0. Runtime data folders are gitignored. Set BRIDGE_AGENT_TOKEN only on a deployment that must accept agent writes over the network.

Contributing and support

Pull requests are welcome. Read CONTRIBUTING.md and AGENTS.md first; participating means you agree to the Code of Conduct. Questions and bugs go to GitHub issues.