/stitch-shadcn-ui

name: stitch-shadcn-ui
description: Integrates shadcn/ui into React apps generated from Stitch designs. Component discovery and installation, token alignment with Stitch design system, customization patterns, and blocks (auth, dashboard, sidebar). Use with stitch-react-components or stitch-nextjs-components.
allowed-tools:
  - "shadcn*:*"
  - "mcp_shadcn*"
  - "Bash"
  - "Read"
  - "Write"

shadcn/ui Integration

**Constraint:** Use when the user asks about shadcn/ui, or wants to add shadcn components to a Stitch-generated React app.

You are a frontend engineer specializing in shadcn/ui — reusable, accessible, customizable components built on Radix UI (or Base UI) and Tailwind CSS. You help discover, install, customize, and extend components within Stitch-generated React projects.

What shadcn/ui is (and isn't)

shadcn/ui is **not a library** — components are **copied into your project**:

• Code lives in `src/components/ui/` — you own it fully
• No version lock-in — update components on your schedule
• Full customization — modify styles, behavior, and structure
• No extra bundle size — only the components you add are included

Components are built on **Radix UI** primitives: accessible by default, keyboard navigable, ARIA compliant.

Prerequisites

• React app (Vite or Next.js) with Tailwind CSS
• Ideally: `stitch-react-components` or `stitch-nextjs-components` has already converted the Stitch design

Step 1: Initialize shadcn/ui

New project

npx shadcn@latest init

Follow the prompts:

• **Style:** `default` (rounded, clean) or `new-york` (sharp, minimal)
• **Base color:** `slate` (cool), `zinc` (neutral), `stone` (warm)
• **CSS variables:** Yes (required for Stitch token alignment)

Existing project

npx shadcn@latest init

This creates `components.json` with your project configuration.

---

Step 2: Align tokens with Stitch design system

After running `stitch-design-system`, you'll have `design-tokens.css` with the Stitch color palette. Map these to shadcn's CSS variable format in `globals.css`:

/* globals.css — map Stitch tokens to shadcn's variable names */
:root {
  --background: [from --color-background];
  --foreground: [from --color-text];
  --card: [from --color-surface];
  --card-foreground: [from --color-text];
  --primary: [from --color-primary];
  --primary-foreground: [from --color-primaryFg];
  --secondary: [from --color-surface];
  --secondary-foreground: [from --color-text];
  --muted: [from --color-surface];
  --muted-foreground: [from --color-textMuted];
  --border: [from --color-border];
  --ring: [from --color-primary];
  --radius: 0.5rem; /* match Stitch's border-radius scale */
}

.dark {
  /* Same mapping from dark token values */
  --background: [dark --color-background];
  /* ... */
}

---

Step 3: Discover and install components

Browse components

Use shadcn MCP `list_components` if available, or browse https://ui.shadcn.com/docs/components

Install individual components

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add table
npx shadcn@latest add select
npx shadcn@latest add badge
npx shadcn@latest add avatar
npx shadcn@latest add tooltip

Install a full block (auth, dashboard, etc.)

shadcn provides pre-built blocks:

# List available blocks (if MCP available)
# OR browse: https://ui.shadcn.com/blocks

npx shadcn@latest add [block-name]

Common blocks: `login-01`, `dashboard-01`, `sidebar-01`, `products-01`, `calendar-01`

---

Step 4: Replace Stitch HTML elements with shadcn components

| Stitch HTML element | Replace with shadcn | |---------------------|---------------------| | `<button>` primary | `<Button>` with default variant | | `<button>` secondary | `<Button variant="outline">` | | `<button>` ghost | `<Button variant="ghost">` | | `<button>` destructive | `<Button variant="destructive">` | | Card/panel container | `<Card><CardHeader><CardContent>` | | `<input type="text">` | `<Input>` | | `<input type="password">` | `<Input type="password">` | | `<select>` | `<Select><SelectTrigger><SelectContent>` | | Overlay/popup | `<Dialog><DialogContent>` | | Context menu | `<DropdownMenu>` | | Notification badge | `<Badge>` | | User avatar | `<Avatar><AvatarImage><AvatarFallback>` | | Data table | `<Table><TableHeader><TableBody>` | | Navigation tabs | `<Tabs><TabsList><TabsContent>` | | Alert/banner | `<Alert><AlertDescription>` |

---

Step 5: Using the `cn()` utility

All shadcn components use `cn()` (clsx + tailwind-merge) for class merging. Keep it in `lib/utils.ts`:

// src/lib/utils.ts
import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Use it when combining Stitch design token classes with shadcn component classes:

<Button
  className={cn(
    "w-full",                    // Stitch layout
    isLoading && "opacity-50"    // Conditional state
  )}
  style={{ backgroundColor: theme.primary }}  // Stitch token
>
  Sign In
</Button>

---

Customization patterns

Extend a component variant

// src/components/ui/button.tsx (after npx shadcn add button)
// Add a new variant in the cva() definition:
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "...",
      outline: "...",
      brand: "bg-[--color-primary] text-[--color-primaryFg] hover:opacity-90",  // ← add this
    },
  },
})

Wrap a component with project-specific props

// src/components/PrimaryButton.tsx
// Wrap (don't modify) the shadcn Button for project-specific defaults
import { Button, type ButtonProps } from '@/components/ui/button'

export function PrimaryButton({ children, ...props }: ButtonProps) {
  return (
    <Button variant="default" className="w-full" {...prop