--- name: tailwind-shadcn-ui-builder description: Builds polished, accessible UI components and pages with Tailwind CSS v4 and shadcn/ui, including design tokens, responsive layout, dark mode and states. Use when asked to create, restyle or "make it look good" for any React/Next.js interface, dashboard, form, landing section or component library piece. license: MIT compatibility: React 18+, Tailwind CSS v3.4 or v4, shadcn/ui CLI available (npx shadcn@latest). Works in Next.js, Vite and Remix projects. metadata: category: design version: "1.0.0" --- # Tailwind + shadcn/ui Builder You are producing production UI, not a mockup. The result must be responsive, keyboard accessible, themed through tokens (never hard-coded hex values in components), and consistent with anything that already exists in the project. ## Step 1 — Read the project before writing a line 1. Find the token source: `app/globals.css` or `tailwind.config.*`. Note the color variables (`--background`, `--primary`, `--radius`), fonts and breakpoints. 2. Check `components.json` to learn the shadcn style (`default` or `new-york`), base color and alias paths (`@/components/ui`). 3. List installed primitives with `ls components/ui`. Reuse them. Only run `npx shadcn@latest add ` for primitives that are missing. 4. Open one existing page and one existing component to match spacing scale, heading sizes and how variants are expressed (`cva` or plain classes). If none of these exist, initialise shadcn (`npx shadcn@latest init`) and propose a small token set before building. ## Step 2 — Plan the composition Write a five-line plan before coding: - Layout skeleton (grid/flex, max width, gutters). - Primitives used (Card, Button, Dialog, Table, Tabs, Sheet, Form). - States to cover: default, hover, focus-visible, disabled, loading, empty, error. - Breakpoints: mobile first, then `md:` and `lg:` overrides only where the design changes. - Data shape the component receives (typed props; no fetching inside presentational components). ## Step 3 — Build with these rules - **Tokens over values.** Use `bg-background text-foreground border-border`, `text-muted-foreground`, `rounded-lg` (which maps to `--radius`). Never `#fff`, `bg-gray-900`, or arbitrary `[13px]` unless a token cannot express it. - **Spacing rhythm.** Pick one scale per component (`gap-2/4/6`, `p-4/6`) and stay on it. Avoid mixing `p-3` and `p-5`. - **Typography.** At most three sizes per view: heading (`text-2xl font-semibold tracking-tight`), body (`text-sm`), meta (`text-xs text-muted-foreground`). - **Variants with `cva`.** For any component with more than one look, define `variant` and `size` through `class-variance-authority` and merge classes with `cn()`. - **Accessibility.** Every interactive element is a `