Magic Patterns

View saved version →

---
name: inspiration
description: Explore several distinct UI design directions for a screen or component in Magic Patterns (magicpatterns.com). First recreates the current UI as a faithful baseline, then creates a shareable magicpatterns.com/inspiration/<id> document and streams in four self-contained HTML concepts tuned to the kind of exploration wanted (entrypoint/discoverability, information architecture/navigation, or visual display). The hosted comparison link is the deliverable. Use when the user wants design inspiration, alternative directions, layout options, variations, or a "show me a few approaches" exploration before committing to an implementation.
---

# Inspiration

Explore **four parallel design directions** for a target screen or component. This skill recreates a faithful **baseline** of the current UI, **creates a placeholder `magicpatterns.com/inspiration/<id>` document up front**, then generates **four concepts** and **streams each one directly into the document** via subagents. The hosted comparison link is the deliverable, and publishing is required, not optional.

Concepts are pushed straight into the document through the `inspiration_add_variant` MCP tool as each subagent finishes — **no concept HTML files are written to disk, and the concept HTML never round-trips through the main agent's context.** This is what keeps the flow fast and avoids the timid "publish a placeholder concept and hope to fix it later" failure mode.

The goal is **bold, grounded divergence**. Pin the product down ONCE using its real content and its real design tokens (colors, fonts, spacing, SVGs), then make the four concepts **meaningfully different from each other**: different layout philosophies, arrangements, or product framings, not four shades of the same idea. Every concept inherits the baseline's tokens so it still looks like the same product; the design *direction* is the only axis that changes.

## Prerequisites

- The Magic Patterns MCP server must be connected (tools prefixed `magic-patterns`). Publishing uses two tools: `create_inspiration_document` (creates the placeholder document + returns the link and one id per concept) and `inspiration_add_variant` (fills a single concept in with its HTML). Iterating on an existing document (see "Iterating on an existing document" below) uses `get_inspiration_document` (loads the current concepts + baseline), `inspiration_clear_variants` (resets all concepts for a full replace), and `inspiration_update_variant` (revises one concept in place). If the tools are unavailable, tell the user to install/enable the Magic Patterns plugin or MCP server.
- Publishing requires a Magic Patterns account; an authentication error from either tool means the user needs to sign in / connect the MCP server.

## When to use

- **This skill (`inspiration`)**: the user wants several directions to compare before committing — layout/IA exploration, alternative visual treatments, "give me options".
- `prototype`: the user already knows what they want and wants to build/iterate one concrete idea.
- `upload-to-magic-patterns`: just mirror local UI into a hosted design, no concepts.
- `integrate-magic-patterns-design`: bring a chosen concept back into the codebase as production code.

## Output contract

The deliverable is a hosted **`magicpatterns.com/inspiration/<id>` link** that renders the four concepts side by side. You obtain the link **up front** by creating a placeholder document (Step 3), then each concept is filled in via `inspiration_add_variant` (Step 4) — the page shows a loading tile per concept until its HTML arrives, then flips to ready once all four are in.

The **only** local file this skill writes is the baseline, into a temporary working directory (create one with `mktemp -d`; refer to it below as `$TMP`):

```
$TMP/<Target>-inspiration/
└── baseline.html            # faithful recreation of the current UI (grounds the concepts; also uploaded as the document's baseline)
```

Concepts are **not** written to disk — each subagent generates its concept HTML in memory and pushes it straight to `inspiration_add_variant`. The baseline is a single self-contained document that opens standalone and follows the **`recreate-as-raw-html` output contract**: Tailwind Play CDN (`<script src="https://cdn.tailwindcss.com"></script>`), real fonts via `<head>` `<link>`/`@font-face`, static markup only (no framework/build step), verbatim 1:1 SVGs, and tokens resolved to concrete values. Every concept must follow the same contract.

## Workflow

### Step 0 — Harvest context already resolved in the thread

Before reading files or launching subagents, harvest everything the current agent already knows about the target UI from the **entire available thread context**. This includes work done outside this skill: previous user requests, manual exploration, earlier subagent results, pasted code, open/referenced files, and prior implementation work. Context does not need to have been produced by `inspiration` or stored in a special artifact to be reusable.

Build a concise in-memory **resolved UI context** covering:

- target component files and component hierarchy
- real copy/content
- styling system and resolved colors/tokens
- typography and font sources
- spacing, radii, shadows, and density
- design-system primitives and their rendered states
- verbatim SVGs/icons and image asset paths

Mark each concern **complete**, **partial**, or **missing**. A concern is complete only when the thread contains the concrete values needed by the baseline (for example exact hex values, px/rem values, font families/weights, verbatim SVG markup, and real asset paths), ideally with source-file provenance. Reuse complete concerns directly without re-reading their files merely to verify them. For partial concerns, preserve the known values and investigate only the unresolved delta. Re-explore a complete concern only when there is evidence it became stale, such as relevant files being edited later in the thread.

Subagents do not inherit the parent agent's thread context. Include the relevant resolved UI context, exact known values, and citations in every subagent brief so they search only for missing information instead of rediscovering the styling system.

### Step 1 — Build the baseline (compose `recreate-as-raw-html`)

First create the temporary working directory (`mktemp -d`, referred to as `$TMP`). Use the resolved UI context from Step 0 as the context inventory for `recreate-as-raw-html` Step 1 — do not repeat that skill's harvest. Run only the missing exploration described below, then always apply `recreate-as-raw-html` Steps 2–4 (styling fidelity, fonts, and assembly) to produce **one faithful baseline** at `$TMP/<Target>-inspiration/baseline.html`.

**Optimize for speed: reuse first, then parallelize only the missing exploration.** Start from the resolved UI context in Step 0. If it already contains everything needed, skip only the exploration and proceed directly through `recreate-as-raw-html` Steps 2–4; the fast path never skips its fidelity or assembly requirements. For partial or missing concerns, you MUST delegate the remaining codebase exploration to `explore` subagents via the Task tool — do not read/grep the files yourself. Give each subagent the relevant known context and ask only for the unresolved delta. Launch them with the `gpt-5.4-mini` model (fast, read-only), **fanned out concurrently in a single batch (one message, multiple Task calls)**, then do the HTML assembly yourself with what they return. Split only the remaining work, e.g.:

- One subagent finds the target component file(s) and lists its subcomponents / styled wrappers.
- One subagent **follows the component's imports into design-system/workspace packages and `node_modules`** (monorepo sibling packages, `@scope/*` packages) and, for every imported UI symbol (icons, logos, illustrations, bespoke SVG components), opens its real source and returns the **exact `<svg>` markup / asset path** — not a description. For any third-party design-system primitive (segmented control, tabs, switch, select, etc.), also read the **library's component CSS/default rendering** and return the actual default/hover/selected part styles (track color, indicator background + shadow, label colors, per-`size` padding/height/radius).
- One subagent identifies the styling system and locates the theme/token definitions (`tailwind.config`, `:root`/`globals.css` CSS vars, JS theme object, or the library's palette), resolving colors from the **theme source-of-truth file** (the palette/token definition) as concrete hex.
- One subagent finds the font setup, prioritizing **local font files** (`public/fonts/`, `assets/fonts/`, `@font-face` `src: url(...)`, `next/font/local`, `.woff2`/`.woff`/`.ttf`/`.otf`) and then any `@import`/`<link>`/`font-family` declarations, returning the real file paths.
- One subagent finds the **real image assets** (public/static image files, imported image sources) and returns their real paths, intrinsic width/height, and any hover/state variants.

Instruct each subagent to return the concrete resolved values (hex colors, px/rem, font families, weights, radii, shadows, verbatim SVG markup, asset paths) and exact file/line citations — not summaries — so you can assemble the baseline without re-reading.

As you build the baseline, **capture the resolved design tokens** — concrete hex colors, font families/weights, spacing steps, radii, shadows, and verbatim SVG markup. The four concepts MUST reuse these exact values so they read as the real product, not generic mockups. Do not re-derive or guess tokens for the concepts; carry the baseline's resolved values forward.

**Then pin the shared invariants once.** These three are constant across all four concepts — the design *direction* is the only thing that changes. Write them down before generating concepts:

- **focus** — one line naming the exact UI surface being explored (the smallest component, section, layout region, or interaction under ideation). Example: "The empty state of the projects list".
- **sharedCopy** — the real content the concepts render, reused **verbatim** (headings, labels, one representative item's real text). Never paraphrase it, invent extra content, or echo the user's prompt as a title.
- **baselineStyle** — the resolved shared aesthetic every concept honors: palette, typography, border radius, spacing density, light/dark, accent. This is what keeps the four feeling like the same product.

Static resolution only — do NOT run the app, Storybook, or a browser.

### Step 2 — Auto-detect the inspiration type

Infer which **kind** of exploration the request is about, state the detected type in one line, and proceed (no confirmation needed). If genuinely ambiguous, pick the closest type and say which one you chose.

- **Entrypoint / discoverability** — *where* a new feature or action should live and how users get to it. Cues: "where should X go", "should this be in the sidebar", "how do users find/discover X", "add an entry point for X".
- **Information architecture / navigation** — *how* content and flows are organized and navigated. Cues: "reorganize", "too many tabs", "restructure the flow", "group these", "this screen is cluttered".
- **Visual display / UI treatment** — the *visual look* of a specific component or screen. Cues: "make it look better", "restyle", "different layout for this card/list", "give this a fresh look".

### Step 3 — Create the placeholder document

You (the main model) do the **creative thinking** first: turn the detected type's four archetypes (matrices in Step 4) into four bold, distinct directions and **name each concept distinctively** (e.g. "Spotlight", "Command Bar", "Split Canvas") with a 1-2 sentence **direction** thesis describing the approach that makes it different. The name becomes the concept's label; the direction is the core of each subagent brief.

**Detect the source repo** so the document keeps that context. Check you're inside a git work tree and read the origin remote:

```bash
git rev-parse --is-inside-work-tree 2>/dev/null && git config --get remote.origin.url
```

Normalize the remote to a plain `https://github.com/<owner>/<repo>` URL (strip a trailing `.git`, and rewrite an SSH remote like `git@github.com:owner/repo.git` to `https://github.com/owner/repo`). If there is no `.git` folder or no remote, just omit `repositoryUrl` — publishing must still work without it.

**Create the placeholder** with the `create_inspiration_document` MCP tool, declaring the four concepts **without html**:

- `title`: the `focus` (e.g. "Projects list empty state").
- `files`: one entry per concept, each `{ name, description }` — the concept's name and direction thesis, **and no `html`**. Send all 4 (they render as loading tiles).
- `repositoryUrl`: the normalized URL from above, when you resolved one.
- `baseline`: `{ html, focus, sharedCopy, baselineStyle }` — `html` is the full contents of `baseline.html`, and the other three are the invariants you pinned in Step 1.

The tool returns `{ id, url, variants: [{ id, name }] }`. **Record the `id` (the inspiration id), the `url`, and each concept's `variantId`** — you hand each subagent its own `variantId` in the next step. If the tool reports an authentication error, the MCP server isn't connected/signed in — tell the user how to connect it and stop.

**Immediately open the `url` before generating the concepts (Step 4).** The page shows a faded, shimmering baseline in each concept tile and polls for updates, so the user watches every concept stream in live as its subagent finishes, instead of staring at a blank wait. Open it in the user's **default browser** with the OS opener: run `open <url>` on macOS, `xdg-open <url>` on Linux, or `start <url>` on Windows. **This `url` is the ONLY thing you open in a browser** — never open the local `baseline.html`, which is scaffolding for publishing, not for previewing. Only skip opening if the user explicitly asked you not to.

### Step 4 — Generate and stream in the four concepts (parallel subagents)

**Delegate the concept generation to subagents (via the Task tool), fanned out concurrently in a single batch**, one subagent per concept. Each subagent assembles its concept HTML from the brief you hand it and **calls `inspiration_add_variant` directly to push the HTML into the document** — it does NOT write a file and does NOT return the HTML to you. This keeps every concept's HTML out of your context.

**Subagent type + model.** Launch each concept subagent as **`generalPurpose`** (it needs MCP access to call `inspiration_add_variant`; the read-only `explore` type cannot) with the **`gpt-5.4-mini`** model (each subagent is mostly assembling HTML from a fully-resolved brief, so speed wins).

**Divergence mandate.** The four must be genuinely different design philosophies, arrangements, or product framings — **not four shades of the same idea**. Take each of the detected type's four archetypes (matrices below) and push it to its **boldest coherent expression**, not a timid tweak. If two directions would look similar, make them diverge harder. The only axis that changes is the design direction; `focus`, `sharedCopy`, and `baselineStyle` stay pinned.

**Craft rules:**

- **Make the explored dimension the large, obvious focal change** — the distinctive idea should read at a glance. Keep everything else consistent with the baseline; render secondary/repeated content as it is in the baseline (or as neutral skeleton) so it doesn't compete with the idea.
- **Honor the baseline tokens** — same palette, typography, radius, density, light/dark, accent. Never flip light to dark (or vice versa) or jump to an unrelated visual language; the divergence is structural/directional, not a rebrand.
- **Auto-play any signature motion via CSS on a loop.** If a direction's idea involves motion or an interaction (a reveal, a transition, a marquee), demonstrate it as a self-running CSS `@keyframes`/`animation` loop (play → briefly hold → reset → repeat) so it's visible when the file is glanced at, not gated behind `:hover`, a click, or JS. Small vanilla JS is fine *in addition*, for making controls genuinely functional when the file is opened for a closer look.
- **No meta text.** No titles, captions, or frame labels inside the file that narrate the concept, and never echo the user's prompt as a heading.

**Subagent brief** — self-contained; the subagent must not re-read the source or re-derive styling. Include:

- The `inspirationId` and this concept's `variantId` (both from Step 3), and the instruction: generate the concept HTML, then call the `inspiration_add_variant` MCP tool with `{ inspirationId, variantId, html }` — passing the full HTML directly. Do NOT write an HTML file; do NOT return the HTML in the response (just confirm the concept was added).
- The concept's **name** and **direction** thesis, plus the specific archetype it expresses and precisely what to change vs. hold constant.
- The pinned invariants — `focus`, `sharedCopy` (render verbatim), `baselineStyle` — plus the concrete resolved values the file needs: hex colors, spacing/radii, font families/weights (and their `<head>` `<link>`/`@font-face`), and verbatim `<svg>` markup. The simplest reliable brief is "start from this baseline HTML, keep the tokens/copy, and change only X" — include the baseline HTML (or its salient tokens/markup) inline in the brief.
- The output-contract + craft rules: single self-contained HTML document, Tailwind Play CDN, real fonts, 1:1 SVGs, no guessed colors, honor baseline tokens, signature motion auto-plays via CSS, no meta labels.

**Fallback.** If a subagent reports it cannot call `inspiration_add_variant` (no MCP access in that subagent), have it return the finished HTML instead, and you call `inspiration_add_variant` yourself for that concept. Prefer the direct-push path.

**Entrypoint / discoverability** (same baseline chrome; the entrypoint's placement moves):

1. Primary nav / sidebar item.
2. Top bar / header action (button or icon).
3. Contextual / inline (empty-state CTA, row action, or a context menu on the relevant object).
4. Global launcher (command palette, modal, or a "+" / create menu).

**Information architecture / navigation** (same content; the structure changes):

1. Tabbed layout.
2. Grouped sidebar sections (explicit hierarchy).
3. Stepped wizard / progressive flow.
4. Single page with progressive disclosure (accordions / collapsible sections).

**Visual display / UI treatment** (same data; the visual treatment changes):

1. Alternate layout container (e.g. cards ↔ list ↔ table) and/or density.
2. Hierarchy & emphasis shift (typography scale, spacing, color emphasis).
3. Alternate component pattern (e.g. grid ↔ feed, split view).
4. Bold, distinct direction (imagery/mood) while staying within the brand tokens.

After the subagents return, each concept should be live on the page (the document flips to ready once all four are in). If a subagent failed or its concept drifted (didn't reuse the baseline tokens/copy/SVGs, didn't express its distinct direction, or its signature motion doesn't auto-play), regenerate that concept and re-push it with `inspiration_add_variant` (targeting the same `variantId`).

### Step 5 — Hand back the shareable link

Return the `url` from Step 3 to the user and tell them it renders the four concepts side by side and can be shared. Note the detected type. If publishing hit an authentication error, tell the user how to connect the MCP server.

**If the tab isn't already open, open it now** — using the same opener described in Step 3. Normally it's already open from Step 3, where the concepts fill in live as each subagent finishes, so you only need to open it here if opening was skipped there (e.g. the browser tool was unavailable then). Never open it twice.

**End your response by asking the user to pick a direction** — something along the lines of: "Let me know which one you like the best and I can implement it into this codebase. Alternatively, let me know if you want me to brainstorm more variants or flesh one out further." The exact wording can vary, but keep the same intent: invite them to choose one to implement, or ask for more variants or a deeper pass on one.

### Step 6 — Clean up the temp folder

Once you've streamed in the concepts (Step 4) and handed back the link (Step 5), **delete the temporary working directory** so nothing is left behind: `rm -rf "$TMP"` (this removes `baseline.html`). The hosted link is the deliverable; the baseline file was only scaffolding for the create call.

## Iterating on an existing document (follow-up messages)

When the user follows up about an inspiration document you already created (e.g. "swap these out", "update C & D", "make them focus more on the messaging"), **don't rebuild from scratch** — iterate on the existing document so the link stays the same.

First **load the current state** with `get_inspiration_document` (pass the `inspirationId`). It returns the current `variants` (each with `id`, `name`, `description`, and its previous `html`) and the `baseline` (`focus`, `sharedCopy`, `baselineStyle`, and the baseline `html`). You need this because a follow-up turn usually doesn't have the concept ids or the pinned invariants in context anymore.

Then **detect the intent** and take one of two paths:

**Replace all** — the user wants a fresh set of directions ("give me different options", "these aren't working, try again"). Call `inspiration_clear_variants(inspirationId)` to reset every concept back to an empty placeholder (this also drops their pre-created "Iterate" rooms). Then invent four new directions **from the baseline** and stream them in with `inspiration_add_variant` exactly like Step 4 — parallel `generalPurpose` + `gpt-5.4-mini` subagents, one per concept, each pushing its own HTML directly (and updating the concept's `name`/`description` on the fill). Reuse the same pinned `focus`/`sharedCopy`/`baselineStyle` from the loaded baseline so the new concepts still read as the same product.

**Update a subset (or all)** — the user wants specific concepts revised ("update Concept C", "make B and D denser", "lean harder into the imagery"). For **only the targeted concepts**, fan out one `generalPurpose` + `gpt-5.4-mini` subagent per concept. Give each subagent that concept's **previous `html`** plus the requested change, and instruct it to **revise from the previous version** (keep everything the user didn't ask to change), then call `inspiration_update_variant(inspirationId, variantId, html)` to push the revised HTML directly. **Leave the untouched concepts alone** — do not regenerate concepts the user didn't mention. The same craft/fidelity rules apply: honor the baseline tokens, render `sharedCopy` verbatim, copy SVGs 1:1, auto-play signature motion via CSS.

After either path, **open the same `url`** for the user (using the opener described in Step 3) — the document updates in place, and any tile being regenerated shows the faded baseline + shimmer until its revised concept streams in.

## Fidelity & guardrails

Carry over from [`recreate-as-raw-html`](../recreate-as-raw-html/SKILL.md):

- Every concept (and the baseline) is a single self-contained HTML document (Tailwind CDN, real fonts, static markup) that opens standalone.
- Colors/spacing/radii/fonts are resolved to concrete values from the theme source of truth — never guessed named colors.
- Icons/SVGs/logo copied 1:1 from source — never redrawn, simplified, or substituted.
- Concepts reuse the baseline's resolved tokens/fonts/SVGs verbatim; the exploration changes layout, placement, or treatment — never the underlying brand values, and never the theme (no light↔dark flip, no unrelated visual language).
- The four must be **meaningfully different** directions, not four shades of one idea — push each archetype to its boldest coherent expression.
- Any signature motion auto-plays via CSS on a loop; it is never gated behind `:hover`, a click, or JS. Extra vanilla JS is fine for functional controls when the concept is opened, but the motion itself must run on its own.
- Keep it static HTML apart from that motion/those controls. Add JS only when a concept genuinely needs it; otherwise omit it.
- Do NOT run the app, Storybook, or a browser — static resolution only.

## Common mistakes

- **Publishing a placeholder concept "to test the flow"** — never fill a concept with stub/placeholder HTML. Declare the four concepts empty at create time (Step 3), then push each one's real HTML via `inspiration_add_variant`.
- **Pulling the concept HTML back through the main agent** — the subagents push HTML straight to `inspiration_add_variant`; don't have them return the HTML for you to forward (except the no-MCP fallback).
- **Four shades of the same idea** — concepts that don't diverge enough (the primary failure). Make each a distinct design philosophy/arrangement/framing.
- Flipping the theme or jumping to a new visual language — the divergence is structural/directional; honor the baseline tokens (palette, type, light/dark, radius, density).
- Signature motion that doesn't auto-play (gated behind hover/click/JS) so it's invisible at a glance — drive it with CSS `@keyframes`/`animation` on a loop.
- Skipping the baseline and jumping straight to concepts — the baseline is what grounds every concept in the real tokens and copy (and it's uploaded as the document's baseline).
- Making concepts generic (guessed colors/fonts) instead of inheriting the baseline's resolved values.
- Varying `focus`, `sharedCopy`, or `baselineStyle` between concepts — hold those pinned so only the design direction changes and the comparison stays meaningful.
- Redrawing or substituting SVGs/logos instead of copying them 1:1 from the baseline.
- Writing concept HTML files to disk — only the baseline is written locally; concepts go straight into the document.
- On a follow-up: rebuilding a brand-new document instead of iterating on the existing one via `inspiration_clear_variants` / `inspiration_update_variant` (the share link should stay the same).
- On an update: regenerating every concept when the user only asked to revise a subset — touch only the concepts they named, and leave the rest as-is.
- On an update: discarding the previous HTML and starting the concept over instead of revising from it — load the previous `html` via `get_inspiration_document` and change only what was asked.

## Related

- `recreate-as-raw-html` — the baseline engine: recreates the current UI as faithful raw HTML that grounds every concept.
- `prototype` — build and iterate one concrete idea grounded in local UI.
- `upload-to-magic-patterns` — mirror local UI into a hosted design.
- `integrate-magic-patterns-design` — bring a chosen concept into this codebase as production code.

View saved version →

---
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.

View saved version →

---
name: prototype
description: Prototype an idea in Magic Patterns (magicpatterns.com) starting from your local UI. Use when the user gives a prompt for something they want to prototype or explore and wants an iterable Magic Patterns design grounded in their existing code. Seeds a design by recreating the relevant local UI (recreate-as-react) and uploading it, then prompts Magic Patterns to design the new idea, returns the editor link, and opens it in the browser. Requires the Magic Patterns MCP server.
---

# Prototype an idea in Magic Patterns

Use this skill when the user has an idea they want to **prototype** and wants it grounded in the UI they already have. It seeds a Magic Patterns design from the relevant local UI, then prompts Magic Patterns to design the idea, hands back the editor link, and opens it in the browser.

It composes two mechanisms, used **in order, for different jobs** — not interchangeably:

- **Seed (deterministic):** recreate the relevant *existing* local UI with `recreate-as-react` and write it into a blank design (the `upload-to-magic-patterns` flow). This recreates what already exists — it does NOT build the new idea.
- **Prototype the idea (creative):** once seeded and published, use `send_prompt` to let Magic Patterns design the net-new idea. This is where the prototyping happens — let Magic Patterns do the creative heavy lifting; don't hand-build it.

Direct file writes *after* seeding are reserved for precise, deterministic tweaks (rename a label, swap a color, port one specific local component) — never for generating the new concept.

Magic Patterns renders **visual prototypes**, not production apps — local code must be ported to its constraints (handled by `recreate-as-react`; see `upload-to-magic-patterns`).

## Prerequisites

- The Magic Patterns MCP server must be connected (tools prefixed `magic-patterns`). If the tools are unavailable, tell the user to install/enable the Magic Patterns plugin or MCP server, and stop.
- Magic Patterns MCP usage requires a paid plan. A `Payment Required` / credits error means the user must upgrade at `magicpatterns.com/settings`.

## When to use

- **This skill (`prototype`)**: the user wants to prototype or evolve an idea grounded in their existing UI, and iterate on it.
- `upload-to-magic-patterns`: just mirror local UI into a hosted design, no iteration.

- `integrate-magic-patterns-design`: bring a Magic Patterns design back into the codebase as production code.

## Links: always hand back the editor link

Designs created via the MCP server use normal Magic Patterns access controls. Return the editor link and tell the user to open it in their browser; they may need to log in.

`create_design` returns two URLs:

- **`editorUrl`** (`…/c/<editorId>`) — the editor. **This is what you give the user to view or edit the prototype.**
- **`previewUrl`** (`project-<slug>.magicpatterns.app`) — an optional rendered preview URL. Do not rely on it as the primary no-login link.

Always return the `editorUrl`.

## Workflow

The two mechanisms are sequential and do different jobs: **seed** recreates existing UI deterministically, then **prompt** lets Magic Patterns design the new idea. Do them in this order.

### Step 1 — Clarify the goal and pick the seed (existing UI only)

From the user's prompt, work out (a) the idea they want to prototype and (b) the smallest existing screen/component it builds on. Keep the seed scope minimal — just enough existing UI to ground the prototype, not the whole app, and not the new feature.

### Step 2 — Seed: recreate the existing local UI in Magic Patterns

**Run the `upload-to-magic-patterns` skill** on the seed scope to mirror the relevant local UI into a fresh design. It does the whole seed for you — ports the UI with `recreate-as-react` (into a temp dir), then `create_design` → `get_design_status` → `write_artifact_files` → `publish_artifact`, and cleans up the temp dir. **Keep the `editorId` and `editorUrl` it returns** for the prompt step below. Don't re-implement that sequence here.

**Mirror only what already exists. Do NOT invent the new feature here.** If there is no relevant local UI to seed from, start from a minimal base instead.

**Fidelity matters most here.** The generated feature inherits the seed's look and layout, so an approximate seed produces an approximate (often ugly) result. `recreate-as-react` reproduces the existing UI faithfully — preferring the source's real component library, which MP installs from `package.json` (e.g. Cubed → `@radix-ui/themes` + its theme CSS + a `<Theme>` wrapper) — rather than rebuilding it in approximate Tailwind. A faithful, well-sized seed is what keeps the later `send_prompt` result from clashing or overflowing.

### Step 3 — Hand back the editor link (checkpoint)

Give the user the `editorUrl` so they can open the starting point before spending generation credits, and open it in the browser (see Step 6). Tell them they may need to log in.

### Step 4 — Prototype the idea with a prompt (the heavy lifting)

This is where the prototyping happens — **let Magic Patterns do the creative design work.** Write a clear spec of the desired feature (goals, behaviors, the user's desires, constraints) and send it:

1. `get_design_status(editorId)` first to get the **current** active `artifactId` — the editor is collaborative and the active artifact can change between steps.
2. `send_prompt(editorId, "<spec of the idea to prototype>")`.
3. Generation runs in the background. Poll `get_design_status` at most once every 60 seconds only if you need to programmatically inspect the result afterward (e.g. `read_artifact_files`).

**Default to this for any net-new or creative change. Do NOT hand-build the new feature with `write_artifact_files`** — that defeats the purpose of prototyping in Magic Patterns.

*Exception — direct file writes:* only for precise, deterministic tweaks on top of a generated result (rename a label, swap a color, port one specific local component). Use `write_artifact_files(...)` then `publish_artifact(...)`. Never use this path to generate the concept itself.

### Step 5 — Hand back the link and iterate

After each meaningful change, return the `editorUrl` so the user can view and keep iterating in Magic Patterns. Offer to keep iterating, or to pull the result back into the codebase with the `integrate-magic-patterns-design` skill.

### Step 6 — Open the editor in the browser

**Always open the `editorUrl` for the user — don't just print it.** Open it in the user's **default browser** with the OS opener: run `open <url>` on macOS, `xdg-open <url>` on Linux, or `start <url>` on Windows. Open it at the Step 3 checkpoint (the seeded starting point) and again after a `send_prompt` change lands. Only skip opening if the user explicitly asked you not to.

## Notes and limitations

- **`send_prompt` is asynchronous:** hand off the editor link for the user to view in their browser. Poll `get_design_status` only when you need to act on the result programmatically.
- **Keep scope tight:** a focused prototype compiles reliably and iterates fast. Resist seeding or generating the whole app.
- **Confirm before regenerating:** each `send_prompt` consumes credits.

## Related

- `recreate-as-react` — the porting engine used to build the seed.
- `upload-to-magic-patterns` — the seed step: recreate local UI and write it into a design directly.
- `inspiration` — explore several parallel design directions instead of building one idea.
- `integrate-magic-patterns-design` — bring the prototyped design back into the codebase as production code.

View saved version →

---
name: recreate-as-raw-html
description: Recreate a component, screen, or pasted code from any codebase as a single self-contained raw HTML file (Tailwind Play CDN + web fonts) that faithfully reproduces its styling, colors, spacing, and fonts. Use when the user asks for a "raw HTML recreation", an "HTML version" of a component, "make an HTML copy of X", or references a component/screen by name (e.g. "Take the <ComponentName> and give me raw HTML").
---

# Recreate as raw HTML

Turn a component, screen, or pasted snippet into **one self-contained `.html` file** that opens standalone in a browser and reproduces the original's styling as faithfully as possible.

**Method: static.** Read the source and resolve its design tokens by inspection — do NOT run the app, Storybook, or a browser. Fidelity comes from carefully tracing whatever styling system the codebase uses down to concrete values, then re-expressing them in Tailwind.

This works for **any codebase**. The styling system varies (Tailwind, CSS/SCSS, CSS Modules, styled-components / Emotion, vanilla-extract, a design-system library like Radix/MUI/Chakra/Mantine/shadcn, or plain inline styles). Step 2 is about identifying which one is in play and following the chain to real pixel/color/font values.

## Output contract

Produce a single HTML document:

- Tailwind via the Play CDN: `<script src="https://cdn.tailwindcss.com"></script>`
- Font `<link>`s / `@import`s in `<head>` for the fonts the source uses
- Static markup only — no React/Vue/framework, no build step. Add JS only for trivial visual behavior if the user asks; otherwise omit it.
- Save as `./<ComponentName>.html` (or next to where the user is working) and hand back the path.

## Workflow

### Step 1 — Locate the source (use subagents to explore)

**First, harvest what's already in the parent agent's entire available thread context — don't re-explore what the agent already knows.** Reusable context can come from anywhere in the thread, not only this skill: previous user requests, manual exploration, earlier subagent results, pasted code, open/referenced files, or prior implementation work.

Build a concise in-memory resolved context brief for the target component source, imported SVGs/design-system rendering, theme tokens/colors, fonts, and image assets. Mark each concern **complete**, **partial**, or **missing**. Only count a concern as complete when the thread contains the concrete values it needs (verbatim `<svg>` markup, concrete hex, px/rem, font families/weights, real asset paths), ideally with source-file provenance. Reuse complete concerns directly without re-reading their files merely to verify them. For partial concerns, preserve the known values and investigate only the unresolved delta. Re-explore a complete concern only when there is evidence it became stale, such as relevant files being edited later in the thread. If everything needed is already in context, skip exploration entirely and go straight to Step 2 assembly.

For whatever remains partial or missing, you MUST delegate the codebase exploration to `explore` subagents via the Task tool — do not read/grep the files yourself. Subagents do not inherit the parent agent's thread context, so include the relevant resolved context brief, exact known values, and citations in every prompt, and ask only for the unresolved delta. Launch them with the `gpt-5.4-mini` model (fast, read-only), fanned out concurrently in a single batch, then do the HTML assembly yourself with what they return. Split the remaining work, e.g.:

- One subagent finds the target component file(s) and lists its subcomponents / styled wrappers.
- One subagent **follows the component's imports into design-system/workspace packages and `node_modules`** (monorepo sibling packages, `@scope/*` packages) and, for every imported UI symbol (icons, logos, illustrations, bespoke SVG components), opens its real source and returns the **exact `<svg>` markup / asset path** — not a description. For any third-party design-system primitive (segmented control, tabs, switch, select, etc.), also read the **library's component CSS/default rendering** and return the actual default/hover/selected part styles (track color, indicator background + shadow, label colors, per-`size` padding/height/radius).
- One subagent identifies the styling system and locates the theme/token definitions (`tailwind.config`, `:root`/`globals.css` CSS vars, JS theme object, or the library's palette), resolving colors from the **theme source-of-truth file** (the palette/token definition) as concrete hex.
- One subagent finds the font setup, prioritizing **local font files** (`public/fonts/`, `assets/fonts/`, `@font-face` `src: url(...)`, `next/font/local`, `.woff2`/`.woff`/`.ttf`/`.otf`) and then any `@import`/`<link>`/`font-family` declarations, returning the real file paths.
- One subagent finds the **real image assets** (public/static image files, imported image sources) and returns their real paths, intrinsic width/height, and any hover/state variants.

Instruct each subagent to return the concrete resolved values (hex colors, px/rem, font families, weights, radii, shadows, verbatim SVG markup, asset paths) and exact file/line citations — not summaries — so you can assemble the HTML without re-reading.

- Named target (e.g. a component name, or "the pricing card", "the settings sidebar") → have a subagent find the component file(s) and everything that affects appearance (subcomponents, styled wrappers, imported CSS/theme files).
- Pasted code → use it directly, but still resolve any tokens, classes, or theme imports it references (delegate that lookup to a subagent).

### Step 2 — Identify the styling system and resolve to concrete values (the fidelity core)

First determine how this component is styled, then trace every style down to a real value (hex color, px/rem size, font family, weight, radius, shadow). Common systems:

- **Tailwind classes** → keep them verbatim where the CDN supports them. Resolve custom classes from the project's `tailwind.config` (custom colors, spacing, fonts) into the concrete value and emit as an arbitrary value (`bg-[#...]`).
- **Semantic / aliased utility classes** (`bg-primary`, `text-foreground`, `border-border`, `bg-muted`, `text-accent`, common in shadcn/Tailwind theme setups) are **not literal colors** — they resolve to CSS variables (`--primary`, `--foreground`, ...) defined in `globals.css`/`:root` or `tailwind.config`. Follow them to the real value; e.g. `border-border` is usually a light gray, `text-foreground` near-black — not the accent.
- **Plain CSS / SCSS / CSS Modules** → read the stylesheet; translate each rule to Tailwind utilities, or drop it into an inline `<style>` block if it's complex (keyframes, pseudo-elements, complex selectors).
- **styled-components / Emotion / vanilla-extract** → read the styled definitions and template literals; translate the resulting CSS to Tailwind/inline styles.
- **Design-system library** (Radix/Radix Themes, MUI, Chakra, Mantine, shadcn, Ant, or an in-house wrapper) → the library's props and CSS-variable tokens hide real values. Map its layout/spacing props to Tailwind, and resolve its **design tokens** (see below) to concrete values.
- **Inline `style={{...}}`** → carry values over directly as inline `style` or the equivalent Tailwind class.

**Never infer a color from convention or memory — read the element.** The most damaging errors come from assuming what a color "should" be instead of reading the actual `className`/`style` on that element. Chat UIs are a classic trap: many apps use a white/bordered user-message bubble, not an accent-colored one — so do not paint the user bubble the accent color (or a primary button, badge, or highlight) just because that's the common pattern. Open the source for each element and use the color it actually declares.

**Follow imports into design-system / workspace packages — they are the source of truth.** A component's appearance is often defined in code it imports, not in the file you're looking at. When a component renders an imported icon, logo, or bespoke SVG component, open that component in its package (a monorepo sibling package or `node_modules`) and reproduce its **actual markup**. Never approximate a design-system component from its name — trace it to its definition and copy what it renders.

**Icons, SVGs, and the logo MUST match the source 1:1 — never guess.**

- Copy the exact `<svg>` markup — same `viewBox`, `<path>` data, `fill`/`stroke`, `stroke-width`, and dimensions — verbatim from the source (app file, icon package, or asset file). Do NOT redraw, simplify, approximate, or invent path data. Do NOT substitute a "closest glyph".
- If an icon/logo is rendered via a component or an asset import, follow it into its package/asset source and copy the real SVG it emits, including the exact colors passed in for the relevant state.
- The brand logo/wordmark is a common miss: copy it verbatim from its source rather than eyeballing or reusing a stale/guessed path.
- The ONLY acceptable fallback when a source SVG truly cannot be located: stop and tell the user which icon could not be found rather than shipping a guessed one. (A distinctive icon guessed instead of copied comes out the wrong shape entirely.)

**Design-system primitives: reproduce the library's real rendering, not a guess.** For a third-party design-system component, the appearance (backgrounds, borders, shadows, the active/selected indicator, sizing per `size`/`variant`) is defined by **the library's own CSS and variant defaults** — not by the app usage or the prop names. You cannot infer it from the app file, which may only be a bare `<SomeControl size="1">` usage.

- Resolve the real look by reading the library's component CSS/source in `node_modules` (or using accurate knowledge of that library's documented default rendering), then translate that to HTML/Tailwind.
- Library part-name selectors in `className` overrides (generic form `[&_.<library-part-name>]`) reveal the component's internal anatomy — use them to know which parts exist and which one is being styled, and as a pointer to the exact component to read.
- **Do NOT accent-fill a selected/active segment, tab, toggle, or menu item by default.** Many design systems render the active state as a neutral raised surface (e.g. white/panel background + a subtle shadow, with normal dark label text) on a muted track — not the brand accent. Reproduce the library's actual selected-state styling; if unsure, read the library CSS rather than guessing. (For example, a segmented control's selected item is often a white raised indicator with a shadow, not a solid accent fill.)

**Resolving design tokens (CSS variables / theme scales).** When you see `var(--...)`, a theme object, or a scale reference, follow it to the source-of-truth value — do NOT guess a Tailwind named color that "looks close":

- Find where the token is defined (a `:root`/theme CSS file, a JS theme object, or the library's published palette) and use that exact value.
- Apply it as a Tailwind arbitrary value (`bg-[#...]`, `text-[#...]`, `border-[#...]`) or, only when no utility fits, an inline `style`.
- For libraries that use a numbered color scale (e.g. Radix's 1–12), the step conveys role: **1–2** app/subtle backgrounds, **3–5** component backgrounds (normal/hover/active), **6–8** borders/separators/focus ring, **9–10** solid fills (9 = the accent solid, e.g. a primary button), **11** secondary/low-contrast text, **12** high-contrast text. Resolve the actual hex from the scale in use (the theme's accent + gray).

**Map layout/spacing/size props to Tailwind** regardless of library:

- `direction="column"` → `flex-col`; `align="center"` → `items-center`; `justify="between"` → `justify-between`
- `gap`, `px`, `py`, `p`, `m*` spacing steps → the matching Tailwind step (verify the scale — some libraries' step N ≠ Tailwind's step N)
- Preserve `size`/`variant`/`weight` semantics by translating to the resolved font size, weight, and fill.

**Border radius — resolve the exact value, don't approximate.** Radius is a common failure point: `rounded-md` (6px) rarely matches the source. Trace the real radius to a px/rem value and emit it as an arbitrary utility (`rounded-[10px]`) rather than the nearest named step.

- Named library radii (`radius="large"`, `size="2"`, `--radius-3`, `borderRadius: 'md'`) are **tokens, not pixels** — look up the resolved px in the theme/scale; many libraries also multiply the base radius by a scaling factor, so verify the computed value.
- A "pill"/fully-rounded element uses a huge radius (e.g. `border-radius: 9999px`) → `rounded-full`, not `rounded-lg`.
- Match **per-corner** radii when the source only rounds some corners (`rounded-t-[10px]`, `rounded-l-lg`) and radius that changes responsively.
- A parent with radius plus `overflow-hidden` clips children — keep the `overflow-hidden` or inner corners will bleed past the rounded parent.
- When elements are nested, inner radius usually = outer radius minus the padding/border; preserve that difference instead of reusing the same value.

**Preserve intent.** Keep responsive prefixes (`md:`, `lg:`), visibility/sizing (`hidden md:inline-flex`, `w-fit`, `whitespace-nowrap`), and hover/active/focus/disabled visual states.

### Step 3 — Fonts

Detect the font source and reproduce it in `<head>`. **Always prefer the codebase's own local font files over a Google Fonts (or other web) substitute** — a substitute only approximates the real typeface. Order of preference:

1. **Local font files (preferred whenever they exist)** → check the project for bundled fonts (`public/fonts/`, `assets/fonts/`, `src/fonts/`, `@font-face` `src: url(...)` rules, `next/font/local` declarations, `.woff2`/`.woff`/`.ttf`/`.otf` files). If found, reference them with a `@font-face` block pointing at the file. Since the output must open standalone, resolve the path so the file loads: use an absolute path to the local file (e.g. `file:///.../public/fonts/Foo.woff2`) or the project's served URL, and only copy the files next to the HTML if the user asks. Note in a comment where the fonts came from.
2. **Google Fonts** → only if the font is a Google font and no local file exists: add the matching `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...">`.
3. **Third-party (Typekit/Adobe, etc.)** `@import url(...)` → mirror the same `@import` or `<link>` when there's no local copy.
4. **Closest web substitute** → last resort when the real font isn't available locally or via a known service; pick the nearest match and note the substitution.
5. **System/default UI font** → for a system stack, set an explicit `font-family` on the root so it doesn't fall back to Times.

Put font `@import url()` first (above other CSS). Apply the correct `font-family`, weights, sizes, and line-heights on the root and headings.

### Step 4 — Assemble the single file

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...&display=swap" />
    <script src="https://cdn.tailwindcss.com"></script>
    <style>
      /* Optional: resolved token vars, keyframes, base font-family */
      :root { --accent: #3e63dd; }
      body { font-family: "Inter", ui-sans-serif, system-ui, sans-serif; }
    </style>
  </head>
  <body>
    <!-- recreated markup -->
  </body>
</html>
```

- Icons/SVGs/logo: paste the **exact `<svg>` markup copied 1:1 from source** (see Step 2) — never a guessed or closest-glyph substitute. Inline SVG is already self-contained.
- Raster images (PNG/JPG/WebP/GIF): **reference the real asset in `src`** rather than inlining it, at its intrinsic width/height, preserving state variants (e.g. hover swaps). Point `src` at the real image so it resolves when the HTML is opened from its saved location — prefer a **path relative to the HTML file** (e.g. `src="public/img/foo.png"` when the HTML sits at the project root), or the **original remote URL** if the source used one. Emoji/placeholder only as an absolute last resort when no asset exists.
- If the source uses many custom colors, define them once as CSS vars in the inline `<style>` and reference them, to keep markup readable.

## Fidelity checklist

- [ ] Colors match the resolved token/theme values (not guessed named colors), resolved from the theme file
- [ ] Every icon/SVG matches source 1:1 (same viewBox/path/fill/stroke, copied verbatim, nothing guessed)
- [ ] Brand logo/wordmark copied verbatim from its source
- [ ] Real image assets used at correct dimensions (SVG inline; raster referenced by a path that resolves from the HTML's location, or a remote URL) — no emoji/placeholder stand-ins
- [ ] Design-system primitives reproduce the library's real rendering (track/indicator/shadow/label); selected state matches the library (not an invented accent fill)
- [ ] Spacing, font sizes, weights, and line-heights match
- [ ] Borders, radii, and shadows match (radius resolved to the exact px/rem, per-corner and `rounded-full` preserved, `overflow-hidden` kept where the parent clips children)
- [ ] Layout and responsive behavior preserved (flex/grid, breakpoints, intrinsic sizing)
- [ ] Hover/active/focus/disabled visual states preserved
- [ ] Fonts load and apply (no Times fallback)
- [ ] No framework/import artifacts, no editor-only props; file opens standalone in a browser

## Common mistakes

- Inferring an element's color from UI convention/memory instead of reading its source — e.g. painting a user chat bubble the accent color when the code says `bg-white border-border text-foreground`.
- Treating semantic classes (`bg-primary`, `text-foreground`, `border-border`) as literal colors instead of resolving their theme CSS variables.
- Guessing a Tailwind named color (`bg-indigo-600`) instead of resolving the actual token/theme value.
- Guessing/redrawing an SVG instead of copying it 1:1 (a distinctive icon comes out the wrong shape).
- Substituting a closest-glyph icon when the real SVG exists in source.
- Emoji or a generic placeholder instead of the real image asset.
- Referencing an image by a path that won't resolve from where the HTML is saved (e.g. an app-served `/img/...` path or a stale relative path) — make the `src` relative to the HTML file's location, or use the remote URL.
- Stopping at the app file instead of following imports into the design-system package/`node_modules`.
- Accent-filling a selected segment/tab/toggle when the library renders the active state as a neutral raised indicator (white + shadow, dark text).
- Inferring a design-system component's look from the app usage/prop names instead of the library's CSS/variant defaults.
- Eyeballing colors instead of reading the theme palette file.
- Substituting a Google/web font when the codebase ships the real font locally — use the local file via `@font-face` instead.
- Dropping fonts, so the page falls back to a serif default.
- Leaving library layout props (`gap`, `px`, `direction`) unconverted — they do nothing in raw HTML.
- Assuming a library's spacing step equals Tailwind's step without checking the scale.
- Approximating border radius with `rounded-md`/`rounded-lg` instead of resolving the exact px value; dropping per-corner radii, `rounded-full`, or the `overflow-hidden` that clips a rounded parent.
- Omitting hover/active/disabled states that the original clearly has.
- Splitting into multiple files — the output must be a single self-contained `.html`.
- Re-launching subagents to re-derive information already resolved in context instead of reusing it — or the inverse, trusting a vague mention/filename and skipping a concern that actually needs its values resolved.

## Example

User: "Take the `<ComponentName>` from my codebase and give me a raw HTML recreation."

1. Search for the named component, read it and its subcomponents.
2. Identify the styling system; convert framework markup to plain HTML, map layout props to Tailwind, and resolve every color/spacing/font token to a concrete value (arbitrary Tailwind values or inline styles).
3. Add the app's font `<link>` and set the root `font-family`.
4. Emit `<ComponentName>.html` with the Tailwind CDN and hand back the path.

View saved version →

---
name: recreate-as-react
description: Recreate a component, screen, or pasted code from any codebase as a self-contained React + TypeScript + Tailwind prototype (App.tsx / index.tsx / index.css, named exports, one component per file) that renders in the Magic Patterns prototype environment and faithfully reproduces the original's styling, colors, spacing, and fonts. Use when the user asks for a "React recreation", a "React version" of a component, "recreate X as React", or as the porting engine for the upload-to-magic-patterns and prototype skills.
---

# Recreate as React

Turn a component, screen, or pasted snippet into a **self-contained React + TypeScript + Tailwind prototype** — a small set of files that compiles and renders standalone (in the **Magic Patterns prototype environment** or any React sandbox) and reproduces the original's styling as faithfully as possible.

**Method: static.** Read the source and resolve its design tokens by inspection — do NOT run the app, Storybook, or a browser. Fidelity comes from carefully tracing whatever styling system the codebase uses down to concrete values, then re-expressing them in Tailwind (or the source's own props/tokens).

This works for **any codebase**. The styling system varies (Tailwind, CSS/SCSS, CSS Modules, styled-components / Emotion, vanilla-extract, a design-system library like Radix/MUI/Chakra/Mantine/shadcn, or plain inline styles). Step 2 is about identifying which one is in play and following the chain to real pixel/color/font values.

## Where this runs — the Magic Patterns environment

The file set this skill produces is exactly the scaffold Magic Patterns renders (`App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`), so it can be written straight into a Magic Patterns design. Conform to that environment so the upload compiles and renders:

- **React + TypeScript. No `any`** — define prop types/interfaces.
- **Named exports only** — never `export default` a React component.
- **One React component per file**; split large screens into sub-components rather than a monolith.
- **Tailwind CSS v3** — use it for net-new UI; for reproduced UI, prefer the source's own styling (see Step 2). Keep the `index.css` imports in the exact order below.
- **Icons:** `lucide-react` is available (import full names ending in `Icon`, e.g. `UserIcon`). For fidelity, inlining the **exact `<svg>` markup copied 1:1 from source** is preferred and also compiles in MP — never guess or redraw an icon.
- **Routing** (only if needed): `BrowserRouter` from `react-router-dom`.
- **Fonts:** `@import url(...)` in `index.css` — never `next/font`.
- **Images:** **absolute URLs only** (the original remote URL or the project's served URL) — app-relative paths won't resolve.
- **Package preferences when applicable:** `sonner` (toasts), `recharts` (charts), `@xyflow/react` (node/canvas), Leaflet (maps). Avoid `@react-three/fiber` / `@react-three/drei`.
- **The code must compile** — no unresolved imports, missing symbols, or type errors. If a dependency is unavailable, stub it locally so it still compiles.

## Output contract

Produce a **folder of React files** (default `./<ComponentName>/`). Keep it self-contained so it compiles and renders with no backend.

### Files to emit

```
<ComponentName>/
├── App.tsx              # entry component — renders the recreated UI
├── index.tsx            # standard mount (ReactDOM root → <App/>)
├── index.css            # Tailwind imports (exact order below) + fonts/tokens
├── tailwind.config.js   # any resolved custom colors/spacing/fonts
├── <ComponentName>.tsx  # the recreated component (named export)
├── components/          # sub-components, one per file (as needed)
└── mockData.ts          # hardcoded mock data (as needed)
```

`index.css` must keep these in **this exact order** — never reorder or remove them:

1. `@import url(...)` font imports (if any)
2. `@import 'tailwindcss/base';`
3. `@import 'tailwindcss/components';`
4. `@import 'tailwindcss/utilities';`
5. other `@import`s
6. custom CSS (keyframes, token vars, base `font-family`)

`App.tsx` is the entry point and renders `<ComponentName />`. Hand back the folder path when done.

### Output location when composed for upload

When another skill runs this as its porting step (`upload-to-magic-patterns`, `prototype`), do **not** write into the user's project. Emit the file set into a temporary working directory (`mktemp -d`; refer to it as `$TMP`, e.g. `$TMP/<ComponentName>/`) so the composing skill can read the files, write them into the Magic Patterns artifact, and then delete `$TMP`. Only write to `./<ComponentName>/` in the user's project when this skill is used standalone.

## Workflow

### Step 1 — Locate the source (use subagents to explore)

You MUST delegate the codebase exploration to `explore` subagents via the Task tool — do not read/grep the files yourself. Launch them with the `gpt-5.4-mini` model (fast, read-only), fanned out concurrently in a single batch, then do the React assembly yourself with what they return. Split the work, e.g.:

- One subagent finds the target component file(s) and lists its subcomponents / styled wrappers.
- One subagent **follows the component's imports into design-system/workspace packages and `node_modules`** (monorepo sibling packages, `@scope/*` packages) and, for every imported UI symbol (icons, logos, illustrations, bespoke SVG components), opens its real source and returns the **exact `<svg>` markup / asset path** — not a description. For any third-party design-system primitive (segmented control, tabs, switch, select, etc.), also read the **library's component CSS/default rendering** and return the actual default/hover/selected part styles (track color, indicator background + shadow, label colors, per-`size` padding/height/radius).
- One subagent identifies the styling system and locates the theme/token definitions (`tailwind.config`, `:root`/`globals.css` CSS vars, JS theme object, or the library's palette), resolving colors from the **theme source-of-truth file** (the palette/token definition) as concrete hex.
- One subagent finds the font setup, prioritizing **local font files** (`public/fonts/`, `assets/fonts/`, `@font-face` `src: url(...)`, `next/font/local`, `.woff2`/`.woff`/`.ttf`/`.otf`) and then any `@import`/`<link>`/`font-family` declarations, returning the real file paths.
- One subagent finds the **real image assets** (public/static image files, imported image sources) and returns their real paths / URLs, intrinsic width/height, and any hover/state variants.

Instruct each subagent to return the concrete resolved values (hex colors, px/rem, font families, weights, radii, shadows, verbatim SVG markup, asset paths) and exact file/line citations — not summaries — so you can assemble the React without re-reading.

- Named target (e.g. a component name, or "the pricing card", "the settings sidebar") → have a subagent find the component file(s) and everything that affects appearance (subcomponents, styled wrappers, imported CSS/theme files).
- Pasted code → use it directly, but still resolve any tokens, classes, or theme imports it references (delegate that lookup to a subagent).

### Step 2 — Identify the styling system and resolve to concrete values (the fidelity core)

First determine how this component is styled, then trace every style down to a real value (hex color, px/rem size, font family, weight, radius, shadow). **Prefer the source's own styling approach — don't re-derive it.** Rebuilding from scratch in approximate Tailwind is the #1 cause of an ugly recreation. Common systems:

- **Tailwind classes** → keep them verbatim where possible. Resolve custom classes from the project's `tailwind.config` (custom colors, spacing, fonts) into the concrete value and emit as an arbitrary value (`bg-[#...]`) or add the token to the output `tailwind.config.js`.
- **Semantic / aliased utility classes** (`bg-primary`, `text-foreground`, `border-border`, `bg-muted`, common in shadcn/Tailwind theme setups) are **not literal colors** — they resolve to CSS variables (`--primary`, `--foreground`, ...) defined in `globals.css`/`:root` or `tailwind.config`. Follow them to the real value; e.g. `border-border` is usually a light gray, `text-foreground` near-black — not the accent.
- **Plain CSS / SCSS / CSS Modules** → read the stylesheet; translate each rule to Tailwind utilities, or drop it into `index.css` if it's complex (keyframes, pseudo-elements, complex selectors).
- **styled-components / Emotion / vanilla-extract** → read the styled definitions and template literals; translate the resulting CSS to Tailwind (or inline `style={{…}}` when a utility can't express it).
- **Design-system library** (Radix/Radix Themes, MUI, Chakra, Mantine, shadcn, Ant, or an in-house wrapper) → **prefer importing the real package — Magic Patterns installs whatever is in the prototype's `package.json` (a real npm install).** Wrap in its theme provider with the same props the app uses so you get its exact token CSS for free. **Best case — the app's own design system is on npm:** `@magicpatterns/cubed` is published, so import it directly (`import '@magicpatterns/cubed/styles.css'`, components from `@magicpatterns/cubed`, wrap in its `ThemeProvider` with the same props the app uses — e.g. `<ThemeProvider accentColor="indigo" panelBackground="translucent">`). Cubed is a thin wrapper over **Radix Themes (`@radix-ui/themes`)** and re-exports its components nearly 1:1 (`Flex`, `Box`, `Text`, `Heading`, `Button`, `IconButton`, `Select`, `SegmentedControl`, `Tooltip`, …), so if you can't use Cubed, map `@magicpatterns/cubed` → `@radix-ui/themes` (`import '@radix-ui/themes/styles.css'`, `<Theme accentColor="indigo" grayColor="slate">`). The same applies to shadcn (Radix primitives), MUI, etc.: prefer the real package. Otherwise, map its layout/spacing props to Tailwind and resolve its **design tokens** (below) to concrete values.
- **Inline `style={{...}}`** → carry values over directly as inline `style` or the equivalent Tailwind class.

**Never infer a color from convention or memory — read the element.** The most damaging errors come from assuming what a color "should" be instead of reading the actual `className`/`style` on that element. Chat UIs are a classic trap: many apps use a white/bordered user-message bubble, not an accent-colored one — so do not paint the user bubble (or a button, badge, highlight) the accent color just because that's the common pattern. Open the source for each element and use the color it actually declares.

**Follow imports into design-system / workspace packages — they are the source of truth.** A component's appearance is often defined in code it imports, not in the file you're looking at. When a component renders an imported icon, logo, or bespoke SVG, open that component in its package (a monorepo sibling package or `node_modules`) and reproduce its **actual markup**. Never approximate a design-system component from its name — trace it to its definition.

**Icons, SVGs, and the logo MUST match the source 1:1 — never guess.**

- Copy the exact `<svg>` markup — same `viewBox`, `<path>` data, `fill`/`stroke`, `stroke-width`, and dimensions — verbatim from source (app file, icon package, or asset file). Do NOT redraw, simplify, approximate, or invent path data. Do NOT substitute a "closest glyph".
- If an icon/logo is rendered via a component or asset import, follow it into its package/asset source and copy the real SVG it emits, including the exact colors passed in for the relevant state.
- The brand logo/wordmark is a common miss: copy it verbatim from its source rather than eyeballing or reusing a stale/guessed path.
- The ONLY acceptable fallback when a source SVG truly cannot be located: stop and tell the user which icon could not be found rather than shipping a guessed one.

**Design-system primitives: reproduce the library's real rendering, not a guess.** For a third-party design-system component, the appearance (backgrounds, borders, shadows, the active/selected indicator, sizing per `size`/`variant`) is defined by **the library's own CSS and variant defaults** — not by the app usage or the prop names. Resolve the real look by importing the real package, reading the library's component CSS/source in `node_modules`, or using accurate knowledge of that library's documented default rendering, then reproduce it. **Do NOT accent-fill a selected/active segment, tab, toggle, or menu item by default** — many design systems render the active state as a neutral raised surface (white/panel background + subtle shadow, dark label text) on a muted track, not the brand accent.

**Resolving design tokens (CSS variables / theme scales).** When you see `var(--...)`, a theme object, or a scale reference, follow it to the source-of-truth value — do NOT guess a Tailwind named color that "looks close":

- Find where the token is defined (a `:root`/theme CSS file, a JS theme object, or the library's published palette) and use that exact value.
- Apply it as a Tailwind arbitrary value (`bg-[#...]`, `text-[#...]`, `border-[#...]`), add it to `tailwind.config.js`, or define it as a CSS var in `index.css` — but never leave a bare `var(--…)` undefined.
- For libraries with a numbered color scale (e.g. Radix's 1–12): **1–2** app/subtle backgrounds, **3–5** component backgrounds (normal/hover/active), **6–8** borders/separators/focus ring, **9–10** solid fills (9 = the accent solid, e.g. a primary button), **11** secondary/low-contrast text, **12** high-contrast text. Resolve the actual hex from the scale in use.

**Map layout/spacing/size props to Tailwind** regardless of library:

- `direction="column"` → `flex-col`; `align="center"` → `items-center`; `justify="between"` → `justify-between`
- `gap`, `px`, `py`, `p`, `m*` spacing steps → the matching Tailwind step (verify the scale — some libraries' step N ≠ Tailwind's step N)
- Preserve `size`/`variant`/`weight` semantics by translating to the resolved font size, weight, and fill.

**Border radius — resolve the exact value, don't approximate.** `rounded-md` (6px) rarely matches the source. Trace the real radius to a px/rem value and emit it as an arbitrary utility (`rounded-[10px]`). Named library radii (`radius="large"`, `--radius-3`) are tokens, not pixels — look up the resolved px (many libraries multiply by a scaling factor). A pill uses `rounded-full`; match per-corner radii (`rounded-t-[10px]`); keep `overflow-hidden` where a rounded parent clips children; inner radius usually = outer radius minus padding/border.

**Preserve intent.** Keep responsive prefixes (`md:`, `lg:`), visibility/sizing (`hidden md:inline-flex`, `w-fit`, `whitespace-nowrap`), and hover/active/focus/disabled visual states.

**Prioritize mobile responsiveness — build mobile-first.** The recreation must render and read well on small screens, not just desktop. Carry over every responsive prefix and breakpoint the source declares (`sm:`/`md:`/`lg:`/`xl:`), and where the source has no explicit mobile handling, add sensible responsive behavior yourself so nothing overflows at narrow widths: stack multi-column layouts vertically, let flex rows wrap, collapse or make navigation scrollable, use fluid widths (`w-full`, `max-w-*`, percentage/`min()`/`clamp()`) instead of fixed pixel widths, keep touch targets comfortably tappable, and allow horizontal scroll only where genuinely unavoidable (e.g. wide tables). Default to a phone-width viewport as the baseline and layer desktop enhancements on top with breakpoints.

### Step 3 — Strip runtime, keep the UI

Make the prototype self-contained so it renders with no backend. This applies to **runtime logic only** — never to styling:

- [ ] Real API calls, `fetch`/`axios`, server actions, tRPC, DB queries → replace with **hardcoded mock data** (inline or `mockData.ts`).
- [ ] Auth guards, protected routes, session logic → render unconditionally.
- [ ] Environment variables and secrets → inline safe constants.
- [ ] Project-specific aliases/imports that won't resolve → local stubs or equivalents.
- [ ] Stub interactivity: controlled inputs with local `useState`, handlers that update local state; no network.

### Step 4 — Fonts

Detect the font source and reproduce it via `@import url(...)` at the **top** of `index.css`. Prefer the codebase's real typeface:

1. **Local font files** → if the project ships fonts (`public/fonts/`, `@font-face src: url(...)`, `next/font/local`, `.woff2`/`.woff`/`.ttf`/`.otf`), add a `@font-face` block in `index.css` pointing at an absolute path or the project's served URL, and note the source in a comment.
2. **Google Fonts** → add the matching `@import url('https://fonts.googleapis.com/css2?family=...&display=swap');`.
3. **Third-party (Typekit/Adobe)** → mirror the `@import url(...)`.
4. **Closest web substitute** → last resort; note the substitution.

Apply the correct `font-family`, weights, sizes, and line-heights on the root/body and headings (via `index.css` base layer or `tailwind.config.js` `fontFamily`).

### Step 5 — Plan the files, then parallelize the writes with subagents

You (the main model) do the **thinking**: from the concrete values resolved in Step 2, produce a high-level spec of the output — the file list, which component lives in which file, the props/mock-data shapes, and the resolved tokens (colors, spacing, radii, fonts, verbatim SVG markup) each file needs. Then **delegate the actual file writing to `gpt-5.4-mini` subagents (via the Task tool), fanned out concurrently in a single batch** so independent files are written in parallel.

- Give each subagent a self-contained brief: the exact file path to write, the full resolved values it needs (concrete hex, px/rem, font families, verbatim `<svg>` markup, mock-data shape), and the Output-contract rules (named exports, one component per file, Tailwind arbitrary values, no `any`, `index.css` import order). Subagents must not re-derive styling or re-read the source — hand them the resolved values so they only assemble.
- Group by independence: e.g. one subagent per sub-component file, one for `index.css` + `tailwind.config.js`, one for `mockData.ts`. Keep files that must agree on a shared interface (e.g. a component and its props type) in the same brief.
- After the subagents return, you assemble/verify: confirm imports line up across files, the `index.css` import order is intact, and everything compiles. Fix any seams yourself.

Skeletons for the entry files (include these in the relevant subagent brief):

```tsx
// index.tsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';
import './index.css';

const root = createRoot(document.getElementById('root')!);
root.render(<App />);
```

```tsx
// App.tsx
import React from 'react';
import { ComponentName } from './ComponentName';

export function App() {
  return <ComponentName />;
}
```

```css
/* index.css */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

:root {
  --accent: #3e63dd;
}
body {
  font-family: 'Inter', ui-sans-serif, system-ui, sans-serif;
}
```

- Raster images (PNG/JPG/WebP): reference the real asset in `src` at its intrinsic width/height, preserving state variants. Use an **absolute URL** (the original remote URL, or the project's served URL) so it resolves anywhere — do not use app-relative paths that won't resolve. Emoji/placeholder only as a last resort when no asset exists.
- Icons/logos/bespoke SVGs: inline the exact `<svg>` copied 1:1 from source.
- If the source uses many custom colors, define them once (CSS vars in `index.css` or `tailwind.config.js` `theme.extend.colors`) and reference them.

## Fidelity checklist

- [ ] Output is the React file set (`App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`, component files) and compiles — no unresolved imports or type errors, no `any`
- [ ] Named exports only; one component per file; `index.css` Tailwind imports in the exact order
- [ ] Colors match the resolved token/theme values (not guessed named colors), resolved from the theme file
- [ ] Every icon/SVG/logo matches source 1:1 (same viewBox/path/fill/stroke, copied verbatim, nothing guessed)
- [ ] Real image assets used at correct dimensions via absolute URLs — no emoji/placeholder stand-ins, no app-relative paths
- [ ] Design-system primitives reproduce the library's real rendering (track/indicator/shadow/label); selected state matches the library (not an invented accent fill)
- [ ] Spacing, font sizes, weights, and line-heights match
- [ ] Borders, radii, and shadows match (radius resolved to exact px/rem, per-corner and `rounded-full` preserved, `overflow-hidden` kept where the parent clips children)
- [ ] Layout and responsive behavior preserved (flex/grid, breakpoints, intrinsic sizing)
- [ ] Mobile-first: renders and reads well at phone widths — no overflow, columns stack, nav collapses/scrolls, fluid widths instead of fixed pixels, touch-friendly targets
- [ ] Hover/active/focus/disabled visual states preserved
- [ ] Fonts load via `@import url()` in `index.css` and apply (no serif fallback)
- [ ] Runtime stripped: mock data instead of fetch/auth/env; nothing needs a backend

## Common mistakes

- Rebuilding the UI from scratch in approximate Tailwind instead of reproducing the source's real values/library — the most common cause of an ugly recreation.
- Stubbing or approximating a library Magic Patterns could just install — MP installs from `package.json`; if the source uses Cubed / Radix Themes / shadcn / MUI, add the real package and import its theme CSS instead of hand-rolling look-alikes.
- Inferring an element's color from UI convention/memory instead of reading its source (e.g. accent-coloring a user chat bubble the code declares as `bg-white border-border text-foreground`).
- Treating semantic classes (`bg-primary`, `text-foreground`, `border-border`) as literal colors instead of resolving their theme CSS variables; leaving bare `var(--…)` undefined.
- Guessing a Tailwind named color (`bg-indigo-600`) instead of resolving the actual token/theme value.
- Guessing/redrawing an SVG or brand logo instead of copying it 1:1 (a distinctive icon comes out the wrong shape).
- Default-exporting the root component.
- Reordering or deleting the Tailwind imports in `index.css` — breaks all styling.
- Emoji or a generic placeholder instead of the real image asset; app-relative image paths that won't resolve (use absolute URLs).
- Stopping at the app file instead of following imports into the design-system package/`node_modules`.
- Accent-filling a selected segment/tab/toggle when the library renders the active state as a neutral raised indicator (white + shadow, dark text).
- Approximating border radius with `rounded-md`/`rounded-lg` instead of resolving the exact px value; dropping per-corner radii, `rounded-full`, or the `overflow-hidden` that clips a rounded parent.
- Pasting production runtime code (fetch/auth/env) verbatim so it fails to compile or renders blank — strip and stub it.
- Building desktop-only — dropping the source's responsive behavior or hardcoding fixed pixel widths so the recreation overflows or breaks on mobile. Build mobile-first and keep it usable at small viewport widths.

## Example

User: "Take the `<PricingCard>` from my codebase and give me a React version."

1. Delegate exploration: subagents find `PricingCard` and subcomponents, follow imports for icons/logo/tokens, resolve the theme palette and fonts, and return concrete values + verbatim SVG.
2. Identify the styling system; resolve every color/spacing/font token to a concrete value (arbitrary Tailwind values, `tailwind.config.js` tokens, or inline styles). Inline the icons/logo SVG 1:1.
3. Strip any runtime (fetch/auth) → mock data; add the app's font `@import` to `index.css`.
4. Plan the file list + resolved values, then fan out `gpt-5.4-mini` subagents to write `App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`, `PricingCard.tsx` (named export) in parallel from that spec. Verify the seams compile and hand back `./PricingCard/`.

## Related

- `upload-to-magic-patterns` — runs this skill as its porting step, then writes the file set into a hosted Magic Patterns design.
- `prototype` — seeds a Magic Patterns design with this skill, then prompts Magic Patterns to design a new idea on top.

View saved version →

---
name: upload-to-magic-patterns
description: Upload UI you are building locally into Magic Patterns (magicpatterns.com) and return the editor link. Use when the user wants to push a component/screen they are working on in their codebase into Magic Patterns as a design — for review, stakeholder sign-off, or further iteration. Requires the Magic Patterns MCP server.
---

# Upload local UI to Magic Patterns

Use this skill to push UI from the current codebase into a **hosted Magic Patterns design** and hand back the editor link. You port the local UI into a Magic Patterns-ready React file set with the `recreate-as-react` skill, then **write those files into a blank design directly** — you do not prompt Magic Patterns to generate anything. The destination is a real Magic Patterns design, created through the Magic Patterns MCP server.

Magic Patterns renders **visual prototypes**, not production apps. Local production code will not run there as-is — it must be ported to Magic Patterns' constraints first. `recreate-as-react` does that port; this skill wires the result into a design.

**Keep the scope minimal.** Upload only what the user wants to prototype — the specific component or screen and the smallest set of files needed to render it. This is not a tool for mirroring the whole app; a tighter upload compiles more reliably and is faster to iterate on.

## Prerequisites

- The Magic Patterns MCP server must be connected (tools prefixed `magic-patterns`). If the tools are unavailable, tell the user to install/enable the Magic Patterns plugin or MCP server, and stop.
- Magic Patterns MCP usage requires a paid plan. A `Payment Required` / credits error means the user must upgrade at `magicpatterns.com/settings`.

## Workflow

### Step 1 — Pick the minimal scope to prototype

Identify the specific component(s) or screen the user wants to prototype, and the smallest set of files needed to render it. Do not pull in the whole app — keep the upload tight to what the user actually wants to see.

### Step 2 — Port to a Magic Patterns-ready file set (run `recreate-as-react`)

Run the **`recreate-as-react`** skill to turn the target into a self-contained React + TypeScript + Tailwind file set (`App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`, component files). That skill already targets the Magic Patterns environment and carries the fidelity rules that make the upload look right — follow it in full. In particular it:

**Emit into a temp dir, not the project.** Tell `recreate-as-react` to write the file set into a temporary working directory (`mktemp -d`, referred to as `$TMP`) so nothing is left behind in the user's repo — this skill reads those files and writes them into the design, then deletes `$TMP` (Step 4).

### Step 3 — Create a blank design and upload the files directly

Create a blank design and write the ported files into it. **Do not use `send_prompt` or any AI generation** — write the files yourself. Use the Magic Patterns MCP tools in this order:

1. `create_design` with no prompt → "start from scratch": returns `editorId`, the active `artifactId` (a blank scaffold: `App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`), and the `editorUrl`. This returns immediately.
2. `get_design_status(editorId)` → confirm the active `artifactId` and that `isGenerating` is false.
3. `write_artifact_files(artifactId, files)` → write the ported files from `$TMP` directly. Include `App.tsx` as the entry component and update `index.css` if you added fonts/tokens.
4. `publish_artifact(artifactId, editorId)` → compiles and activates the artifact so the preview renders.

If you need to preserve the original scaffold as a separate version, call `create_new_artifact(artifactId, name)` before writing and use the returned artifact ID for the writes.

### Step 4 — Hand back the link, open it, and clean up

Return the `editorUrl` to the user so they can keep iterating in Magic Patterns, and tell them they may need to log in. If `publish_artifact` reported compile errors, fix the offending files and publish again before returning the link.

**Always open the `editorUrl` for the user — don't just print it.** Open it in the user's **default browser** with the OS opener: run `open <url>` on macOS, `xdg-open <url>` on Linux, or `start <url>` on Windows. Only skip opening if the user explicitly asked you not to.

Then delete the temp working directory (`rm -rf "$TMP"`) so nothing is left in the user's project.

## Common mistakes to avoid

- **Uploading too much** — pulling in the whole app instead of the minimal scope the user wants to prototype. Keep it tight.
- **Prompting instead of writing files** — this skill writes the files directly with `write_artifact_files`; do not use `send_prompt` to generate the UI.
- **Skipping the `recreate-as-react` port** — pasting production code unchanged (live `fetch`/auth/env) fails to compile or renders blank. Always port first.
- **Rebuilding the UI from scratch in approximate Tailwind** — the most common cause of an ugly upload. `recreate-as-react` prefers importing the source's real component library (e.g. Cubed → `@radix-ui/themes`); let it.
- **Reordering or deleting the Tailwind imports** in `index.css` — breaks all styling.
- **Default-exporting the root component** or leaving non-`lucide-react` icons in place.
- **Relative image paths** — use absolute URLs.
- **Returning the link before `publish_artifact` succeeds** — confirm it compiled first.
- **Leaving the temp dir behind** — delete `$TMP` after uploading.

## Related

- `recreate-as-react` — the porting engine: turns the local UI into the Magic Patterns-ready React file set this skill uploads.
- `prototype` — seed with this flow, then prompt Magic Patterns to design a new idea on top.
- `integrate-magic-patterns-design` — go the other direction: bring a Magic Patterns design into this codebase as production code.