Do you need to add this skill?
- Using the Magic Patterns plugin for Cursor or Codex: you already have it.
- Using Claude Code, or set up MCP yourself: add the skill below.
Install the skill
- Claude Code
- Manual MCP
- Other AI editors
Save the skill to your project (or Claude Code picks it up automatically and activates it when you share a Magic Patterns prototype or
~/.claude/skills/... to make it global):mkdir -p .claude/skills/integrate-magic-patterns-design
# paste the SKILL.md below into:
# .claude/skills/integrate-magic-patterns-design/SKILL.md
magicpatterns.com URL.Cursor and Codex plugins already include this skill. Use these steps only if you connected MCP yourself.For Cursor, add the skill as a project rule:
mkdir -p .cursor/rules
# paste the SKILL.md below into:
# .cursor/rules/integrate-magic-patterns-design.mdc
Any agent that supports custom instructions or skills works. Paste the SKILL.md below into your tool’s rules or skills, or include it with your prompt.
The skill
Copy the contents below into your tool of choice.---
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.
Related
Connect your AI coding tool
Pull a prototype into Cursor, Codex, or Claude Code, then adapt it with this skill.
Choose how to export
Download a zip, sync with GitHub, or export to Figma.