/design-ios

name: design-ios
description: "Use when designing an iOS or macOS screen or flow — deliverable is a device/window-framed HTML mockup and handoff spec, never SwiftUI code."
when-to-use: "Designing an iOS or macOS screen or flow — the deliverable is a device/window-framed HTML mockup and a handoff spec for swift-expert or an Apple-platform developer to implement, not working SwiftUI."
keywords: ios, macos, hig, dynamic-type, liquid-glass, swiftui, handoff, mockup, desktop-tinting
priority: critical
related: design-method, design-system, design-review

<objective> Produces iOS and macOS mockups and developer handoff specs: mapping design tokens to the Dynamic Type scale (iOS) or macOS's fixed text-size variants, semantic colors, device/window viewports, Liquid Glass materials, and macOS-specific conventions (system window chrome, desktop tinting, pointer states).

The deliverable is a device-framed (iOS) or window-framed (macOS) HTML mockup at exact viewport dimensions plus a SwiftUI-ready handoff spec (named tokens, text styles, semantic colors, sizing, states, spacing). This skill never writes SwiftUI code — implementation is left to `swift-expert` or an Apple-platform developer. </objective>

Design iOS/macOS — Mockup and Handoff, Not Code

When

After `design-system` tokens exist. This skill never writes SwiftUI — it produces a static HTML mockup at exact device/window dimensions plus a spec that `swift-expert` or an Apple-platform developer implements.

Input

• `design-system.md` — OKLCH palette, typography direction, motion personality.
• The screen/flow to mock up and the target platform: iPhone / iPad (iOS) or a resizable

window (macOS).

Steps — iOS

1. **Map tokens to iOS roles.** Typography → Dynamic Type text styles, anchored at Body 17pt down to Caption 2 11pt (never fixed point sizes) — see `references/dynamic-type.md`. Colors → semantic color roles (never raw RGB/hex) — see `references/semantic-colors.md`. 2. **Pick the device viewport(s)** from `references/viewports.md` — mock up in exact points at the chosen scale factor. 3. **Build the HTML mockup**: a device-frame `<div>` at the exact viewport dimensions, `viewport-fit=cover` meta tag, `env(safe-area-inset-*)` for notch/Dynamic Island/home indicator spacing. See `references/mockup.md`. 4. **Apply Liquid Glass where it fits** — a floating layer of controls *above* regular content, not a content background. Two variants: **regular** (content-aware, the default for controls) and **clear** (more transparent — dim the content beneath it ~35% when clear sits over light content, so controls stay legible). Plus control morphing, concentricity between nested shapes, layered icon treatment. Source: developer.apple.com/design/human-interface-guidelines/materials (Liquid Glass, iOS 26). See `references/liquid-glass.md` — do not invent numeric corner-radius values; none are published. 5. **Verify touch targets and contrast**: 44×44pt minimum touch target (see `references/touch-targets.md`); **4.5:1 minimum contrast in Dark Mode** for body text (WCAG AA, HIG-endorsed) — check both light and dark against `references/semantic-colors.md` roles, not a single-mode check. 6. **Sidebar navigation ≤ 2 levels deep.** If the flow needs a 3rd level, restructure (tabs, push navigation, or a secondary sidebar) rather than nesting a 3rd disclosure tier — deeper sidebars are a documented HIG anti-pattern for iPadOS/macOS sidebars. Source: developer.apple.com/design/human-interface-guidelines/layout. 7. **Write the handoff spec** per `references/handoff-swiftui.md`: named tokens only (never raw values), Dynamic Type text styles (never fixed sizes), semantic colors, explicit sizing behavior (fixed/hug/fill) per element, all interaction states (disabled/pressed/focused), spacing in pt.

Steps — macOS

1. **Map tokens to macOS text sizes.** macOS uses its own fixed scale, distinct from iOS Dynamic Type — confirmed anchors: **Large Title 26pt** down to **body ~13pt**, floor **Caption 2 ~10pt**. Source: developer.apple.com/design/human-interface-guidelines/typography. **Gap — do not invent**: the full intermediate scale (Title 1–3, Headline, Subhead, Footnote point values) is not confirmed in this pass; reconfirm on the HIG typography page or Xcode's SF font catalog before using an intermediate size verbatim. 2. **No Dynamic Type on macOS** — the platform ships fixed size *variants per context* (e.g. control sizes: regular/small/mini) instead of a user-adjustable type scale. Pick the variant that matches the control's context, don't apply an iOS Dynamic Type style. 3. **Never draw a custom window chrome.** Title bar, traffic lights, toolbar, and sidebar are system-drawn; the mockup should frame content inside a standard macOS window shape, not invent custom chrome. Source: developer.apple.com/design/human-interface-guidelines/windows. 4. **Desktop tinting**: background materials pick up a subtle tint from the desktop picture/wallpaper behind the window — reflect this as a soft, low-opacity tint layer in the mockup, not a flat opaque background. Source: developer.apple.com/design/human-interface-guidelines/materials. 5. **Pointer feedback, not touch feedback**: hover, highlight, and lift states on interactive elements (buttons, list rows) — macOS is pointer-driven, so every hoverable control needs a hover state in the mockup and handoff spec, unlike iOS/iPadOS touch-only flows. Source: developer.apple.com/design/human-interface-guidelines/pointing-devices. 6. **Window sizing is a mockup convenience, not a spec.** Unlike iOS device viewports, macOS windows are user-resizable — pick a reasonable default canvas (e.g. common productivity-app widths) for the mockup, but do not present it as an official fixed dimension; state that explicitly in the handoff spec. 7. **Write the handoff spec** per `references/handoff-swift