/stitch-swiftui-components

name: stitch-swiftui-components
description: Converts a Stitch mobile screen, a local HTML file, or a URL into SwiftUI views for native iOS apps — VStack/HStack/ZStack layout mapping, Color asset tokens with dark mode, NavigationStack/TabView routing, and Xcode project structure. Only the Stitch route needs an API key.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"

Stitch → SwiftUI (Native iOS)

You are a Swift/SwiftUI engineer. You convert mobile UI layouts — a Stitch screen generated with `deviceType: MOBILE`, a local HTML file, or a URL — into native iOS SwiftUI views — `.swift` files that build and run in Xcode. You follow Apple's Human Interface Guidelines and produce code that feels like it belongs on iOS.

When to use this skill

Use this skill when:

• The user wants **native iOS** output from an existing design
• The user mentions "SwiftUI", "Xcode", "iOS", "native iOS app"
• The source is a **mobile layout** — narrow, vertical, touch-sized targets (a Stitch screen with `deviceType: MOBILE`, or a local file/URL that reads as mobile)

**Note:** This skill targets iOS 16+ with SwiftUI. For cross-platform (iOS + Android), use `stitch-react-native-components` instead.

Prerequisites

A mobile-layout source, read as structural and visual reference only — nothing here ships, SwiftUI views get written from scratch. Any one of these works:

• A **Stitch screen** — needs Stitch MCP access and a screen generated with `deviceType: MOBILE`
• A **local HTML file** of a mobile layout — no Stitch account required
• A **URL** rendering a mobile layout — no Stitch account required

Desktop layouts don't map well to SwiftUI without significant rethinking, regardless of which route you took.

Also:

• Xcode 15+ on macOS
• Swift 5.9+

Step 1: Resolve the source

Everything downstream reads one file: `temp/source.html`. Get the HTML there by whichever route matches what the user gave you, then continue at Step 2 — the rest of this skill is identical regardless of where the markup came from.

This skill only works on a **mobile layout** — narrow, vertical, touch-sized targets. Desktop layouts don't map well to SwiftUI without significant rethinking, regardless of source. How you confirm mobile-ness depends on where the HTML came from:

• **Stitch screen** — check it was generated with `deviceType: MOBILE`. If the screenshot shows a desktop layout, stop and tell the user to regenerate with `deviceType: MOBILE` first.
• **Local HTML file or URL** — inspect the markup: a `<meta name="viewport">` tag, mobile-first media queries, a narrow `max-width` on the root container, touch-sized tap targets. If it's clearly a desktop layout (wide multi-column grid, hover-only interactions, no viewport meta), stop and tell the user the source isn't a mobile layout — don't tell them to "regenerate with deviceType: MOBILE," that instruction is meaningless outside Stitch.

**From a Stitch screen:**

1. **Namespace discovery** — `list_tools` to find the Stitch MCP prefix 2. **Fetch metadata** — `[prefix]:get_screen` for the design JSON 3. **Download HTML** — GCS URLs need the reliable downloader:

   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"

4. **Visual audit** — check `screenshot.downloadUrl` before converting. Append `=s0` to that URL for full resolution; the bare URL serves a 512px thumbnail regardless of the `width`/`height` the API reports. Confirm it's a mobile layout, per the check above.

**From a local HTML file:**

mkdir -p temp && cp "path/to/design.html" temp/source.html

Open it and confirm it's a mobile layout, per the check above.

**From a URL:**

bash scripts/fetch-stitch.sh "https://example.com/page" "temp/source.html"

Despite the name, that script is a generic hardened downloader — follows redirects, retries transient failures, handles gzip, and fails loudly on an empty result. It does not care whether the URL points at Stitch. Confirm the page is a mobile layout, per the check above.

**From a screenshot:** there's no upload route — the Stitch MCP API has no image-upload tool. Either recreate the design from a text prompt via `stitch-mcp-generate-screen-from-text`, or hand-write the HTML and use the local-file route above.

> Only the Stitch route needs an API key. Converting a local file or a URL works with no Google account at all.

Step 2: Xcode project structure

MyApp/
├── MyApp.swift              ← @main entry point
├── ContentView.swift        ← Root view (TabView or NavigationStack)
├── Theme/
│   ├── ThemeTokens.swift    ← Design token constants
│   └── Color+App.swift      ← Color extension with semantic names
├── Views/
│   ├── [ScreenName]View.swift   ← One file per screen
│   └── Components/
│       └── [Name]View.swift     ← Reusable component views
├── Models/
│   └── MockData.swift       ← Static preview data
└── Assets.xcassets/
    └── Colors/              ← Color assets for light/dark mode

Step 3: The HTML/CSS → SwiftUI layout mapping

This is the core translation. Apply these rules to every element in the source HTML:

Layout containers

| HTML/CSS pattern | → SwiftUI | |---|---| | `display:flex; flex-direction:column` | `VStack(alignment: .leading, spacing: 16)` | | `display:flex; flex-direction:row` | `HStack(alignment: .center, spacing: 12)` | | `display:flex; justify-content:space-between` | `HStack { Spacer() }` pattern | | `position:absolute` overlay | `ZStack` with layered views | | `display:grid` (2-column) | `LazyVGrid(columns: [GridItem(.flexible()), GridItem(.flexible())], spacing: 16)` | | `overflow-y: scroll` | `ScrollView(.vertical, showsIndicators: false)` | | Repeated list of items | `List` or `ForEach` inside `ScrollView + LazyVStack` | | `position:fixed` bottom nav | `TabView` (preferred) or explicit `VStack` with `Spacer()` |

Spacing mapping

SwiftUI uses points (1pt ≈ 1dp on non-retina, 2px on Retina @2x):

// Spacing from