claude-design-to-swiftui

name

claude-design-to-swiftui

description

This skill should be used when the user asks to "convert a Claude design to SwiftUI", "turn a prototype into iOS code", "convert HTML to SwiftUI", or provides a Claude design URL (e.g. https://api.anthropic.com/v1/design/h/<id>?open_file=<name>) or .tar.gz archive to translate. Fetches the design, renders the prototype, generates a single SwiftUI View file, writes it into the active Xcode workspace, builds it, renders the SwiftUI preview, and visually diffs against the prototype until they match.

HTML prototype → SwiftUI View

This skill converts a Claude-generated HTML/CSS prototype (delivered as a design URL from api.anthropic.com/v1/design/h/..., or a local .tar.gz archive) into a single SwiftUI View file inside the user's active Xcode workspace.

The output is one self-contained .swift file: one View struct + a #Preview, plus inline Path-based icons and any imported image assets. No multi-screen navigation and no JS interactivity — visual layout fidelity only.

Required MCP servers

This skill calls into two MCP servers. If either is missing, stop and tell the user how to enable it.

• xcode-tools (Apple's native Xcode MCP, ships with Xcode 26.3+ as xcrun mcpbridge). Bundled in this plugin's .mcp.json. The user must enable it once: Xcode → Settings (⌘,) → Intelligence → Xcode Tools → ON. Xcode must be running with the target project open.
• claude-in-chrome (user-installed). Used to render the HTML prototype for screenshotting.

Workflow

Follow these steps in order. Do not skip the build or visual-diff steps.

1. Fetch the design and start a local server

"${CLAUDE_PLUGIN_ROOT}/skills/claude-design-to-swiftui/scripts/fetch.sh" <design-url-or-tarball-path>

Accepts either a Claude design URL (https://api.anthropic.com/v1/design/h/<id>?open_file=<name>) or a local .tar.gz path. The script downloads (if needed), unpacks to a temp directory, starts a localhost-bound python3 -m http.server on a free port, and prints three lines on stdout:

1. The URL to the entry HTML (e.g. http://127.0.0.1:51234/index.html)
2. The server PID (capture for cleanup in step 8)
3. The unpack directory (capture for cleanup in step 8)

Entry resolution: URL-decoded open_file= query param → index.html → first *.html. The local server is required because Claude designs commonly use ES modules / fetch() which fail under file:// origins.

Note: design URLs are one-shot/short-lived. Fetch immediately; if it 404s, ask the user for a fresh URL.

2. Render the prototype in Chrome

Use claude-in-chrome to render the prototype at iPhone-class viewport:

1. mcp__claude-in-chrome__tabs_create_mcp → open the URL from step 1 (do not use file://).
2. mcp__claude-in-chrome__resize_window → 390x844 (iPhone 15 Pro logical size).
3. mcp__claude-in-chrome__computer (screenshot action) → capture the rendered page.

Keep this screenshot — the prototype reference for step 7's diff loop.

3. Read the HTML/CSS source and inventory assets

Read the entry HTML and every linked stylesheet (<link rel="stylesheet">) and inline <style> block. Build a mental model of:

• The DOM tree (containers, leaves, text)
• The styles applied to each container (layout mode, spacing, colors, typography, borders, shadows)
• Repeated patterns that should become reusable subviews

Also do an asset inventory pass (used in step 4):

• Inline <svg> elements — collect the unique ones (after whitespace normalization). Most Claude designs put icons inline this way.
• Google Fonts — parse any <link href="https://fonts.googleapis.com/css2?family=...". The &family= segments give the font families (URL-decode + to space).
• <img> tags — separate into local paths (relative to the entry HTML) vs external URLs (http:///https://).
• Background images in CSS (background-image: url(...)) — same separation as <img>.

Skip <script> tags — JS behavior is out of scope. (For React/JSX prototypes, the JSX iconSvg map and component tree are still the source of truth for what gets rendered — read them like a description of the DOM.)

4. Translate to SwiftUI

Walk the DOM top-down using the reference mappings (loaded on demand):

• Layout containers → references/layout-mapping.md (flex/grid/block → VStack/HStack/ZStack/Grid/ScrollView)
• CSS properties → references/styling-mapping.md (padding, background, border, shadow → SwiftUI modifiers)
• Typography → references/typography-mapping.md (font-family/size/weight → .font() / .fontWeight() / .lineSpacing())
• Common patterns (cards, buttons, list rows, nav bars) → references/component-patterns.md

For the assets inventoried in step 3, run them through these handlers:

• Inline SVGs → first try references/svg-to-sfsymbol.md (curated SF Symbol map). On miss, fall back to references/svg-path-translation.md (emit a fileprivate struct FooIcon: View with a hand-translated Path).
• Google Fonts → references/font-mapping.md. Default behavior: map each detected family to its closest SwiftUI system equivalent and emit a // Fonts detected in prototype comment block at the top of the file. Original-font fidelity requires manual user steps (download .ttf, drag into Xcode, edit Info.plist UIAppFonts) — the Xcode 26.3 MCP exposes no tools for project-file or Info.plist mutation; see the "Original-font fidelity" section in references/font-mapping.md for the recipe to hand the user.
• <img> tags / CSS background-image → references/asset-catalog-import.md. Local files get imported into Assets.xcassets/<name>.imageset/; external URLs become AsyncImage.

When unsure how a chunk maps, see examples/01-landing-card/ and examples/02-list-with-rows/ for end-to-end before/after pairs.

Translation rules:

• Preserve hierarchy — wrapping <div> becomes a wrapping VStack (or whatever container fits).
• Inline literal pixel values (padding: 16px → .padding(16)); don't abstract into design tokens for v1.
• Use Color(hex:) from a fileprivate extension Color at the bottom of the file (so it doesn't collide with helpers in the user's project).
• Custom Path-based icons go next to the Color extension as additional fileprivate struct FooIcon: View declarations. Reuse one struct across multiple usage sites of the same SVG.
• Wrap in ScrollView if content is taller than 844pt.

5. Locate the Xcode workspace and write the file

1. Call mcp__plugin_claudedesign-to-swiftui_xcode-tools__XcodeListWindows to find the open workspace and its on-disk root path.
2. Pick a meaningful filename based on the prototype's purpose (e.g., OnboardingView.swift, SettingsListView.swift). If multiple workspace folders exist, ask the user which target group to write into. If only one obvious group exists, write there.
3. Call mcp__plugin_claudedesign-to-swiftui_xcode-tools__XcodeWrite with the chosen path and the generated SwiftUI source.

Required file structure:

import SwiftUI

// Fonts detected in prototype (mapped to SF equivalents):    ← only when Google Fonts detected
//   Newsreader  → .system(design: .serif)
//   Geist Mono  → .system(design: .monospaced)

struct MeaningfulName: View {
    var body: some View {
        // ...translated layout...
    }
}

#Preview {
    MeaningfulName()
}

// At file bottom, in this order, each only if used:
//   1. fileprivate extension Color { init(hex: String) ... }   ← if any hex colors
//   2. fileprivate struct FooIcon: View { ... Path { ... } }   ← one per unique custom SVG
fileprivate extension Color {
    init(hex: String) { /* ... */ }
}

The file must compile standalone — no external packages, no references to types defined elsewhere in the user's project.

6. Build and fix until clean

1. Call mcp__plugin_claudedesign-to-swiftui_xcode-tools__BuildProject for the active scheme.
2. If errors:
   • Call mcp__plugin_claudedesign-to-swiftui_xcode-tools__XcodeListNavigatorIssues to read structured diagnostics.
   • Before patching, check references/swiftui-gotchas.md — most build failures here (expression-too-complex, ForEach Identifiable, Color(hex:) not found, foregroundColor vs foregroundStyle, etc.) have a known fix that's faster than diagnosing from the raw error.
   • Patch the file with mcp__plugin_claudedesign-to-swiftui_xcode-tools__XcodeUpdate.
   • Re-run BuildProject.
   • Loop. If the same error recurs after two patch attempts, surface it to the user with the diagnostic and your interpretation.
3. Continue once the build succeeds.

7. Render the SwiftUI preview and visually diff

For tall designs (anything that scrolls past 844pt — long landing pages, settings screens with many rows, dashboards with multiple cards): before calling RenderPreview, modify the #Preview { ... } block to force a frame tall enough to capture the whole layout, otherwise the preview only renders the iPhone viewport's top ~844pt and below-the-fold content goes un-diff'd:

#Preview {
    MeaningfulName()
        .previewLayout(.sizeThatFits)
        .frame(width: 390, height: 1800)   // estimate from prototype screenshot height
}

Pick the height by eyeballing the prototype screenshot from step 2 (use the rendered HTML's full document height, not the 844 viewport). Better to overshoot — the preview will whitespace-pad the bottom but at least nothing is hidden.

For single-screen designs (≤ 844pt), skip this — the default preview is fine.

1. Call mcp__plugin_claudedesign-to-swiftui_xcode-tools__RenderPreview for the file you just wrote — it returns the actual rendered preview as an image.
2. Compare against the prototype screenshot from step 2:
   • Layout: containers in the right positions, with the right spacing?
   • Sizing: widths/heights/proportions correct?
   • Colors: backgrounds/text/borders match?
   • Typography: font sizes/weights look right?
   • Iconography & images: placeholders in roughly the right spots?
   • Below-the-fold content present? If you didn't extend the preview frame and the prototype is taller than 844pt, explicitly tell the user "preview only verified the top viewport — below-the-fold content (X, Y, Z) was generated but not auto-diff'd."
3. Produce a concrete list of discrepancies with proposed patches (specific line edits, not vague "make it more X").
4. Apply patches via mcp__plugin_claudedesign-to-swiftui_xcode-tools__XcodeUpdate, then go back to step 6 (build) → step 7 (re-render).
5. Loop until the diff is acceptable. After three iterations without convergence, stop and present the remaining diff to the user.

When done, show the user: the prototype screenshot, the final preview screenshot, and the path to the file you wrote.

8. Stop the local server and clean up

"${CLAUDE_PLUGIN_ROOT}/skills/claude-design-to-swiftui/scripts/stop.sh" <pid> <dir>

Pass the PID and directory captured in step 1. This kills the http.server process and removes the unpack directory. Always run this even if earlier steps failed.

Fallback when MCP servers are unavailable

If xcode-tools MCP is not available (e.g., Xcode < 26.3, MCP not enabled, or no project open):

• Use the standard Write tool to emit the .swift file. Ask the user where to put it.
• Skip steps 6 (build) and 7 (auto-diff). Instead, ask the user to open it in Xcode, run the SwiftUI Preview manually, screenshot it, and paste it back. Then do the visual diff manually.

If claude-in-chrome MCP is not available:

• Tell the user the prototype reference screenshot can't be captured automatically. Offer to skip the screenshot step and proceed without a visual reference (degraded mode), or ask them to open the HTML themselves and paste a screenshot.

When NOT to use this skill

• Multi-screen flows or navigation hierarchies — this emits one View only.
• Prototypes whose primary value is JS interactivity (animations, drag/drop, state machines).
• Requests to generate a full Xcode project from scratch.
• Conversions from Figma, Sketch, or screenshot-only inputs (no HTML source).