ios-design

Files (66)

• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• compose-body-some-view.md · references/
• compose-custom-properties.md · references/
• compose-modifier-order.md · references/
• compose-prefer-composition.md · references/
• compose-prefer-value-types.md · references/
• compose-viewbuilder.md · references/
• converse-dismiss.md · references/
• converse-hierarchy.md · references/
• converse-nav-bar.md · references/
• converse-navigationstack.md · references/
• converse-search.md · references/
• converse-sheet-item.md · references/
• converse-tab-bar.md · references/
• converse-tabview.md · references/
• converse-toolbar.md · references/
• craft-avoid-body-state.md · references/
• craft-minimize-scope.md · references/
• craft-state-bindable.md · references/
• craft-state-binding.md · references/
• craft-state-environment.md · references/
• craft-state-local.md · references/
• craft-state-observable.md · references/
• empathy-dark-mode.md · references/
• empathy-foreground-style.md · references/
• empathy-readable-width.md · references/
• empathy-reduce-motion.md · references/
• empathy-safe-areas.md · references/
• empathy-semantic-colors.md · references/
• empathy-touch-targets.md · references/
• empathy-voiceover-labels.md · references/
• layout-adaptive.md · references/
• layout-frame-sizing.md · references/
• layout-grid.md · references/
• layout-lazy-grids.md · references/
• layout-scroll-indicators.md · references/
• layout-spacer.md · references/
• layout-stacks.md · references/
• layout-zstack.md · references/
• product-content-unavailable.md · references/
• product-list-cells.md · references/
• product-loading-states.md · references/
• product-matched-geometry.md · references/
• product-menus.md · references/
• product-segmented.md · references/
• product-transitions.md · references/
• product-with-animation.md · references/
• system-gradients.md · references/
• system-material-backgrounds.md · references/
• system-sf-symbols.md · references/
• system-spacing-grid.md · references/
• system-stack-config.md · references/
• system-standard-margins.md · references/
• system-typography.md · references/
• system-visual-hierarchy.md · references/
• taste-action-sheets.md · references/
• taste-alerts.md · references/
• …and 6 more

SKILL.md (first lines)

# 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`](references/empathy-semantic-colors.md) - Use semantic colors, never hard-coded values
- [`empathy-dark-mode`](references/empathy-dark-mode.md) - Support Dark Mode from day one
- [`empathy-foreground-style`](references/empathy-foreground-style.md) - Use foregroundStyle over foregroundColor
- [`empathy-safe-areas`](references/empathy-safe-areas.md) - Always respect safe areas for content
- [`empathy-voiceover-labels`](references/empathy-voiceover-labels.md) - Add VoiceOver labels to every interactive element
- [`empathy-touch-targets`](references/empathy-touch-targets.md) - Ensure 44x44 point minimum touch targets
- [`empathy-reduce-motion`](references/empathy-reduce-motion.md) - Always provide reduce motion fallback
- [`empathy-readable-width`](references/empathy-readable-width.md) - 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`](references/system-typography.md) - Use system typography styles, never fixed sizes
- [`system-visual-hierarchy`](references/system-visual-hierarchy.md) - Establish clear visual hierarchy through size, weight, and color
- [`system-spacing-grid`](references/system-spacing-grid.md) - Use a 4pt base unit for all spacing
- [`system-material-backgrounds`](references/system-material-backgrounds.md) - Use material backgrounds for depth and layering
- [`system-sf-symbols`](references/system-sf-symbols.md) - Use SF Symbols for consistent iconography
- [`system-gradients`](references/system-gradients.md) - Apply gradients for visual depth, not decoration
- [`system-standard-margins`](references/system-standard-margins.md) - Use system standard margins consistently
- [`system-stack-config`](references/system-stack-config.md) - 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`](references/craft-state-local.md) - Use @State for view-local value types
- [`craft-state-binding`](references/craft-state-binding.md) - Use @Binding for child view mutations
- [`craft-state-environment`](references/craft-state-environment.md) - Use @Environment for shared app-wide data
- [`craft-state-observable`](references/craft-state-observable.md) - Use @Observable for model classes
- [`craft-avoid-body-state`](references/craft-avoid-body-state.md) - Never create state inside the view body
- [`craft-minimize-scope`](references/craft-minimize-scope.md) - Minimize state scope to reduce re-renders
- [`craft-state-bindable`](references/craft-state-bindable.md) - Use @Bindable for @Observable bindings

### 4. Creative Composition (HIGH)

Kocienda: "Creative selection — great software is built through composition and recombination."

- [`compose-body-some-view`](references/compose-body-some-view.md) - Return some View from body, never concrete types
- [`compose-custom-properties`](references/compose-custom-properties.md) - Use properties to make views configurable
- [`compose-modifier-order`](references/compose-modifier-order.md) - Apply view modifiers in the correct order
- [`compose-viewbuilder`](references/compose-viewbuilder.md) - Use @ViewBuilder for flexible slot-based composition
- [`compose-prefer-value-types`](references/compose-prefer-value-types.md) - Prefer value types for view data
- [`compose-prefer-composition`](references/compose-prefer-composition.md) - 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`](references/taste-list-vs-lazyvstack.md) - Choose List for system features, LazyVStack for custom layouts
- [`taste-sheet-vs-fullscreen`](references/taste-sheet-vs-fullscreen.md) - Choose sheet for tasks, fullScreenCover for immersion
- [`taste-picker`](references/taste-picker.md) - Choose the right picker style for the data type
- [`taste-grid-vs-lazygrid`](references/taste-grid-vs-lazygrid.md) - Choose Grid for aligned data, LazyVGrid for scrollable collections
- [`taste-button`](references/taste-button.md) - Use button styles that match the action's importance
- [`taste-textfield`](references/taste-textfield.md) - Configure text input with the right keyboard and content type
- [`taste-alerts`](references/taste-alerts.md) - Use alerts only for critical, blocking information
- [`taste-action-sheets`](references/taste-action-sheets.md) - 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.

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills