AI agents
Use MiniDev UI with AI agents
MiniDev UI is written to be read by agents as well as people. Every component is one file with documented props, a Markdown page and a registry item, so Claude Code, Cursor, Codex and the rest can find the right piece, install it in one command and use it correctly the first time.
Quick start
No setup needed. Paste this into any agent at the start of a task:
Use MiniDev UI for the interface. Read https://ui.minidev.pro/llms.txt first, then https://ui.minidev.pro/docs/<name>.md for each component you use, and install with npx shadcn@latest add @minidev/<name>.
For work you repeat, install the rules file for your tool below so the agent knows the kit without being told, and add the MCP server so it can search components itself.
Setup by tool
Claude Code
1. Rules
Install the MiniDev UI skill. Claude loads it whenever you ask for UI.
mkdir -p .claude/skills/minidev-ui && curl -fsSL https://ui.minidev.pro/skill/minidev-ui/SKILL.md -o .claude/skills/minidev-ui/SKILL.md
2. MCP server
Add the hosted MCP server. Nothing to install.
claude mcp add --transport http minidev-ui https://ui.minidev.pro/mcp
Cursor
1. Rules
Save the rules file. It applies to .tsx, .jsx and .css files.
mkdir -p .cursor/rules && curl -fsSL https://ui.minidev.pro/rules/minidev-ui.mdc -o .cursor/rules/minidev-ui.mdc
2. MCP server
Add the server, or use the one-click link.
Add to Cursor{
"mcpServers": {
"minidev-ui": {
"url": "https://ui.minidev.pro/mcp"
}
}
}
Codex
1. Rules
Codex reads AGENTS.md. Append the MiniDev rules to it.
curl -fsSL https://ui.minidev.pro/AGENTS.md >> AGENTS.md
2. MCP server
Register the server in your Codex config.
[mcp_servers.minidev-ui]
url = "https://ui.minidev.pro/mcp"
Windsurf
1. Rules
Windsurf picks up AGENTS.md in the workspace.
curl -fsSL https://ui.minidev.pro/AGENTS.md >> AGENTS.md
2. MCP server
Add the server to Windsurf's MCP config.
{
"mcpServers": {
"minidev-ui": {
"serverUrl": "https://ui.minidev.pro/mcp"
}
}
}
GitHub Copilot
1. Rules
Append the rules to Copilot's repository instructions.
mkdir -p .github && curl -fsSL https://ui.minidev.pro/AGENTS.md >> .github/copilot-instructions.md
2. MCP server
In VS Code, add the server to the workspace, or use the one-click link.
Add to VS Code{
"servers": {
"minidev-ui": {
"type": "http",
"url": "https://ui.minidev.pro/mcp"
}
}
}
v0
Context
v0 has no local rules file. Start your chat with the line from Quick start, or open any registry item in v0 directly:
https://v0.dev/chat/api/open?url=https://ui.minidev.pro/r/dashboard-home.json
MCP server
A Model Context Protocol server, hosted at https://ui.minidev.pro/mcp (Streamable HTTP). It gives the agent the MiniDev catalogue and docs as tools, so it can look up the right component and its props without leaving the editor. Nothing to install, no account, no key.
claude mcp add --transport http minidev-ui https://ui.minidev.pro/mcp
Tools: search_components, list_components, get_component, get_example, get_design_rules and get_install_instructions. To run it locally over stdio instead (Node 18+), use claude mcp add minidev-ui -- npx -y minidev-ui-mcp, or command npx with args ["-y", "minidev-ui-mcp"] in any client.
Docs agents can read
Plain text and JSON at stable URLs. Point any agent at them, or paste them into a chat.
- /llms.txt
Install routes, house rules and a one-line index of every component (about 130 KB).
- /llms-full.txt
Every component in full: purpose, when to use, install, import, props, examples. Search it to pick components.
- /docs/button.md
One component's docs as Markdown: props, examples, related components. Swap button for any name.
- /r/button.json
The shadcn registry item: exact source, npm dependencies and MiniDev dependencies.
- /r/registry.json
The whole registry index, for tools that enumerate items.
- /r/styles.css
The token stylesheet every component reads. Needed once per project on the shadcn route.
Rules files
Three files with the same rules in the format each tool expects: how to install, which tokens to use, how buttons and links work, the spring presets, and the gotchas agents hit most.
AGENTS.md
Codex, Windsurf, Copilot, Jules, Zed and any tool that reads AGENTS.md
minidev-ui.mdc
Cursor project rules
SKILL.md
Claude Code skill
# MiniDev UI: rules for AI coding agents
Paste this into your project's AGENTS.md (or CLAUDE.md, .github/copilot-instructions.md). Source: https://ui.minidev.pro/AGENTS.md
MiniDev UI (https://ui.minidev.pro) is a free, MIT-licensed library of 500+ React components, page blocks and motion pieces for Tailwind CSS v4, built on Base UI. Every component is one file the project owns.
## Look it up before you write it
1. Find the component. Index and rules: https://ui.minidev.pro/llms.txt. Every component with a one-line description: https://ui.minidev.pro/llms-full.txt. If the `minidev-ui` MCP server is connected, ask it instead.
2. Read that component's docs before using it: https://ui.minidev.pro/docs/<name>.md. The exact source is in https://ui.minidev.pro/r/<name>.json.
3. Use an existing component or block before hand-writing markup. Use only the props the docs show. Never invent props, variants or sizes.
## Install
- This project's route decides the import path. `components.json` present: shadcn CLI. `minidev-ui-kit` in package.json: npm package. Do not mix them.
- shadcn CLI: `npx shadcn@latest add @minidev/<name>` (several at once: `npx shadcn@latest add @minidev/kpi-row @minidev/chart-card`). Long form: `npx shadcn@latest add https://ui.minidev.pro/r/<name>.json`. Files land in `components/ui/<name>.tsx`; import `import { KpiRow } from "@/components/ui/kpi-row"`.
- npm: `npm i minidev-ui-kit`, then `import { KpiRow } from "minidev-ui-kit/ui/kpi-row"`. Blocks: `minidev-ui-kit/blocks/<name>`. Motion pieces: `minidev-ui-kit/premium/<name>`. In Next.js add `transpilePackages: ["minidev-ui-kit"]`.
- Exports are named and PascalCase of the file name (`chat-thread` exports `ChatThread`). There are no default exports.
- Tokens, once per project. shadcn route: `curl -o app/minidev.css https://ui.minidev.pro/r/styles.css`, then `@import "./minidev.css";` after `@import "tailwindcss";`, and delete the `:root`, `.dark` and `@theme inline` blocks that `shadcn init` generated (they override MiniDev's tokens and turn the accent gray). npm route: `@import "minidev-ui-kit/styles.css";` plus `@source "../node_modules/minidev-ui-kit";` (path relative to the CSS file).
## Write code the way the kit does
- Colour: semantic tokens only. Surfaces `bg-bg`, `bg-surface`, `bg-raised`, `bg-sunken`, `bg-ink`, `bg-accent`. Lines `border-border`, `border-border-strong`. Text `text-fg`, `text-fg-muted`, `text-fg-subtle`, `text-on-ink`, `text-accent-fg`. Status `success`, `warning`, `danger`, `info`. Tints `bg-accent-soft`, `border-accent-line`. Never hex, never palette steps (`blue-500`), never `bg-white` or `bg-black`, never opacity variants on cards (`bg-surface/80`).
- Buttons: `<Button>` is the ink primary. `variant="accent"` for the one brand action, `"outline"` secondary, `"ghost"` quiet, `"soft"` tinted, `"secondary"` filled neutral. Sizes `xs`, `sm`, `default`, `lg`, `xl`. Icon-only: `<IconButton aria-label="…">`.
- Links that look like buttons use Base UI's `render` prop, not `asChild`: `<Button render={<Link href="/pricing" />}>See pricing</Button>`.
- Depth: only `shadow-xs`, `shadow-sm`, `shadow-raised` (cards), `shadow-key` (outline controls), `shadow-ink` (solid buttons), `shadow-md`, `shadow-lg`, `shadow-overlay` (menus, dialogs). No `shadow-[...]`, no `backdrop-blur` on surfaces.
- Radius: controls `rounded-lg`, cards `rounded-xl`, overlays `rounded-2xl`. Nested radius = outer minus padding.
- Spacing and sizes are even numbers on a 2px grid. Control heights 28, 32, 36, 44, 48px.
- Numbers use `tabular-nums`. Headings get negative tracking; body text does not.
- Dark mode is the `dark` class on `<html>`. Never branch on theme inside a component.
- Materials: `data-material="hairline | glass | metal | paper"` on `<html>` or any element. They work only through the tokens above, which is why the token rules matter.
- Motion: springs from `motion/react`, never ad-hoc durations for movement. `snappy { type: "spring", bounce: 0.18, duration: 0.42 }` for toggles and tabs, `morph { type: "spring", bounce: 0.16, duration: 0.5 }` for size or shape changes. Always `const reduce = useReducedMotion()` and `transition={reduce ? { duration: 0 } : SPRING}`. No animation on page load in product UI. Hover never moves layout; press never scales.
- Accessibility: keep the focus rings. Wrap fields in `<FormField id label error>` so labels and errors are wired. Every icon-only control has an `aria-label`.
## Gotchas
- Most components are client components (`"use client"`). A server component can render them, but function props such as `onSubmit` or `onCta` need a client parent.
- Scrolling regions such as ChatThread need a height from you, for example `className="h-96"`.
- Demo data: use believable product data. Never invent real company logos, testimonials, awards or customer stats.
## When you finish
List the `npx shadcn@latest add` command (or npm imports) you used, so the user can reproduce the install.
Prompts that work
Name the library, say what the screen is for, and let the agent choose components. Each prompt below is followed by what a correct answer looks like: one install command, then code that uses only documented props and semantic tokens.
Prompt 1
Using MiniDev UI, build a dashboard home: a page header, four KPIs, and a weekly revenue chart below. Install with the shadcn CLI.
bashnpx shadcn@latest add @minidev/page-header @minidev/kpi-row @minidev/chart-card @minidev/area-chart @minidev/buttonapp/dashboard/page.tsxtsximport { AreaChart } from "@/components/ui/area-chart" import { Button } from "@/components/ui/button" import { ChartCard } from "@/components/ui/chart-card" import { KpiRow } from "@/components/ui/kpi-row" import { PageHeader } from "@/components/ui/page-header" export default function Dashboard() { return ( <main className="mx-auto max-w-6xl space-y-6 p-6"> <PageHeader title="Overview" description="Last 30 days" actions={<Button size="sm">Export</Button>} /> <KpiRow items={[ { label: "MRR", value: "$48.2k", delta: 8 }, { label: "Active accounts", value: "1,204", delta: 3 }, { label: "Net revenue retention", value: "112%", delta: 2 }, { label: "Churn", value: "1.1%", delta: -0.3, invert: true }, ]} /> <ChartCard title="Revenue" description="Last 8 weeks"> <AreaChart data={[18, 22, 27, 31, 36, 41, 45, 52]} label="Weekly revenue, $k" className="h-48 w-full" /> </ChartCard> </main> ) }Why it is right: Composes existing pieces instead of hand-drawing cards, uses only documented props, and marks churn as invert so a drop reads green.
Prompt 2
Add an AI assistant panel with MiniDev UI: a scrolling message thread and a composer that sends on Enter.
bashnpx shadcn@latest add @minidev/chat-thread @minidev/prompt-inputcomponents/assistant.tsxtsx"use client" import * as React from "react" import { ChatThread, type ChatThreadMessage } from "@/components/ui/chat-thread" import { PromptInput } from "@/components/ui/prompt-input" export function Assistant() { const [messages, setMessages] = React.useState<ChatThreadMessage[]>([]) const [prompt, setPrompt] = React.useState("") return ( <section aria-label="Assistant" className="flex flex-col gap-3 rounded-xl border border-border bg-surface p-4 shadow-raised"> <ChatThread className="h-96" messages={messages} /> <PromptInput value={prompt} onChange={setPrompt} onSubmit={(text) => { setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", content: text }]) setPrompt("") }} /> </section> ) }Why it is right: Gives the thread a height so it scrolls, keeps state in a client component, and frames the panel with surface, border and shadow-raised tokens.
Prompt 3
Build a three-plan pricing section with MiniDev UI. Highlight Pro as the most popular.
bashnpx shadcn@latest add @minidev/plan-cardcomponents/pricing.tsxtsximport { PlanCard } from "@/components/ui/plan-card" export function Pricing() { return ( <div className="grid gap-4 md:grid-cols-3"> <PlanCard name="Starter" price="$0" period="mo" features={["1 seat", "100 invoices a month"]} cta="Start free" /> <PlanCard name="Pro" price="$49" period="mo" features={["10 seats", "Bank sync", "Recurring invoices"]} highlighted badge="Most popular" /> <PlanCard name="Team" price="$129" period="mo" features={["Unlimited seats", "SSO", "Audit log"]} cta="Talk to sales" /> </div> ) }Why it is right: One component, three instances, prices as preformatted strings, and the highlight comes from the prop, not a hand-written accent border.
Prompt 4
Create a sign-in screen with MiniDev UI: email, password, and a link to sign up.
bashnpx shadcn@latest add @minidev/auth-card @minidev/form-field @minidev/input @minidev/buttonapp/login/page.tsxtsximport Link from "next/link" import { AuthCard } from "@/components/ui/auth-card" import { Button } from "@/components/ui/button" import { FormField } from "@/components/ui/form-field" import { Input } from "@/components/ui/input" export default function Login() { return ( <main className="grid min-h-svh place-items-center bg-bg p-4"> <AuthCard title="Sign in" description="Use your work email." footer={<Link href="/signup">Create an account</Link>}> <form action="/api/login" method="post" className="space-y-4"> <FormField id="email" label="Email"> <Input id="email" name="email" type="email" autoComplete="email" required /> </FormField> <FormField id="password" label="Password"> <Input id="password" name="password" type="password" autoComplete="current-password" required /> </FormField> <Button type="submit" className="w-full">Continue</Button> </form> </AuthCard> </main> ) }Why it is right: Labels and errors are wired through FormField, autofill tokens are set, and the primary action is the default ink Button.
More examples live on every component page. Start with DataTable or browse the gallery.
Frequently asked questions
Which AI coding tools work with MiniDev UI?
Any agent that can read a URL or run a shell command. This page has setup for Claude Code, Cursor, Codex, Windsurf, GitHub Copilot and v0. Everything is public: /llms.txt, per-component Markdown at /docs/<name>.md, and shadcn registry items at /r/<name>.json.
Do I need the MCP server?
No. The rules file plus /llms.txt is enough for an agent to pick, install and use components. The MCP server saves the agent from fetching and searching those files itself.
Does the agent need an API key or an account?
No. MiniDev UI is MIT licensed and every file the agent reads is a static public URL. Installing runs npx shadcn@latest add @minidev/<name> or npm i minidev-ui-kit.
The agent's output looks gray or unstyled. What went wrong?
The token stylesheet is missing or overridden. On the shadcn route, save /r/styles.css next to your global CSS, import it after Tailwind, and delete the :root, .dark and @theme inline blocks that shadcn init generated. See Installation.
How do I stop the agent inventing props?
The rules files tell it to read /docs/<name>.md before using a component and to use only the props shown there. If it still guesses, paste that URL into the chat.