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

Step 2: Align tokens with Stitch design system

After running

stitch-design-system

design-tokens.css

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

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

<button>

<Button>

<button>

<Button variant="outline">

<button>

<Button variant="ghost">

<button>

<Button variant="destructive">

<Card><CardHeader><CardContent>

<input type="text">

<Input>

<input type="password">

<Input type="password">

<select>

<Select><SelectTrigger><SelectContent>

<Dialog><DialogContent>

<DropdownMenu>

<Badge>

<Avatar><AvatarImage><AvatarFallback>

<Table><TableHeader><TableBody>

<Tabs><TabsList><TabsContent>

<Alert><AlertDescription>

Step 5: Using the

cn()

utility

All shadcn components use

cn()

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" {...props}>
      {children}
    </Button>
  )
}

Accessibility

Radix UI primitives handle most accessibility automatically:

• Keyboard navigation (Tab, Enter, Escape, Arrow keys)
• ARIA attributes (

  role

  ,

  aria-expanded

  ,

  aria-haspopup

  )
• Focus management (trapping focus in dialogs, restoring focus on close)

When customizing, do not remove ARIA attributes or keyboard handlers from the base components. Add to them, don't replace them.

Integration with Stitch workflow

The typical flow:

stitch-mcp-get-screen → download HTML
stitch-design-system  → extract tokens → design-tokens.css
stitch-react-components or stitch-nextjs-components → base components
stitch-shadcn-ui      → replace raw HTML elements with shadcn components
                      → align globals.css with design-tokens.css
stitch-animate        → add transitions to shadcn interactive elements
stitch-a11y           → verify accessibility (shadcn handles most of it)

Troubleshooting

@/components/ui/...

tsconfig.json

vite.config.ts

@/*

./src/*

globals.css

ThemeProvider

next-themes

.dark

<html>

npx shadcn@latest add [component]

cn()

npx shadcn@latest init

lib/utils.ts

References

• shadcn/ui docs: https://ui.shadcn.com/docs
• Radix UI: https://www.radix-ui.com/

• stitch-react-components

  — convert Stitch design to base React components first

• stitch-nextjs-components

  — if using Next.js App Router

• stitch-design-system

  — extract Stitch tokens before aligning with shadcn