Skip to content

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:

prompttext
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.

bash
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.

bash
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.

bash
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
.cursor/mcp.jsonjson
{
  "mcpServers": {
    "minidev-ui": {
      "url": "https://ui.minidev.pro/mcp"
    }
  }
}

Codex

1. Rules

Codex reads AGENTS.md. Append the MiniDev rules to it.

bash
curl -fsSL https://ui.minidev.pro/AGENTS.md >> AGENTS.md

2. MCP server

Register the server in your Codex config.

~/.codex/config.tomltoml
[mcp_servers.minidev-ui]
url = "https://ui.minidev.pro/mcp"

Windsurf

1. Rules

Windsurf picks up AGENTS.md in the workspace.

bash
curl -fsSL https://ui.minidev.pro/AGENTS.md >> AGENTS.md

2. MCP server

Add the server to Windsurf's MCP config.

~/.codeium/windsurf/mcp_config.jsonjson
{
  "mcpServers": {
    "minidev-ui": {
      "serverUrl": "https://ui.minidev.pro/mcp"
    }
  }
}

GitHub Copilot

1. Rules

Append the rules to Copilot's repository instructions.

bash
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
.vscode/mcp.jsonjson
{
  "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:

text
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.

bash
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

Download

minidev-ui.mdc

Cursor project rules

Download

SKILL.md

Claude Code skill

Download
AGENTS.mdmd
# 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.

  1. 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.

    bash
    npx shadcn@latest add @minidev/page-header @minidev/kpi-row @minidev/chart-card @minidev/area-chart @minidev/button
    
    app/dashboard/page.tsxtsx
    import { 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.

  2. Prompt 2

    Add an AI assistant panel with MiniDev UI: a scrolling message thread and a composer that sends on Enter.

    bash
    npx shadcn@latest add @minidev/chat-thread @minidev/prompt-input
    
    components/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.

  3. Prompt 3

    Build a three-plan pricing section with MiniDev UI. Highlight Pro as the most popular.

    bash
    npx shadcn@latest add @minidev/plan-card
    
    components/pricing.tsxtsx
    import { 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.

  4. Prompt 4

    Create a sign-in screen with MiniDev UI: email, password, and a link to sign up.

    bash
    npx shadcn@latest add @minidev/auth-card @minidev/form-field @minidev/input @minidev/button
    
    app/login/page.tsxtsx
    import 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.