playbooks

home / skills / petekp / claude-code-setup / swiftui

swiftui skill

/skills/swiftui

This skill helps you design and implement world-class SwiftUI interfaces with accessibility, performance, and Apple-like polish across platforms.

npx playbooks add skill petekp/claude-code-setup --skill swiftui

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
4.4 KB
---
name: swiftui
description: Use when building SwiftUI interfaces for iOS, iPadOS, macOS, or visionOS. Triggers on Liquid Glass adoption, SwiftUI animation/transitions, layout patterns, state management, design tokens, performance optimization, accessibility in SwiftUI, or creating "Apple-level" UI quality.
---

# SwiftUI Excellence Playbook

Tactical guide for designing and building world-class SwiftUI interfaces—the kind that feel at home next to Apple's own apps.

## Six Non-Negotiables

1. **Content first** — UI is a frame, not the painting
2. **System components unless measured reason not to** — buy accessibility, platform behavior, design updates for free
3. **Design for states, not screens** — every screen handles: loading, empty, error, offline, partial, permission denied
4. **Accessibility is a constraint** — Dynamic Type, VoiceOver, Reduce Motion/Transparency, Increased Contrast
5. **Performance is a feature** — "feels instant" interactions, instrument when hitches occur
6. **Coherence over cleverness** — best interfaces feel inevitable

## Quick Reference: ADA Rubric

| Category | Requirement |
|----------|-------------|
| **Delight** | Micro-delight at success moments only, never reduces clarity |
| **Innovation** | In discovery, state communication, simplifying complexity |
| **Interaction** | Predictable, direct, forgiving, platform-appropriate |
| **Inclusivity** | Dynamic Type XXL+, VoiceOver, no color-only meaning, reduced motion |
| **Visuals** | Consistent rhythm, coherent materials, restrained tint |

## Design Workflow (Step-by-Step)

1. **Define experience** — 10-line spec: goal, primary action, states, edge cases, platforms
2. **Sketch IA** — TabView vs NavigationSplitView vs deep navigation
3. **Design hierarchy** — one hero, one primary CTA per moment, progressive disclosure
4. **Build tokens first** — spacing, radius, typography, motion, colors
5. **Build components** — cards, rows, buttons, empty states, filters
6. **Integrate structure** — NavigationStack, NavigationSplitView, TabView, Sheets
7. **Add motion** — only what improves comprehension and causality
8. **Accessibility + performance pass** — Dynamic Type, VoiceOver, Instruments

## Liquid Glass Quick Rules (iOS 26+)

**Do:**
- Use glass for navigation/control layer floating above content
- Group nearby glass in `GlassEffectContainer`
- Use `glassEffect(.interactive)` for custom controls
- Use `glassEffectID` for morphing transitions

**Don't:**
- Glass on content layer (tables, documents)
- Glass on glass stacking
- Tint everything — only primary actions/meaning
- Custom backgrounds behind toolbars (let system handle scroll edge effects)

## Layout Essentials

| Container | Use For |
|-----------|---------|
| `List` | Large datasets, selection, swipe actions, edit mode |
| `ScrollView` + `LazyVStack` | Custom surfaces, cards, mixed content |
| `Grid` | Forms, settings, dense structured layouts |
| `LazyVGrid` | Responsive galleries |
| `NavigationSplitView` | iPad/Mac hierarchical apps |
| `NavigationStack` | Deep navigation flows |

## Animation Principles

- Motion communicates **causality**, **hierarchy**, **continuity**
- State-driven animation, not imperative choreography
- Springs for organic UI, ease-in/out for fades
- Custom transitions for signature moments only
- Always provide Reduce Motion fallback

## Performance Rules

| Rule | Implementation |
|------|----------------|
| Body must be cheap | No sorting, filtering, formatting, I/O in body |
| Stable identity | `ForEach(items, id: \.id)` not `\.self`, no UUID() in body |
| Dependency hygiene | Keep @State local, pass Binding not whole model |
| Instrument | Use SwiftUI instrument (Instruments 26) for hitches |

## Accessibility Checklist

- [ ] System text styles, no clipping at XXL+
- [ ] Layout adapts (stacks turn vertical, rows multi-line)
- [ ] VoiceOver labels/hints on non-obvious controls
- [ ] Focus order matches reading order
- [ ] 44×44pt minimum touch targets
- [ ] Reduced Motion removes parallax, uses opacity
- [ ] Reduced Transparency increases separation

## Component Primitives (Build These)

1. Screen scaffold
2. Section header
3. Card surface
4. List row
5. Primary/secondary/icon buttons
6. Empty state
7. Loading skeleton
8. Error banner
9. Form field row
10. Chip/tag/pill

## Full Reference

For complete implementation patterns, code recipes, design tokens, Liquid Glass details, and the full ADA review checklist:

See: [swiftui-playbook.md](swiftui-playbook.md)

Overview

This skill helps you design and build production-grade SwiftUI interfaces that match Apple-level quality across iOS, iPadOS, macOS, and visionOS. It codifies layout patterns, state-driven animation, Liquid Glass guidance, accessibility constraints, and performance rules so you ship interfaces that feel coherent and fast. Use it as a practical checklist and pattern library while implementing screens and components.

How this skill works

The skill inspects design and implementation choices against six non-negotiables: content-first layout, system component preference, state-driven UI, accessibility as a constraint, performance as a feature, and coherence over cleverness. It provides concrete layout recommendations, animation principles, Liquid Glass usage rules, component primitives to build, and a compact ADA/accessibility checklist. It flags common SwiftUI anti-patterns like work-heavy view bodies, unstable identities, and improper state ownership.

When to use it

  • When designing new SwiftUI screens or migrating UIKit flows to SwiftUI
  • When introducing Liquid Glass visuals or platform-specific glass effects (iOS 26+)
  • When auditing accessibility (Dynamic Type, VoiceOver, Reduced Motion)
  • When optimizing SwiftUI performance or debugging hitches
  • When creating a component library or design token system for a SwiftUI app
  • When choosing navigation structures for multiplatform apps

Best practices

  • Start with a 10-line experience spec: goal, primary action, states, edge cases, platforms
  • Favor system components unless you have a measured reason not to
  • Design for states (loading, empty, error, offline, permissions) rather than static screens
  • Keep View bodies cheap: no sorting, formatting, I/O or UUID() creation in body
  • Use state-driven animations; provide Reduce Motion fallbacks and prefer springs for organic motion
  • Build tokens first (spacing, radius, typography, motion, colors) and then component primitives

Example use cases

  • Implement a master-detail app with NavigationSplitView for iPad/Mac, NavigationStack for deep flows
  • Create a card-based dashboard using ScrollView + LazyVStack with accessible text scaling
  • Add Liquid Glass controls to a floating toolbar using GlassEffectContainer and glassEffect(.interactive)
  • Refactor a list to use List for large datasets and LazyVGrid for responsive galleries
  • Audit an app for accessibility failures: Dynamic Type clipping, missing VoiceOver labels, touch-target violations

FAQ

When should I use Liquid Glass?

Use glass for floating navigation and control layers (iOS 26+). Avoid placing glass on primary content layers, stacking glass layers, or tinting everything; group related glass in GlassEffectContainer.

How do I keep SwiftUI views performant?

Make bodies cheap, avoid work in body, use stable identities in ForEach, keep @State local, pass Bindings instead of full models, and instrument with SwiftUI/Instruments to find hitches.