ios-design

Apple SwiftUI iOS Design Best Practices A builder's guide for implementing Apple-quality iOS interfaces in SwiftUI, grounded in two foundational design texts: Ken Kocienda — Creative Selection (empathy for the user, craft in coding, taste in choosing the best solution, demo culture of iterative refinement) John Edson — Design Like Apple (systems thinking, the product is the marketing, design out loud, design with conviction) Contains 62 rules across 8 principle-based categories. Each rule identifies a specific anti-pattern, grounds the fix in a named principle, and provides the correct iOS 26 / Swift 6.2 SwiftUI implementation. Scope & Relationship to Sibling Skills This skill is the building and implementation guide — it teaches how to construct new SwiftUI interfaces from scratch using Apple-quality patterns. When loaded alongside ios-ui-refactor (reviewing/refactoring existing UI), this skill covers the greenfield implementation that ios-ui-refactor later audits. Use this skill for building new screens; use the sibling for evaluating and improving existing ones. Clinic Architecture Contract (iOS 26 / Swift 6.2) All guidance in this skill assumes the clinic modular MVVM-C architecture: Feature modules import Domain + DesignSystem only (never Data , never sibling features) App target is the convergence point and owns DependencyContainer , concrete coordinators, and Route Shell wiring Domain stays pure Swift and defines models plus repository, *Coordinating , ErrorRouting , and AppError contracts Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes ViewModels call repository protocols directly (no default use-case/interactor layer) When to Apply Reference these guidelines when: Building new SwiftUI views and screens from scratch Choosing between semantic colors, system typography, and spacing grids (Edson's Systems Thinking) Managing state with @State, @Binding, @Observable, @Environment (Kocienda's Craft) Selecting the right component: List vs LazyVStack, Sheet vs FullScreenCover (Kocienda's Taste) Composing views with @ViewBuilder, custom modifiers, and value types (Kocienda's Creative Selection) Implementing navigation with NavigationStack, TabView, sheets (Edson's Conversation) Laying out content with stacks, grids, frames, and adaptive layouts (Edson's Design Out Loud) Ensuring VoiceOver, touch targets, Dark Mode, and reduce motion support (Kocienda's Empathy) Adding transitions, loading states, and animation polish (Edson's Product Is the Marketing) Rule Categories by Priority Priority Category Principle Impact Prefix Rules 1 Empathy in Every Pixel Kocienda "Empathy" · Edson "Design Is About People" CRITICAL empathy- 8 2 The Visual System Edson "Systems Thinking" · Kocienda "Convergence" CRITICAL system- 8 3 Craft: State as Foundation Kocienda "Craft" CRITICAL craft- 7 4 Creative Composition Kocienda "Creative Selection" HIGH compose- 6 5 Taste: The Right Choice Kocienda "Taste" · Edson "Design with Conviction" HIGH taste- 8 6 Navigation as Conversation Edson "Design Is a Conversation" · Kocienda "The Demo" HIGH converse- 9 7 Design Out Loud: Layout Edson "Design Out Loud" · Kocienda "Intersection" HIGH layout- 8 8 The Product Speaks Edson "Product Is the Marketing" · Kocienda "Demo Culture" MEDIUM product- 8 Quick Reference 1. Empathy in Every Pixel (CRITICAL) Kocienda: "Empathy — trying to see the world from other people's perspectives." Edson: design begins with the person holding the device. empathy-semantic-colors - Use semantic colors, never hard-coded values empathy-dark-mode - Support Dark Mode from day one empathy-foreground-style - Use foregroundStyle over foregroundColor empathy-safe-areas - Always respect safe areas for content empathy-voiceover-labels - Add VoiceOver labels to every interactive element empathy-touch-targets - Ensure 44x44 point minimum touch targets empathy-reduce-motion - Always provide reduce motion fallback empathy-readable-width - Constrain text to readable width on iPad 2. The Visual System (CRITICAL) Edson: "Zoom out to see relationships between objects." Kocienda: convergence — many decisions narrowing toward one coherent whole. system-typography - Use system typography styles, never fixed sizes system-visual-hierarchy - Establish clear visual hierarchy through size, weight, and color system-spacing-grid - Use a 4pt base unit for all spacing system-material-backgrounds - Use material backgrounds for depth and layering system-sf-symbols - Use SF Symbols for consistent iconography system-gradients - Apply gradients for visual depth, not decoration system-standard-margins - Use system standard margins consistently system-stack-config - Configure stack alignment and spacing explicitly 3. Craft: State as Foundation (CRITICAL) Kocienda: "Craft — applying skill to achieve a high-quality result." craft-state-local - Use @State for view-local value types craft-state-binding - Use @Binding for child view mutations craft-state-environment - Use @Environment for shared app-wide data craft-state-observable - Use @Observable for model classes craft-avoid-body-state - Never create state inside the view body craft-minimize-scope - Minimize state scope to reduce re-renders craft-state-bindable - Use @Bindable for @Observable bindings 4. Creative Composition (HIGH) Kocienda: "Creative selection — great software is built through composition and recombination." compose-body-some-view - Return some View from body, never concrete types compose-custom-properties - Use properties to make views configurable compose-modifier-order - Apply view modifiers in the correct order compose-viewbuilder - Use @ViewBuilder for flexible slot-based composition compose-prefer-value-types - Prefer value types for view data compose-prefer-composition - Prefer composition over inheritance for view reuse 5. Taste: The Right Choice (HIGH) Kocienda: "Taste — refined judgment, the ability to choose the one right solution." Edson: commit to one approach and perfect it. taste-list-vs-lazyvstack - Choose List for system features, LazyVStack for custom layouts taste-sheet-vs-fullscreen - Choose sheet for tasks, fullScreenCover for immersion taste-picker - Choose the right picker style for the data type taste-grid-vs-lazygrid - Choose Grid for aligned data, LazyVGrid for scrollable collections taste-button - Use button styles that match the action's importance taste-textfield - Configure text input with the right keyboard and content type taste-alerts - Use alerts only for critical, blocking information taste-action-sheets - Use confirmation dialogs for contextual multi-choice actions 6. Navigation as Conversation (HIGH) Edson: "Design is a conversation between the product and the person." Kocienda: demos as conversations about whether the interface speaks clearly. converse-navigationstack - Use NavigationStack for programmatic, type-safe navigation converse-tabview - Organize app sections with TabView for parallel navigation converse-sheet-item - Use item binding for data-driven sheet presentation converse-dismiss - Use environment dismiss for modal closure converse-toolbar - Place toolbar items in the correct semantic positions converse-tab-bar - Use tab bar for top-level section navigation converse-nav-bar - Configure navigation bar to communicate context converse-hierarchy - Design clear navigation hierarchy before writing code converse-search - Integrate search with the searchable modifier 7. Design Out Loud: Layout (HIGH) Edson: "Design Out Loud — prototype relentlessly until layout feels inevitable." Kocienda: the intersection of technology and liberal arts. layout-stacks - Use stacks instead of manual positioning layout-spacer - Use Spacer for flexible space distribution layout-frame-sizing - Use frame() for explicit size constraints layout-zstack - Use ZStack for purposeful layered composition layout-grid - Use Grid for aligned non-scrolling tabular content layout-lazy-grids - Use LazyVGrid for scrollable multi-column layouts layout-adaptive - Use adaptive layouts for different size classes layout-scroll-indicators - Show scroll indicators for long scrollable content 8. The Product Speaks (MEDIUM) Edson: "The product itself is the marketing." Kocienda: every animation and loading state built to survive Steve Jobs' scrutiny. product-transitions - Use semantic transitions for appearing views product-loading-states - Show honest loading states, not indefinite spinners product-with-animation - Use withAnimation for explicit state-driven animation product-matched-geometry - Use matchedGeometryEffect for contextual origin transitions product-list-cells - Design list cells with standard layouts product-content-unavailable - Use ContentUnavailableView for empty and error states product-segmented - Use segmented controls for visible, mutually exclusive options product-menus - Use menus for secondary actions without cluttering the interface How to Use Read individual reference files for detailed explanations and code examples: Section definitions - Category structure, principle sources, and impact levels Rule template - Template for adding new rules Reference Files File Description references/_sections.md Category definitions and principle grounding assets/templates/_template.md Template for new rules metadata.json Version and reference information