Ios Design

ios-design — SwiftUI mockups, Claude-Design style

Claude Design produces a design system as browsable cards: a foundations page (POV statement, named swatches, type scale) plus per-component pages showing hierarchy / sizes / states with design-rule captions, all light+dark. This skill produces the same deliverable in real SwiftUI, so the mockup language IS the implementation language — no HTML-to-SwiftUI translation loss (the /design-fidelity-loop "same-language" rule). Mockups render headlessly to PNG in seconds via ImageRenderer on macOS; no simulator, no Xcode project.

Phase map

| Phase | Deliverable | Reference | |---|---|---| | 0 Read first | inventory of existing design assets | below | | 1 Direction | 3 rendered direction anchors → user picks 1 | DIRECTION.md | | 2 Foundations | Theme.swift + foundations card render | below | | 3 Components | kit + one card render per component | below | | 4 Screens | full-screen mockups, light+dark | below | | 5 Iterate | versioned re-renders until user approves | below | | 6 Persist | docs/design// + optional Claude Design publish | RENDERER.md §Publish |

Read RENDERER.md before the first render (build commands + gotchas). Read DIRECTION.md and TASTE.md at the start of Phase 1 — TASTE.md is the council-distilled beauty canon (reference apps, 15 checkable laws, anti-patterns); direction proposals name their canon lens, and foundations lock only after a pass against its laws. Read VERIFY.md before showing the user any render — every shown set goes through its loop: mechanical gate → fresh-eyes subagent verdict → act, with the 3-strikes convergence rule. Fresh-eyes briefs include TASTE.md's density/motion/drama laws.

Content rules (hold in every phase)

• No filler. Never pad a mockup with placeholder sections, dummy stats,

or "data slop" — numbers, icons, or copy that are not useful. An empty-feeling screen is a layout problem, not a content gap. One thousand no's for every yes; bias to minimalism.

• Ask before adding material. New sections, screens, or copy you think

would help → ask first; the user knows their audience.

• Vocalize the system up front. After Phase 0/1, state the system you

will use (layout per screen kind, 1–2 background colors, type pairing) before building screens.

• Scales. Tap targets never under 44×44pt in any mockup.
• Assets. Clean labeled placeholders over invented artwork; never

AI-drawn vector clipart or emoji-as-icons. Ask for real materials.

Phase 0 — Read first

1. Resolve the target repo (~/.claude/repo-map.md if referenced by name).
2. Inventory existing design assets before generating anything:

docs/design/, *Theme*.swift, *Tokens*.swift, *DesignKit*, a project design skill (e.g. example-app-glass-design), brand assets, app icon — AND experience artifacts: docs/design/*/EXPERIENCE.md + journeys.yaml (authored by /ux-design). If they exist, screens come FROM flows: every Phase 4 mockup names its flow node, and the screen set covers the HERO + DAILY journeys — no orphan screens. If the user wants flows designed first, route to /ux-design before Phase 1.

1. If a design system already exists: EXTEND it — load its tokens into

Theme.swift verbatim and skip Phase 1 unless the user asked for new directions. Never invent a second design vocabulary for an app that has one.

1. Confirm toolchain: swiftc present. If not, stop and say so.

Phase 1 — Direction (read DIRECTION.md now)

1. Interview the user (max ~5 questions): purpose, audience, tone words,

references they love, constraints (existing brand, iOS version floor).

1. Propose 3 named directions from distinct schools (DIRECTION.md table) —

each with a POV sentence and its signature detail.

1. Render the anchors. Copy assets/mockups-template/ into

docs/design//mockups/, then build one hero screen per direction with its own candidate Theme values, render light+dark, and show the user real PNGs — never ask them to imagine a direction from prose.

1. User picks a direction (or a blend). Record the decision and the POV

statement in DESIGN.md. This is a gate: do not proceed on your own pick.

Phase 2 — Foundations

1. Lock Theme.swift: every color token carries explicit light AND dark

values; type scale ≤ 6 named roles; spacing/radius constants; a data/numeral treatment if the product shows numbers (times, prices, metrics). Spacing is a named scale in Theme (e.g. inset/gapItem/gapSection/rowHeight) — components consume the scale, never ad-hoc paddings. Density is a direction decision: calm/refined/luxury directions default to the GENEROUS end (the calm lives in the gaps); dense-instrument directions choose density deliberately. If a rendered screen feels squeezed, fix the scale, not the screen.

1. Render the foundations card (POV statement, named swatches, type

specimens — see template FoundationsCard). Contrast-check ink-on-surface and onAccent-on-accent pairs (≥ 4.5:1 body, ≥ 3:1 large) in BOTH schemes before showing the user.

Phase 3 — Component cards

1. Author the kit: 6–12 components the screens will need (buttons, card,

list row, chip/badge, field, empty state, sheet header…). Variant axes come from anticipated call sites, bounded (e.g. 3 kinds × 3 sizes). Components take t: Theme — a hardcoded color in a component is a defect.

1. One card per component, Claude-Design style: sections for hierarchy,

sizes, states, each with a one-line design-rule caption stating the law ("one primary per view"). Render all cards light+dark. Contrast checks cover STATE variants too — a disabled or secondary state that fails 3:1 on its own card fails the gate, not just the base pair.

Phase 4 — Screen mockups

1. Build 3–6 full screens covering the core journey. Screens COMPOSE kit

components and tokens; they never define new styles inline — if a screen needs a new style, it goes into the kit first.

1. Use custom-drawn chrome (header, tab bar) — never SwiftUI NavigationStack

or TabView in mockups; their chrome renders macOS-styled headlessly (RENDERER.md §Fidelity). Glass/material-heavy directions need the simulator lane (RENDERER.md §Simulator).

1. Run the VERIFY.md loop on the full set: gate (build, fake-dark,

contrast), fresh-eyes subagent verdict against the user's asks verbatim, act on needs_work. Only a VERDICT: done set reaches the user.

Phase 5 — Iterate

1. Show the contact sheet / PNGs. Collect reactions per screen.
2. Apply feedback at the right altitude: color/spacing/type feedback lands in

Theme.swift, component feedback in Components.swift — so one change propagates everywhere. Screen-local fixes are the rare case.

1. Re-render with a bumped ITER (r2, r3…). Never overwrite a previous

iteration — the numbered history is the design conversation.

1. Repeat until the user approves. User approval is the only exit; a mockup

set you like is not "done".

Phase 6 — Persist + hand off

1. Final render at SCALE=3. Commit the system (ask before committing if

repo conventions unclear):

docs/design//
  DESIGN.md            direction, POV, chosen tokens, component laws, decision log
  mockups/             Theme.swift Components.swift Screens.swift Render.swift
  renders/             rN--{light,dark}.png + index.html contact sheet

1. DESIGN.md opens with: POV statement, the one signature detail, the

3 laws a reviewer can check at a glance, and a REQUIRED motion spec — spring parameters, transition style, and the drama budget: the ONE orchestrated signature moment (name the 3-second interaction), with every other animation ≤0.35s sharing at most two curves and bound to a state change (TASTE.md laws 12–13) — mockups are static, so implementation inherits motion from this spec or not at all. Any deliberate break of a TASTE.md law is recorded here with a reason. A fresh session must be able to continue the system from this directory alone.

1. Offer (do not auto-run): publish renders to a Claude Design project via

DesignSync so the system is browsable at claude.ai/design (RENDERER.md §Publish), and/or proceed to implementation with /design-fidelity (mockups → production predicates) or /design-fidelity-loop (full program). For theme A/B on the finished kit, use /skin-gallery.

Output format

• Every render is r--.png in renders/; index.html

is the contact sheet. Renders come in light+dark pairs, always.

• The runner exits non-zero on a byte-identical light/dark pair ("fake dark

mode") — never show the user renders from a failing run.

• Progress messages to the user show PNGs, not Swift code.

Verify before claiming done

• The template must compile and run (swiftc … && ./render) — a mockup set

that doesn't build is not a deliverable.

• Fake-dark self-check green; contrast pairs pass in both schemes.
• You have looked at every final PNG with your own eyes (Read tool), AND the

final set carries a fresh-eyes VERDICT: done (VERIFY.md §3) — the author grading their own work alone does not count.

Does not do

• Production implementation — /design-fidelity (validation pipeline),

/design-fidelity-loop (program), /component-kit-consolidation (brownfield DRY).

• Journeys, flows, navigation architecture, habit loops — /ux-design

(this skill renders what it decides; EXPERIENCE.md is upstream of screens).

• Craft review / polishing existing SwiftUI — /swiftui-craft (spacing,

type, colors, widgets, review checklist); it is this skill's implementation-time counterpart.

• HIG audit / native-idiom review — /swiftui-craft (owns HIG references).
• Liquid Glass API work — /liquid-glass; glass renders need the

simulator lane anyway (RENDERER.md).

• Theme A/B on an existing kit — /skin-gallery.
• HTML mockups — that is Claude Design itself (via DesignSync); this skill

exists precisely to skip the HTML intermediary.

Concurrency

Mockups live under docs/design// in the target repo. Before overwriting a system another session may own, claim it: /claim R-design-. New-system authoring in a fresh directory needs no claim.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.