Component Library Scaffolder

---
name: component-library-scaffolder
description: Use when scaffolding a starter component library — buttons, inputs, cards, modals, toasts. Triggers on "component library", "design system scaffold", "build a UI kit", "component scaffold".
---

# Component Library Scaffolder

Scaffold a tight component library. The goal is 8-12 components that cover 90% of use cases — not a Radix clone. shadcn/ui is the reference target: copy-pasteable, owned by your codebase, no opaque package.

## Required inputs

1. **Framework** — React (default), Vue 3, Svelte, or framework-agnostic HTML
2. **Styling** — Tailwind (default) or CSS modules
3. **Accent / brand color** — hex (e.g., `indigo-600`, `#4f46e5`)
4. **Variant strategy** — `class-variance-authority` (cva) recommended; or `clsx` with manual variants
5. **Components needed** — pick from the list below

If the user says "I want everything," push back: ship 8 components excellently before adding more.

## Output format

A folder structure:

```
components/ui/
  button.tsx
  input.tsx
  card.tsx
  dialog.tsx
  dropdown.tsx
  toast.tsx
  badge.tsx
  tabs.tsx
  ...
lib/cn.ts          // clsx + tailwind-merge helper
```

Each component file has:
1. Imports
2. Variant definition (`cva`)
3. Component implementation
4. TypeScript types exported
5. Optional: usage example as a JSDoc comment

## Standard components

### Button
Variants: `primary` | `secondary` | `ghost` | `danger` × sizes `sm` | `md` | `lg`. Loading state with spinner. `asChild` prop (Radix slot pattern) for composition with `<a>` or `<Link>`.

### Input / Textarea / Select
Wrapped in a `Field` that handles label, helper, error. `Input` itself is unstyled-ish; visual styling on the wrapper.

### Card
`Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` — composed pieces, not one big prop bag.

### Dialog / Modal
**Use Radix UI primitives or `@reach/dialog` underneath.** Don't hand-roll focus trapping, escape handling, scroll-lock — you'll get it wrong. Style on top.

### Dropdown / Menu
Same: Radix `DropdownMenu` underneath. Style with Tailwind.

### Toast / Notification
`sonner` is the easy choice. If hand-rolling: `role="status"` + `aria-live="polite"` for non-urgent, `role="alert"` for errors. Auto-dismiss with `prefers-reduced-motion` honored.

### Badge / Tag
Variants by intent (`default` | `success` | `warning` | `danger`).

### Tabs
Radix `Tabs` underneath. Keyboard arrow navigation handled.

## Variants with cva

```
import { cva, type VariantProps } from 'class-variance-authority';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      intent: {
        primary: 'bg-indigo-600 text-white hover:bg-indigo-700 focus-visible:ring-indigo-500',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200 focus-visible:ring-gray-500',
        ghost: 'hover:bg-gray-100 focus-visible:ring-gray-500',
        danger: 'bg-red-600 text-white hover:bg-red-700 focus-visible:ring-red-500',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: { intent: 'primary', size: 'md' },
  }
);
```

## Accessibility (non-negotiable)

- Every interactive component supports keyboard (Tab, Enter, Space, Esc, Arrow keys where appropriate)
- Focus-visible rings on every focusable element — no `outline-none` without a replacement
- Modals trap focus and restore on close
- Toasts use appropriate `role` (`status` vs `alert`)
- Color is not the only signal — pair red borders with error icons / text
- Tap targets: buttons `h-10` minimum (40px); icon-only `h-10 w-10`
- `@media (prefers-reduced-motion)` honored on transitions

## File structure conventions

- `components/ui/*` — primitives, copy-paste-owned
- `components/blocks/*` — composed components (e.g., `PricingCard` uses `Card` + `Button`)
- `lib/cn.ts` — `cn()` helper combining `clsx` + `tailwind-merge` (last-wins merging)
- `tailwind.config.ts` — extend with brand colors as semantic tokens (`primary`, not `indigo`)

## Anti-patterns

- **One mega-Button with 20 props**: split into composable pieces (`Button` + `asChild`).
- **Reinventing focus management**: use Radix or React Aria primitives.
- **Color names in props** (`color="blue"`): use semantic intent (`intent="primary"`).
- **Inline styles for variants**: use cva or a class map.
- **No story / no example**: include a usage block in JSDoc; even better, integrate Storybook or Ladle.
- **Components that `forwardRef` inconsistently**: be consistent — every primitive forwards `ref`.

## Output

Return the file structure + each component file. End with a 1-page README listing:
- Components included
- Setup steps (`npm i clsx tailwind-merge class-variance-authority`, plus Radix peer deps)
- Tailwind config additions
- Convention notes (semantic colors, cn helper, asChild pattern)