SpecUI

Agent prompts

Two autonomous prompts to install SpecUI in an existing app or start a new one with a coding agent driving the design end to end.

Two prompts. Paste, change the {{...}} placeholders if you want (or leave them and let the agent pick sensible defaults), and hand them to your coding agent. Neither asks questions — the agent reads the repo, derives a sensible design system, and runs validate --strict until the contract is clean. You can review and override afterwards.

Both assume the agent can run npx/npm and read/write files in your repo.

The one-liner versions

Existing app — paste this into Cursor, Claude Code, Codex, or any agentic tool that can run shell commands in your current repo:

Install SpecUI (a .specui/ design contract + CLI) into this repo and build out the design system autonomously, without asking me any questions. Steps: (1) detect the framework from package.json and pick the closest preset (web-app, mobile-app, marketing-site, dashboard-data-dense, or design-system-library); (2) run `npx @logicplanes/specui@latest init --name "{{My Product}}" --preset <chosen> --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) scan the existing code under src/, app/, components/, or wherever the UI lives, infer the brand voice and accent color from existing styles, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) for every UI component the app already ships, run `specui add component <name> --variants <…> --states <…>` and fill in each .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md from the actual implementation; (6) add any missing semantic tokens with `specui add token <path> <value> --theme light` (and `--theme dark`); (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, and keep .specui/ and the implementing code in the same commit.

New app — paste this to start from scratch with the design system first:

We are starting a brand-new application from scratch and the design system comes first. Build it autonomously, without asking me any questions, before any UI code is written. Steps: (1) scaffold the framework ({{Next.js + Tailwind | Vite + CSS modules | React Native | …}}) into ./{{my-product}}, cd in, git init; (2) run `npx @logicplanes/specui@latest init --name "{{My Product}}" --preset {{web-app | mobile-app | marketing-site | dashboard-data-dense | design-system-library}} --agents-md --agent-tools cursor --ci github`; (3) run `specui doctor` and report the result; (4) choose a coherent brand voice, accent color, typography stack, and density, then fill in .specui/01-brand-and-product.md, .specui/02-foundations-tokens.md, and .specui/TOKENS.yaml with a complete token set (color, type, spacing, radius, shadow, motion) for light and dark themes; (5) define the first three to five components we will actually need (e.g. button, input, dialog, card, navigation) — for each run `specui add component <name> --variants <…> --states <…>` and fill in .specui/components/<name>/SPEC.md, STATES.md, VARIANTS.md; (6) define one or two flow patterns (e.g. onboarding, destructive-confirmation) with `specui add pattern <name>` and fill them in; (7) `specui sync` then `specui validate .specui --strict` — fix every finding and re-run until it prints "SpecUI valid — no findings." (8) export tokens for the framework: `specui export --format {{tailwind | css | dtcg | json}}` and wire them into the framework config so code reads from the same source of truth; (9) commit .specui/, the framework scaffold, and the wiring in a single first commit. Print a short summary of what you created, the token set, and the component list. From now on, never write or modify UI code without first registering the component in .specui/, always run `specui validate .specui --strict` before considering any UI task done, add missing tokens with `specui add token` before using them in code, keep .specui/ and the implementing code in the same commit, and suggest a `specui add component` whenever I describe a UI feature that needs a new piece.

Why these prompts work

Both prompts encode the SpecUI loop as a single instruction the agent can follow end to end: register → validate → export → implement. The contract leads; the code follows. Because they don't ask questions, the agent gets to a clean validate --strict pass in one session — you review and override afterwards, not in the middle.

A few things they do deliberately:

  • They pick the preset themselves. The existing-app prompt scans the code to detect the framework and chooses the closest preset; the new-app prompt uses the {{...}} you set (or web-app if you leave it). You can override by editing the prompt.
  • They derive the brand from what's there. On an existing app, the agent reads your styles, Tailwind config, CSS variables, or whatever your stack uses, and infers the accent color, typography, and density from real values rather than asking.
  • They register every component they find. The existing-app prompt walks src/ / app/ / components/ so your contract reflects what's actually shipped — not what you remember shipping.
  • They enforce strict validation as the gate. specui validate .specui --strict is the last step before "done." If it's red, the task isn't done.
  • They install durable rules. The trailing "from now on" sentence is what turns a one-shot install into a project-wide habit the agent keeps following on every future task.

Tips

  • No {{...}} placeholders needed. The existing-app prompt has only one ({{My Product}}) — the agent will infer everything else. The new-app prompt has a few you can fill, but leaving them works (the agent picks sensible defaults).
  • Prefer MCP? If you've wired the SpecUI MCP server (specui mcp install-hook cursor), the agent can read the spec through the model context protocol directly — but these prompts work without it.
  • Already have a brand guide? Add one sentence to the prompt: "Read BRAND.md and derive all tokens from it."
  • Want it to ask questions after all? Delete the words "without asking me any questions" — the agent will interview you instead. The default is autonomous on purpose.
  • Pre-load the docs. Before pasting either prompt, you can pre-load the SpecUI docs into the agent's context by pointing it at https://logicplanes.github.io/specui/llms.txt (the index) or https://logicplanes.github.io/specui/llms-full.txt (every page as one markdown file).

Where to go next

  • Agents & MCP — how agents read .specui/, plus rules and skills
  • Quick start — the human-driven version of the same flow
  • Scenarios — monorepo, design-system repo, agent-first, shadcn
  • CI/CD — make validate --strict fail the PR

Agents & MCP

AGENTS.md, the .specui agent docs, custom rules and skills, and the specui MCP server.

CI/CD

Gate pull requests with specui validate, strict mode, and GitHub Actions.

Edit this page on GitHub
On this page

On this page

The one-liner versionsWhy these prompts workTipsWhere to go next