skills/integrate-magic-patterns-design/SKILL.md

---
name: integrate-magic-patterns-design
description: Adapt code generated by Magic Patterns (magicpatterns.com) into an existing codebase. Use when the user shares a Magic Patterns design, prototype, exported zip, "Copy Code as Prompt" output, or a magicpatterns.com URL and wants it implemented, integrated, or productionized in their project. Treats the Magic Patterns code as a design spec, not as code to copy verbatim.
---

# Integrate a Magic Patterns Design

Magic Patterns generates **prototypes**. The code you receive is a high-fidelity design spec — it shows layout, hierarchy, spacing rhythm, interactions, and intent. It is NOT meant to be pasted into a codebase as-is.

**The golden rule: when the Magic Patterns code and the target codebase disagree, the codebase wins.** Reproduce the *design*, not the exact code. Always prefer the codebase's existing components, design tokens, styling system, data layer, and conventions over the literal values in the prototype.

## What Magic Patterns code looks like

Unless the design used a custom design system, expect:

- React 18 + TypeScript, styled with **Tailwind CSS v3** utility classes
- **lucide-react** icons, **framer-motion** animations, **react-router-dom** routing, **recharts** charts
- Named exports (`export function PricingSection`), flat or shallow file structure (`components/`, `pages/`, `utils/`)
- **Hardcoded mock data** — inline arrays/objects or a `utils/mockData.ts`
- Placeholder images as full URLs (often Unsplash)
- Stubbed interactivity: controlled inputs with local `useState`, `onSubmit` handlers that do nothing real, no API calls, no auth, no backend
- Zip/GitHub exports are wrapped in a standalone Vite project (`vite.config.ts`, `index.html`, `src/`)

Designs built on a design system preset (shadcn/ui, Chakra, Mantine, MUI) or a custom imported design system will use that library's components and theming instead of plain Tailwind.

## Workflow

### Step 1: Inventory the prototype

Read all the Magic Patterns files first. Identify:

- The actual design content: components, layout, screens, interactions, states (hover, empty, loading, error if present)
- Mock data shapes — these hint at the real data model the UI expects
- Which parts are scaffolding to discard (see checklist below)

**Discard checklist** — never port these:

- [ ] `index.tsx` / `index.html` / `vite.config.ts` / `tsconfig*.json` / `postcss.config.js` / `package.json` / `.eslintrc*` — Vite scaffolding; your project already has its own
- [ ] `tailwind.config.js` and `index.css` — merge any genuinely new tokens into your existing config instead of replacing it
- [ ] `canvas.manifest.js`, `useScreenInit.js` — Magic Patterns multi-screen plumbing; replace with your real router
- [ ] `ComponentPreview.tsx`, `components.config.json`, `context.md` — editor preview files
- [ ] `_designSystem/` folders and empty component stub files — precompiled design system bundles
- [ ] `data-id` props on elements — editor instrumentation
- [ ] `utils/mockData.ts` and inline mock data — replace with your real data layer

### Step 2: Survey the target codebase

Before writing anything, learn how this codebase builds UI. Find:

1. **Framework and routing** — Next.js App Router? Pages Router? Remix? Plain Vite + react-router? Match its conventions for pages, layouts, links, and navigation.
2. **Component library** — Look for an existing `components/ui/`, design system package, or shared component folder. List the available primitives (Button, Input, Card, Dialog, Select, Badge, Table...).
3. **Styling system** — Tailwind (which version? v4 syntax differs from the v3 the prototype uses), CSS Modules, styled-components, vanilla-extract, a token system? Find the theme: colors, spacing, radii, typography, breakpoints.
4. **Icons** — Which icon library is already installed? Do not add lucide-react if the project uses something else.
5. **Data and state** — How does this codebase fetch data (React Query, SWR, server components, tRPC)? Where do types live? How are forms handled (react-hook-form, server actions)?
6. **Conventions** — Default vs named exports, file naming, folder placement, client/server component boundaries, i18n, accessibility patterns.

An effective shortcut: find an existing page or feature in the codebase that is similar in shape to the new design, and use it as the structural template.

### Step 3: Map prototype pieces to codebase equivalents

For every element in the prototype, prefer replacement over porting:

| Prototype has | Do this |
|---|---|
| Hand-rolled `<button className="px-4 py-2 bg-blue-600...">` | Use the codebase's `<Button>` with the nearest variant |
| Hand-rolled inputs, selects, modals, dropdowns, tabs | Use the codebase's form/overlay primitives |
| Raw hex/arbitrary colors (`bg-[#4F46E5]`, `text-blue-600`) | Use the nearest semantic token (`bg-primary`, `text-accent`) |
| Exact pixel values (`w-[347px]`, `gap-[18px]`) | Snap to the codebase's spacing/sizing scale |
| Hardcoded font families and Google Font `@import`s | Use the project's existing typography setup |
| lucide-react icons | Use the project's icon library; pick the closest equivalent glyph |
| framer-motion animations | Keep only if framer-motion is already a dependency; otherwise use the project's animation approach or CSS transitions |
| `react-router-dom` routes and `<Link>`s | Use the framework's router and link component |
| Mock data arrays | Wire to the real data source; derive or reuse real types instead of the prototype's inline shapes |
| Unsplash/placeholder image URLs | Use real assets, or the project's placeholder/image component (`next/image`, etc.) |
| `useState`-only form handling | Use the codebase's form library and real submit/mutation logic |

Only port a component wholesale when the codebase genuinely has no equivalent — and when you do, restyle it with the project's tokens and put it where the codebase keeps shared components.

### Step 4: Implement

- Build in the codebase's file structure, not the prototype's. The prototype's component *boundaries* (what's a section, what's a card, what's reusable) are usually worth keeping; its file paths are not.
- Preserve the design's intent: visual hierarchy, layout structure, relative spacing rhythm, responsive behavior, and interaction states. These are what the user approved in Magic Patterns.
- Treat exact values as approximations of that intent. "16px gap" means "one step of normal spacing", not literally `gap-[16px]` if the codebase's scale says `gap-4` or `var(--space-3)`.
- Add what prototypes always omit: real loading/error/empty states, accessibility (labels, focus management, keyboard handling) per the codebase's patterns, i18n if the project uses it, and real event handlers.
- Don't install new dependencies to match the prototype unless nothing in the codebase can do the job — and ask the user before adding any.

### Step 5: Verify

1. Run the project's typecheck and linter; fix anything introduced.
2. Render the result and compare it against the Magic Patterns design for *intent*: same hierarchy, same layout, same interactions — expressed in this codebase's visual language. Pixel-for-pixel parity with the prototype is not the goal; consistency with the rest of the app is.
3. Confirm no prototype artifacts leaked in: no mock data, no `data-id` props, no stray Tailwind config, no unused new dependencies.

## Common mistakes to avoid

- **Copying the prototype verbatim** and ending up with a page that looks different from the rest of the app. The most common and most costly failure.
- **Duplicating primitives** — shipping a second Button/Modal/Input that slightly differs from the existing one.
- **Importing the prototype's theme** — overwriting or forking `tailwind.config` / global CSS instead of mapping onto existing tokens.
- **Keeping mock data "for now"** — it gets shipped. Wire real data or clearly stub at the data-layer boundary, not inside components.
- **Matching arbitrary values exactly** (`w-[347px]`) instead of snapping to the design scale.
- **Adding lucide-react / framer-motion / react-router-dom** to a project that already has equivalents.