Apple SwiftUI iOS Design Best Practices

Comprehensive guide for building Apple-quality iOS UIs with SwiftUI. Contains 62 rules across 8 categories covering design systems, state management, layout, view composition, navigation, components, accessibility, and animation polish.

When to Apply

Reference these guidelines when:

Building new SwiftUI views and screens
Implementing design systems with semantic colors, typography, and spacing
Managing state with @State, @Binding, @Observable, @Environment
Laying out content with stacks, grids, and adaptive layouts
Composing views with @ViewBuilder and custom modifiers
Implementing navigation with NavigationStack, TabView, sheets
Choosing and configuring SwiftUI components
Ensuring VoiceOver support, touch targets, and reduce motion
Adding semantic transitions and loading state animations

Rule Categories by Priority


design-
state-
layout-
view-
nav-
comp-
access-
anim-

Priority	Category	Impact	Prefix
1	Design System	CRITICAL	`design-`
2	State & Data Flow	CRITICAL	`state-`
3	Layout & Sizing	HIGH	`layout-`
4	View Composition	HIGH	`view-`
5	Navigation	HIGH	`nav-`
6	Components & Controls	HIGH	`comp-`
7	Accessibility	HIGH	`access-`
8	Animation & Polish	MEDIUM	`anim-`

Quick Reference

1. Design System (CRITICAL)

```
design-semantic-colors
```
- Use semantic and system colors
```
design-typography
```
- Use system typography styles
```
design-visual-hierarchy
```
- Establish clear visual hierarchy
```
design-dark-mode
```
- Support Dark Mode from day one
```
design-material-backgrounds
```
- Use material backgrounds for depth
```
design-sf-symbols
```
- Use SF Symbols for consistent iconography
```
design-safe-areas
```
- Respect safe areas for content layout
```
design-gradients
```
- Apply gradients for visual depth
```
design-foreground-style
```
- Use foregroundStyle over foregroundColor

2. State & Data Flow (CRITICAL)

```
state-local
```
- Use @State for view-local value types
```
state-binding
```
- Use @Binding for child view mutations
```
state-environment
```
- Use @Environment for shared app data
```
state-observable
```
- Use @Observable for model classes
```
state-avoid-in-body
```
- Avoid creating state inside view body
```
state-minimize-scope
```
- Minimize state scope to reduce re-renders
```
state-bindable
```
- Use @Bindable for @Observable bindings

3. Layout & Sizing (HIGH)

```
layout-8pt-grid
```
- Use 8pt grid for spacing
```
layout-readable-width
```
- Constrain text to readable width on iPad
```
layout-adaptive
```
- Use adaptive layouts for different size classes
```
layout-standard-margins
```
- Use system standard margins
```
layout-scroll-indicators
```
- Show scroll indicators for long content
```
layout-stacks
```
- Use stacks instead of manual positioning
```
layout-stack-config
```
- Configure stack alignment and spacing
```
layout-spacer
```
- Use Spacer for flexible distribution
```
layout-frame-sizing
```
- Use frame() for explicit size constraints
```
layout-zstack
```
- Use ZStack for layered view composition
```
layout-grid
```
- Use Grid for aligned tabular layouts
```
layout-lazy-grids
```
- Use LazyVGrid for scrollable grid layouts

4. View Composition (HIGH)

```
view-body-some-view
```
- Return some View from body property
```
view-custom-properties
```
- Use properties to make views configurable
```
view-modifier-order
```
- Apply modifiers in correct order
```
view-viewbuilder
```
- Use @ViewBuilder for flexible composition
```
view-prefer-value-types
```
- Prefer value types for view data
```
view-prefer-composition
```
- Prefer composition over inheritance

5. Navigation (HIGH)

```
nav-navigationstack
```
- Use NavigationStack for modern navigation
```
nav-tabview
```
- Organize app sections with TabView
```
nav-sheet-item
```
- Use item binding for sheet presentation
```
nav-dismiss
```
- Use environment dismiss for modal closure
```
nav-toolbar
```
- Place toolbar items correctly
```
nav-tab-bar
```
- Use tab bar for top-level navigation
```
nav-bar
```
- Configure navigation bar
```
nav-hierarchy
```
- Design clear navigation hierarchy
```
nav-search
```
- Integrate search using searchable modifier

6. Components & Controls (HIGH)

```
comp-list-vs-lazyvstack
```
- Choose List vs LazyVStack by feature needs
```
comp-sheet-vs-fullscreen
```
- Choose sheet vs fullScreenCover
```
comp-picker
```
- Choose the right picker style
```
comp-grid-vs-lazygrid
```
- Choose Grid vs LazyVGrid by data size
```
comp-textfield
```
- Configure text input components
```
comp-button
```
- Use appropriate button styles
```
comp-list-cells
```
- Design list cells with standard layouts
```
comp-alerts
```
- Use alerts sparingly for critical information
```
comp-action-sheets
```
- Use action sheets for contextual choices
```
comp-segmented
```
- Use segmented controls for exclusive options
```
comp-menus
```
- Use menus for secondary actions
```
comp-content-unavailable
```
- Use ContentUnavailableView for empty states

7. Accessibility (HIGH)

```
access-voiceover-labels
```
- Add VoiceOver labels to interactive elements
```
access-touch-targets
```
- Ensure minimum 44pt touch targets
```
access-reduce-motion
```
- Respect reduce motion preference

8. Animation & Polish (MEDIUM)

```
anim-transitions
```
- Use semantic transitions for appearing views
```
anim-loading-states
```
- Animate loading and empty states
```
anim-with-animation
```
- Use withAnimation for explicit state changes
```
anim-matched-geometry
```
- Use matchedGeometryEffect for smooth view transitions

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules

ios-design

NPX Install

Tags

SKILL.md Content