ios-design-stack

name	ios-design-stack
description	Invocable iOS design pipeline. When called with a design prompt, runs an autonomous loop: designs iOS screens in Pencil MCP following Apple HIG, reviews for taste using Design Philosophy, validates with XcodeBuildMCP, and iterates until done. Use as: /ios-design-stack "Design a [screen] for [app] with [requirements]"
user-invocable	true
argument-hint	Design a [screen] for [app]

/ios-design-stack

Autonomous iOS design pipeline. Give it a prompt, it designs, reviews, builds, and iterates until the result passes both taste and build checks.

When Invoked

Parse the user's prompt as the design brief. Then run this pipeline as a loop until the design passes all checks.

Pipeline

┌─────────────────────────────────────────────────┐
│  1. SETUP     Load tokens + guidelines          │
│  2. DESIGN    Create screen in Pencil MCP       │
│  3. REVIEW    Taste-check with Design Philosophy│
│  4. BUILD     Export SwiftUI, build, screenshot  │
│  5. VERIFY    Compare screenshot to design       │
│  6. ITERATE   Fix issues, loop to step 2         │
│  7. DONE      All checks pass                    │
└─────────────────────────────────────────────────┘

Step 1: Setup

Load the iOS design skills in this repo:

Read: skills/ios-design-tokens/SKILL.md     ← iOS HIG tokens (colors, type, spacing)
Read: skills/pencil-ios-design/SKILL.md     ← Pencil MCP iOS workflow
Read: skills/design-philosophy/SKILL.md     ← taste principles

Then initialize:

1. Call get_editor_state to check Pencil MCP is available
2. Call open_document("new") or open existing .pen file
3. Call set_variables with iOS design tokens from ios-design-tokens skill
4. Call get_guidelines(topic="mobile-app") for Apple HIG rules

If the user specified an aesthetic (e.g., "dark, minimal, premium"): 5. Call get_style_guide_tags then get_style_guide(tags=[...]) to get style direction

Step 2: Design

Using the pencil-ios-design skill as your guide:

1. Call find_empty_space_on_canvas(width=393, height=852) for iPhone 15 Pro frame size
2. Call batch_design to create the screen layout. Max 25 operations per call.

Mandatory iOS rules:

• 59pt top safe area (Dynamic Island)
• 34pt bottom safe area (home indicator)
• 16-20pt horizontal margins
• All touch targets ≥ 44x44pt
• 8pt spacing grid
• SF Pro typography only, using iOS type scale
• iOS semantic colors only (not hardcoded hex)
• Continuous corners (squircle)

Refer to the common screen patterns in pencil-ios-design for Login, Settings, Detail, and other standard layouts.

Step 3: Review (Design Philosophy)

Before building, taste-check the design. Ask these questions:

1. What's the one feeling this creates? Write it in one word.
2. What would you remove? Cut at least one element.
3. Does every element earn its place? If removing it changes nothing, remove it.
4. Would Apple ship this? Be honest.

From the Design Philosophy skill:

• Typography creates hierarchy, not color or weight
• Whitespace = premium. Cramped = cheap.
• One focal point per screen
• One accent color maximum
• Less, but better. (Dieter Rams #10)

If the design fails taste review, go back to Step 2 and simplify. Do NOT proceed to build until taste passes.

Step 4: Build

Export the design and validate it compiles:

1. Export the Pencil design nodes to SwiftUI code
2. Create/update the Swift file in the project
3. Build with XcodeBuildMCP: xcodebuild build
4. Run in simulator: xcrun simctl boot + install + launch
5. Capture screenshot: xcodebuildmcp screenshot

If XcodeBuildMCP is not available, skip to Step 5 with the Pencil screenshot only.

Step 5: Verify

Compare the build screenshot (or Pencil screenshot) against the design:

Call: get_screenshot(nodeId="frame-id")
Call: snapshot_layout(nodeId="frame-id", problemsOnly=true)
Call: search_all_unique_properties(nodeId="frame-id", properties=["fillColor", "fontFamily", "fontSize"])

Verification checklist:

• Spacing follows 8pt grid
• All touch targets ≥ 44pt
• Typography hierarchy is clear (squint test passes)
• One focal point dominates the screen
• Only SF Pro font family used
• Only iOS type scale sizes (11, 12, 13, 15, 16, 17, 20, 22, 28, 34)
• Only semantic colors (no random hex)
• Continuous corners, not circular
• Safe areas respected (top 59pt, bottom 34pt)
• No layout issues (snapshot_layout reports clean)
• Code compiles without warnings (if built)
• Screenshot matches design intent

Step 6: Iterate

If any checks fail:

1. Identify the specific issue
2. Fix it in the Pencil design (batch_design update operations)
3. Re-verify (back to Step 5)
4. If it's a taste issue, revisit Step 3
5. If it's a build issue, revisit Step 4

Continue iterating until ALL checks pass.

Step 7: Done

When all checks pass, report:

DESIGN COMPLETE

Screen: [name]
Feeling: [one word]
Checks passed:
  ✓ Typography: SF Pro, iOS type scale
  ✓ Spacing: 8pt grid
  ✓ Colors: iOS semantic tokens
  ✓ Touch targets: ≥ 44pt
  ✓ Safe areas: respected
  ✓ Taste: [one sentence on why it passes]
  ✓ Build: compiles, zero warnings
  ✓ Screenshot: matches design intent

Files:
  - [.pen file path]
  - [.swift file path]

Using with Ralph Loop

For fully autonomous iteration, wrap this skill in a Ralph Loop:

/ralph-loop "Run /ios-design-stack with this brief:

[USER'S DESIGN BRIEF HERE]

Success criteria:
- Design passes all verification checks
- Code compiles without warnings
- Screenshot matches design intent
- Taste check passes (would Apple ship this?)

Output <promise>DESIGN_COMPLETE</promise> when all checks pass." --max-iterations 15

The Ralph Loop will keep re-running the pipeline until it converges on a design that passes every check. Typical: 3-5 iterations for a simple screen.

External Dependencies

Tool	Source	Required?
Pencil MCP	pencil.dev	Yes — the design canvas
XcodeBuildMCP	getsentry/XcodeBuildMCP	Optional — for build validation
Ralph Loop	anthropics/claude-code	Optional — for autonomous iteration

Skills in This Repo

Skill	What it does
skills/design-philosophy/	Taste principles — Dieter Rams, "less but better"
skills/ios-design-tokens/	iOS HIG tokens — typography, colors, spacing, radii
skills/pencil-ios-design/	iOS Pencil MCP workflow — how to design iOS screens