## Workflows

There are two primary ways to use the Magic Patterns MCP tools.

## Prompt-based

Delegate creative work to Magic Patterns’ AI. Send a natural language prompt and let the AI generate or update code.

## Code-first

Write code directly into artifacts. Create a working branch, edit files, and publish when done.

### Workflow A — Prompt-based

**Starting from scratch:**

```
1. create_design(prompt, ...)         → kicks off AI generation
2. get_design_status(editorId)        → poll every 60s until isGenerating=false
```

**With an existing design:**

```
1. get_editor_id_from_url(url)        → resolve a Magic Patterns URL to an editorId
2. get_design_status(editorId)        → check current state before acting
3. send_prompt(editorId, prompt)      → send prompt (returns immediately)
4. get_design_status(editorId)        → poll every 60s until isGenerating=false
```

### Workflow B — Code-first

```
1. create_design()                    → no prompt, creates blank design instantly
2. get_design_status(editorId)        → confirm active artifact is ready
3. create_new_artifact(artifactId, name)  → create a working branch
4. read_artifact_files(artifactId, fileNames) → read existing scaffolding
5. write_artifact_files(artifactId, files) → write one or more files at once
6. publish_artifact(artifactId, editorId)  → compile + activate
```

## Important Guidance

**Collaborative editing:** Magic Patterns is a collaborative editor — the user can make changes in the UI at any time. Always call `get_design_status` before starting new work to get the latest active artifact. Never assume state from a previous call is still current.

**Polling:** AI generation typically takes **2–10 minutes**. Poll `get_design_status` no more frequently than **every 60 seconds**. Slow generation is normal — do not treat it as an error.

## General Tools

list_design_systems

Tool

Lists the design systems available to the authenticated user. Returns both built-in presets (e.g. Base, Shadcn, MUI) and any custom design systems.

### Show Returns

Array of design systems, each with:
- `id` — unique design system ID (pass to `create_design`)
- `name` — human-readable name
- `isReserved` — whether it is a built-in preset
- `isActive` — whether this is the user’s currently active design system

## Design Tools

create_design

Tool

Creates a new Magic Patterns design. This is the starting point for both workflows.

- **With `prompt`**: Kicks off AI generation (long-running, 2–10 minutes). Poll `get_design_status` every 60s.
- **Without `prompt`**: Creates a blank design with scaffold files (`App.tsx`, `index.tsx`, `index.css`, `tailwind.config.js`). Returns immediately.
- **With `templateId`**: Forks an existing design first, then optionally applies the prompt to the fork.

### Show Parameters

- **name** (string): Optional name for the design. Defaults to “Untitled”.
- **prompt** (string): Optional natural language prompt. If omitted, a blank design is created instantly.
- **imageUrls** (string[]): Optional image URLs as visual references (only used with prompt).
- **designSystemId** (string): Optional design system ID. Use `list_design_systems` to discover IDs.
- **designSystem** (string): Optional design system name (e.g. “Shadcn”, “MUI”). Resolved case-insensitively. `designSystemId` takes precedence if both provided.
- **templateId** (string): Optional editor ID of an existing design to use as a template. The design is forked before any prompt is applied.

### Show Returns

- `editorId` — the editor ID for subsequent operations 
- `editorUrl` — URL to edit the design 
- `previewUrl` — URL to preview the design 
- `activeArtifactId` — the currently active artifact ID 
- `availableFiles` — array of file paths

## Video Walkthrough

Getting existing code from your codebase into Magic Patterns:

[Roundtrip between design and code with the Magic Patterns MCP](https://www.youtube.com/watch?v=2QOc6vXftHo)  
  
Magic Patterns1.73K subscribers