/ui-prototyping

name: ui-prototyping
description: Explore multiple *divergent* UI directions for a screen as named Swift #Previews, remix the strongest elements into hybrids, fill them with lived-in sample content and edge-case states, then tune signature animations with a generated tuning panel. Produces real native SwiftUI you carry forward, not throwaway mockups. Use early — after new-app or at the start of any UI-heavy phase, before /apple:plan commits to a single layout. Based on Apple's WWDC method for prototyping with coding agents in Xcode: go wide → remix → make lived-in → tune.
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22

UI Prototyping Skill

Task lists and specs commit you to **one** layout before you've seen the alternatives. The cost is quiet but large: you anchor on the first arbitrary structure an agent guessed, then spend the rest of the phase fighting feature creep around it. This skill front-loads *divergent exploration* — many real, named SwiftUI variations you flip between in Xcode's canvas — so the layout you carry into `/apple:plan` is one you **chose**, not one you defaulted into.

> **Agents are collaborators, not designers. You always have final say.** Go wide, remix, repeat.

Why this exists (the trap it removes)

A vague prompt — *"make a UI for a book club"* — produces one arbitrary layout, silently guesses at features you never asked for (polling? a photo gallery?), and anchors you on a flawed start. By the time you've bent it to the features you *do* want, it looks clunky and inelegant. Three disciplines remove the trap, and this skill enforces all three:

| Discipline | What it means | What it prevents | |---|---|---| | **Specificity** | Bake the exact features in; nothing extra | Feature creep, arbitrary navigation elements | | **Stylistic intent** | Name the mood — warm coffee-shop palette? paper & typography? clean editorial? | Point-of-view-less, generic layouts | | **Multiplicity** | Ask for *many divergent* options at once | Anchoring on the first guess |

Early is your **only** cheap chance to explore wide. Spend it.

Input

• `.planning/APP.md` — features, audience, platform. The feature list is exactly what you bake into every variation.
• Optional target screen (arg). If none, prototype the primary screen implied by `<mvp-features>`.
• **If `APP.md` is missing, that's fine** — elicit the essentials first via `AskUserQuestion` (this is the novice front door): the one screen, its 3–5 must-have features, the mood, and 0–2 reference apps. You do not need to know how to write the "good prompt" — the skill assembles it from your answers.

The method — go wide → remix → make lived-in → tune

Stage 1 — Go wide (divergent variations)

1. **Assemble the brief** (via `AskUserQuestion` if it isn't already pinned down in `APP.md`): the screen, the 3–5 must-have features (baked in — *this* is what stops feature creep), the mood cue, reference apps. 2. **Generate 6–10 genuinely divergent variations** of that ONE screen. Divergence is measured by *organizing metaphor*, not paint: vary tab vs. grid→detail vs. single-scroll vs. dashboard/standings, the navigation shape, typography (New York / serif vs. SF), density, and color/mood. Two variations that differ only in tint = one wasted slot. 3. **Each variation gets its own `#Preview` with a descriptive, memorable name** — `"Cozy"`, `"Editorial"`, `"Club Hub"`, `"Blueprint Atelier"`. The name is the handle you'll use when you remix. Put each in its own file (or a clearly separated struct) so the named previews render side by side in Xcode's canvas.

   #Preview("Cozy") { CozyHomeView(club: .sample) }
   #Preview("Club Hub") { ClubHubHomeView(club: .sample) }

4. **Only the requested features appear.** If the app needs no polling or gallery, no variation invents one. 5. **It compiles.** `xcodebuild build` (or the canvas) — you're carrying this forward, not screenshotting a dead mock.

Present the named set; the user flips between them and reacts. **Expect duds** ("…well, it was worth a shot") — range is the goal, not a batting average.

Stage 2 — Remix + make it lived-in

1. **Remix.** The user names what they liked *by preview name and element* — "the standings board from *Club Hub* + the current-book cover from *Cozy*." Generate new **hybrid** variations from only those elements, each its own new named preview. Go wide → remix → repeat until one direction feels right. 2. **Lived-in content.** Empty scaffolding lies about how a screen feels. Generate **reusable sample models in their own file** (delegate to `generators/preview-data-generator`) so you can edit them, and make the content *plausible for the audience* — a book club's discussions are about books, not lorem ipsum. Plausible also means **messy, not idealized**: prototype with real data ranges, because the layout that flatters a hilly San Francisco route must also survive a pancake-flat New York one (WWDC23). Ideal placeholders hide exactly the cases that break a design. 3. **Edge-case previews.** Think the states through yourself; don't let the agent silently pick the happy path. Cover at minimum:

• **Empty / blank-slate** — no meeting scheduled yet, zero items. Is there a call-to-action and an account/management entry, or does it just look broken?
• **Unbounded growth** — many members, long message threads, dozens of past items, long titles. Truncate, or an expand control? (The leaderboard that pushes the discussion off-screen is the classic bug.)
• **Long input** — does text truncate with `.help()`/detail access, or wrap to multiple lines?

Delegate the state-matrix generation to the `swiftui-builder` agent (it emits a `#Preview` per state); **you** decide which states matter.

Stage 3 — Tune key moments (a tuning panel)

Signature interactions — a cover-to-detail transition, a staggered list entrance — are where an app reads as considere