rshankras/ui-prototyping

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 considered or cheap. Don't hand-edit constants scattered across files; have the agent build a tuning panel.

1. Be specific about what you're tuning. Ease (duration) vs. spring (stiffness / damping / mass)? A single element, or a transition where views enter and leave the hierarchy?
2. Break the animation into named phases — "Phase 1: cover transitions to detail. Phase 2: rows stagger in." Phases give you and the agent a shared vocabulary; ask for controls per phase so you can inspect and retune one in isolation.
3. Lay the panel out side-by-side on a wide window, not a modal that obstructs the content — toggle a parameter and see the effect without context-switching. Ask for a resize control that moves the panel beside the UI on a larger canvas.
4. Tuning panels generalize beyond animation: swap app states, colors, fonts, visual offsets. Use design/animation-patterns for the curve knowledge; the panel is its runnable counterpart.
5. Prototype beyond static layout. Friction, inertia, device-motion effects (gyroscope parallax), and haptics are all promptable and panel-tunable the same way — and they're feel, only judgeable running on a device, not in a screenshot (WWDC26).
6. Guard it behind DEBUG / a launch arg so it never ships — same discipline as walkthrough's -uiTestSeed.
7. On device early; review as a demo app. Don't wait for "done" to leave the canvas — feel parameters (Digital Crown sensitivity, spring values) only tune while running live, so the earlier a prototype is on hardware the cheaper every iteration. And when it's time for a design review, bundle the competing prototypes into one on-device demo app rather than exporting stills: "no slide deck in the world can compare with one spectacular demo" (WWDC23).

Output: .planning/PROTOTYPE.md + real Swift

Record the decisions so the next session — and /apple:plan — inherits them:

# UI Prototype — [Screen], Phase [N]

## Variations explored (Stage 1)
| Preview name | Organizing idea | Verdict |
|--------------|-----------------|---------|
| Cozy | single-scroll, warm serif, current-book hero | ✅ base direction |
| Club Hub | tab bar + standings board | remix: take the standings board |
| Blueprint Atelier | grid → detail | ✗ too cold |

## Chosen direction & remix (Stage 2)
- Base: *Cozy*; grafted the standings board from *Club Hub*.
- Sample data: `PreviewData/BookClubSamples.swift` (editable, reused across previews).
- Edge cases covered: empty (added CTA + account entry), long member list (rank pinned + expand), long titles (truncate).

## Tuned moments (Stage 3)
- Cover→detail: spring(stiffness: …, damping: …); rows stagger 0.04s. Panel: `Debug/TransitionTuner.swift` (DEBUG only).

## Carry-forward
- Winning layout → `/apple:plan` `<flows>` + `<apple-patterns>`; keep the Swift files.

Plus the actual files in the project: the variation views, the sample-data file, and any tuning panel (DEBUG-guarded).

Honest limits

• Agents propose; you decide. Don't delegate "which is best" — that judgment is the design work. A pile of variations with no chosen direction is not a result.
• Divergent ≠ good. Some variations will flop; that's the method working, not failing.
• Nothing beats real users. Lived-in sample content is a head start on the feedback stage, not a substitute for people using your app with their own content.
• The tuning panel is scaffolding — DEBUG-only, guarded, and removed or gated before release.

Cadence & integration

• Run early, once per signature screen — after /apple:new-app, or at the start of a UI-heavy phase, before /apple:plan locks a layout. Exploration is cheapest before the "real" screen exists.
• Feeds forward: the winning variation is real SwiftUI — hand its structure to /apple:plan (<flows> / <apple-patterns>) and /apple:build; don't rebuild it.
• Bookends with flow-walkthrough / /apple:walkthrough: prototype the screen (diverge, choose, tune), then walkthrough the flow (verify transitions and dead-ends) once it's wired up. Explore → build → verify.
• Complements product/ux-spec: ux-spec formalizes one spec; this skill is how you find the one worth formalizing. Feed the winner in, or skip ux-spec for small apps.
• Reuses: generators/preview-data-generator (sample content), the swiftui-builder agent (edge-case #Preview matrix), design/animation-patterns (curve reference).