apple-design

apple-design — pick the track first

Apple platforms have multiple stacks with different visual ceilings and cost. Ask the user which one before any code.

What This Skill Can Do

• Choose the right Apple track: strict SwiftUI, branded SwiftUI, React Native, Flutter Cupertino, or Electron/Tauri for macOS.
• Design iPhone task flows, iPad/macOS productivity surfaces, menu-bar utilities, document apps, settings, inspectors, media apps, and desktop-class workbenches.
• Preserve UX briefs, state coverage, action hierarchy, keyboard flow, Dynamic Type, focus, accessibility, and safe areas.
• Apply HIG, Liquid Glass, SF Symbols, SF typography, NavigationSplitView, DocumentGroup, inspectors, sheets, toolbars, and platform-specific motion.
• Add originality through composition, content, and state treatment without replacing native controls with web-style chrome.

Step 0 (MANDATORY) — Ask the user which track

> Which track for this app?

>

> 1. System-like native (SwiftUI strict + Liquid Glass + HIG) — feels like Settings, Notes, Reminders, Mail. Best for: utilities, productivity. Visual ceiling: medium. Stays App Store-friendly. Examples: Things 3, NetNewsWire, Soulver.

>

> 2. Branded native (SwiftUI + HIG + custom identity) — native chrome (Liquid Glass, SF Symbols, Dynamic Type) but bespoke content surface (custom typography, hero atmospheres, magazine layouts). Best for: consumer/media/creative apps that want fit-in and identity. Visual ceiling: high. Examples: Ivory, Reeder, Mela, Craft, CARROT Weather.

>

> 3. React Native (New Architecture + Fabric + Hermes) — real UIKit views, decent native feel, JavaScript codebase, cross-platform with Android. Liquid Glass partial via expo-glass-effect. Best for: cross-platform apps with web-team velocity. Examples: Discord mobile, Coinbase, Microsoft Office mobile.

>

> 4. Flutter Cupertino — Skia-painted UIKit-look. Always one OS behind, no Liquid Glass. Cross-platform. Best for: utility apps where pixel control beats native feel. Visual ceiling: high if you bring your own design language; low if you try to mimic iOS.

>

> 5. Electron / Tauri 2 (macOS only — no iOS) — web stack desktop apps. Tauri 2 (~5MB, WKWebView) or Electron (~150MB, bundled Chromium). Same React/Tailwind/Motion code as web. Best for: cross-platform desktop with brand-first identity. Examples: Spotify, Discord, VSCode, Slack, Figma desktop, Linear.

>

> Which? Or describe priorities (App Store, brand vs HIG fit, cross-platform reach) and I'll pick.

If brief gives a strong signal (e.g. "iOS App Store launch" → 1 or 2; "cross-platform with our existing React team" → 3 or 5; "web team building desktop-only" → 5), state your pick + reasoning in one sentence. If ambiguous, ask.

Step 0b — Once picked, route

| Track | Reference docs | Default stack |

|---|---|---|

| 1. System-like SwiftUI | ../../references/apple-hig.md + ../../references/liquid-glass.md | SwiftUI 7 + Xcode 26 + iOS 26 SDK strict |

| 2. Branded SwiftUI | Same as 1 | Same as 1 + custom display font + hero atmospheres + bespoke surfaces |

| 3. React Native | ../../references/web-fonts.md + cross-platform docs | RN 0.78+ New Arch + Expo Router + react-native-screens |

| 4. Flutter Cupertino | None for native fidelity (will feel imported) | Flutter 3+ stable |

| 5. Tauri 2 / Electron (macOS) | ../../references/web-fonts.md + ../../references/web-motion.md + ../../references/web-bans.md + ../../references/awwwards-ceiling.md | React 19 + Tailwind v4 + Motion |

For tracks 3, 4, 5: web/cross-platform anti-slop rules apply. Read the web design references.

State the chosen aesthetic direction and track in one sentence at top of response, then proceed.

Step 0c — UI decision brief

Before code, read:

• ../../references/ui-patterns/surface-taxonomy.md
• ../../references/ui-patterns/ui-decision-brief.md
• ../../references/ui-patterns/desktop-app-archetypes.md
• ../../references/ui-patterns/native-desktop-app-quality-contract.md
• ../../references/ui-patterns/originality-engine.md
• ../../references/ui-patterns/design-recipes.md
• ../../references/ui-patterns/anti-default-contrasts.md
• ../../references/ui-patterns/visual-hierarchy.md
• ../../references/ui-patterns/motion-budget.md

Write the UI decision brief and, for macOS/iPad desktop-class work, the desktop archetype brief, native desktop quality brief, and compact layout sketch. For original/non-generic Apple work, also write the originality brief: subject, product world, main object, composition archetype, repeated motif, one weird move, and restraints. Pick the app shape before picking controls: command center, library/collection, workbench, monitoring cockpit, menu-bar utility, media/consumer, document/knowledge, or setup/preferences. Define window model, command model, resize behavior, native controls, keyboard/focus paths, state coverage, and platform evidence. If the sketch becomes generic sidebar + detail, use anti-default contrasts and rewrite it around the main object. iPhone task flows need thumb reach and progressive disclosure; iPad/Mac productivity surfaces need NavigationSplitView, inspector, keyboard flow, command surfaces, and stable density; media/consumer apps may use branded content surfaces while preserving HIG controls, SF typography, SF Symbols, Dynamic Type, and safe areas. Do not make every Mac app a generic sidebar plus detail view unless the archetype truly calls for it.

Step 1 — Liquid Glass first (only if track 1 or 2)

Apple's unified design language across iOS 26, iPadOS 26, macOS 26 Tahoe, watchOS 26, tvOS 26, visionOS 26. Treat as default.

Apply via:

• .glassEffect() modifier on surfaces that should refract underlying content
• GlassEffectContainer { ... } to coordinate multiple glass surfaces (avoids overlapping refraction artifacts)
• .buttonStyle(.glass) for buttons that should adopt Liquid Glass
• .toolbar { ... } automatically lifts to glass on iOS 26+
• .scrollEdgeEffectStyle(.soft) — replaces hard chrome edges with material lensing

Lineage to remember: Aqua → iOS 7 blur → Dynamic Island → visionOS → Liquid Glass. The aesthetic is "digital meta-material" — light bends through it.

Read ../../references/liquid-glass.md for full Liquid Glass adoption checklist.

Step 2 — SwiftUI 7 modern APIs (Swift 6.2 / Xcode 26)

Always prefer:

• @Observable macro on view models — never ObservableObject + @Published
• @Entry for one-line EnvironmentValues / FocusedValues / Transaction keys
• Group(subviews:) and ForEach(subviewsOf:) for custom containers
• MeshGradient(width:height:points:colors:) for distinctive backgrounds — replaces flat gradients
• NavigationSplitView with .inspector { ... } for iPad/Mac three-pane
• TabView with sidebar-adaptable .role
• .searchable (morphs into a glass pill on iOS 26)
• .symbolEffect(.bounce) / .pulse / .variableColor / .replace.byLayer on SF Symbols
• MotionScheme and spring physics — .spring(response:dampingFraction:), never linear/easeIn/easeOut on UI motion

Step 3 — HIG compliance

• Layout grid: 8pt base, 4pt half-step. Never 10/15/20. Use .padding() defaults — they encode the system's grid.
• Safe areas: every screen wraps in safe area handling. .safeAreaInset(edge:) for content bars.
• Dynamic Type: support xSmall → AX5. Use Font.TextStyle (.largeTitle, .title, .headline, .body, .caption). Never hard-coded points.
• SF Symbols 7 is the only icon system. ~6,900 glyphs, 9 weights × 3 scales. Use Image(systemName:).
• Accessibility: .accessibilityLabel/Hint/Value, .accessibilityElement(children:.combine), traits like .isButton, .isHeader. Mandatory.

Read ../../references/apple-hig.md for HIG section deep-dive.

Step 4 — macOS specifics (macOS 26 Tahoe)

• SwiftUI is now first-class for new Mac apps. Drop into AppKit only for: complex NSTextView + custom rich text, Quick Look extensions, custom NSToolbar items, NSOpenPanel extensions.
• Catalyst is deprecated in spirit. Prefer SwiftUI multiplatform target.
• Patterns:
• NavigationSplitView { sidebar } content: { ... } detail: { ... }
• .inspector { ... } for trailing pane (Craft, Notes pattern)
• DocumentGroup for document-based apps where files are the main object
• Table or OutlineGroup for dense libraries, files, logs, and knowledge trees
• Window("Quick Capture", id: ...) for focused utility windows
• MenuBarExtra("Name", systemImage: ...) { ... } for menu-bar apps
• Settings { TabView { ... } } scene for prefs window
• Vibrancy materials: .background(.regularMaterial), .ultraThin/Thin/Regular/Thick/UltraThick
• For sidebar background: .background(NSVisualEffectView { $0.material = .sidebar }) via NSViewRepresentable if needed

Step 5 — Cross-platform fidelity warnings

State the tradeoff if the user asks for non-Swift on Apple:

| Stack | Liquid Glass adoption | Verdict |

|---|---|---|

| SwiftUI / UIKit native | Full automatic | Use this |

| React Native (New Arch + Fabric + Hermes) | Partial via expo-glass-effect / native modules | Decent for utility apps, off in nav transitions/haptics |

| Flutter Cupertino | Pixel-recreates iOS but always one OS behind, no Liquid Glass | Will feel wrong on iOS 26+ |

| .NET MAUI | Looks like Android in costume | Never use on Apple |

If user insists on cross-platform, route to cross-platform-design and warn that any non-SwiftUI path will fail Liquid Glass adoption.

Step 6 — Anti-slop ban list (Apple-specific)

• Inter / Roboto / SF Pro replaced by web fonts — only SF Pro / SF Pro Rounded / SF Mono / New York
• Material Design elevation shadows — use materials (.regularMaterial) and Liquid Glass instead
• Hamburger drawer navigation — use TabView (iOS), NavigationSplitView (iPad/Mac)
• FontAwesome / Material Symbols / Lucide icons — only SF Symbols 7
• Linear/easeIn/easeOut animation curves — only spring physics
• .padding(20) magic numbers — use system spacing or 8/16/24 grid
• Bottom sheets without .presentationDetents([.medium, .large])
• Custom switch / checkbox UI replacing Toggle
• Full-bleed content under nav without .scrollEdgeEffectStyle(.soft)
• Ignoring .safeAreaInset — content collides with home indicator
• Hard-coded points instead of Font.TextStyle (breaks Dynamic Type)
• Custom scroll indicators — use ScrollIndicators(.hidden) only when justified
• Web-style dashboards squeezed into iPhone screens
• Decorative cards where grouped Form, List, inspector, or split view is the platform idiom
• Generic macOS sidebar plus detail view for every app, regardless of the main object
• Custom originality that replaces native controls instead of changing composition, content, and state treatment

Step 7 — Reference apps that nail HIG

• Things 3 — typographic restraint, magic-plus, perfect Dynamic Type
• Reeder Classic / Reeder 5 — NavigationSplitView exemplar on iPad/Mac
• Ivory (Tapbots) — bespoke yet HIG-correct; haptic + .symbolEffect choreography
• Mela — text-first, native share sheets, no chrome
• Craft — multi-pane Mac, inspector pattern, vibrancy
• NetNewsWire — open-source HIG textbook
• Soulver 3 — Mac-native typography + sidebar
• CARROT Weather — system materials + variable color symbols
• Overcast — type hierarchy, Dynamic Type, accessibility
• Fantastical — sidebar + inspector + menu-bar mode

Step 8 — Tokens & assets

• Apple Design Resources Figma kits (iOS 26, macOS 26): https://developer.apple.com/design/resources
• SF Symbols 7 app: https://developer.apple.com/sf-symbols
• HIG: https://developer.apple.com/design/human-interface-guidelines
• Icon Composer (WWDC25 session 361) for Liquid Glass app icons
• System color spec: https://developer.apple.com/design/human-interface-guidelines/color (use .primary, .secondary, .tint, Color(.systemBackground) — never raw hex)

Token JSON: see ../../assets/tokens/apple-system.json