SwiftUI Design Excellence

Encode Apple's Human Interface Guidelines as machine-enforceable rules for SwiftUI code review, generation, and iteration. Target: iOS 17+ by default (configurable via settings).

Operational Modes

Review Mode

Accept SwiftUI code (files or inline) and evaluate against 40 enforceable rules.

Process:

1. •Read the target SwiftUI file(s)
2. •Check settings for iOS target version and strictness — read .claude/swift-design.local.md if it exists (see Settings section below)
3. •Load references/review-checklist.md for the complete rule set
4. •Evaluate code against each applicable rule category in priority order:
   • •Modern API compliance (M1–M6) — load references/deprecated-apis.md for replacement patterns
   • •Accessibility (A1–A7) — load references/accessibility-guide.md for detailed checks
   • •Platform idioms (P1–P6) — load references/component-patterns.md for correct patterns
   • •Spacing & layout (S1–S7)
   • •Typography (T1–T5)
   • •Color & contrast (C1–C4)
5. •Calculate letter grade per the rubric in references/review-checklist.md
6. •Output findings grouped by severity: 🔴 Critical → 🟡 Warning → 🔵 Suggestion → 🟢 Praise
7. •Each finding: rule ID, file:line, description, concrete fix

When iterating on existing code (review + feedback argument):

• •Focus analysis on the areas mentioned in feedback
• •Load the relevant reference file for that area
• •Apply targeted improvements as a minimal diff
• •Re-run the checklist on modified code
• •Report what changed and the new grade

Visual Review Mode

Accept a screenshot or mockup of an iOS screen.

Process:

1. •Load references/visual-review-rubric.md
2. •Evaluate the screenshot across 5 dimensions:
   • •Platform nativeness (30% weight)
   • •Visual hierarchy (25%)
   • •Spacing consistency (20%)
   • •Color coherence (15%)
   • •Typography discipline (10%)
3. •Score each dimension 1–5 with specific observations
4. •Calculate weighted average and map to letter grade
5. •Provide top 3 actionable improvements

Generation Mode

Accept a natural language description (or screenshot as reference) and produce HIG-compliant SwiftUI code.

Process:

1. •Load references/design-tokens.md for spacing, typography, color tokens
2. •Load references/hig-rules.md for generation guidelines
3. •Load references/component-patterns.md for structural patterns
4. •Load references/deprecated-apis.md to ensure modern API usage
5. •Generate SwiftUI code that:
   • •Uses semantic font styles and colors
   • •Follows 8pt spacing grid via design tokens
   • •Handles all view states (loading, empty, error, content)
   • •Includes accessibility labels and proper tap targets
   • •Uses @Observable, NavigationStack, Tab API
   • •Applies spring animations and appropriate haptics
6. •Self-verify output against references/review-checklist.md
7. •Output the code plus a design specification noting:
   • •Type hierarchy used (which text styles, why)
   • •Spacing choices (which tokens, why)
   • •Color decisions (which semantic colors, why)
   • •Accessibility considerations applied

Settings

Read settings from .claude/swift-design.local.md if present:

---
ios-target: 17
strictness: standard
---

ios-target (16 | 17 | 18, default: 17):

• •iOS 16: M2 (@Observable) becomes suggestion, M3 (Tab API) becomes suggestion
• •iOS 17: M3 (Tab API) becomes suggestion, all others at listed severity
• •iOS 18: All 40 rules at their listed severity

strictness (relaxed | standard | strict, default: standard):

• •relaxed: Only 🔴 Critical rules reported
• •standard: 🔴 Critical + 🟡 Warning reported, 🔵 Suggestions at end
• •strict: All findings reported, grade penalizes suggestions

Key Anti-Patterns

The most common failures in AI-generated SwiftUI — check these first:

1. •NavigationStack wrapping TabView (P2) — tab bar disappears during navigation
2. •NavigationView instead of NavigationStack (M1) — deprecated since iOS 16
3. •ObservableObject instead of @Observable (M2) — causes unnecessary re-renders
4. •Color.black/Color.white (C1) — invisible in dark mode
5. •Hardcoded font sizes (T1) — breaks Dynamic Type
6. •.onTapGesture instead of Button (A4) — invisible to VoiceOver

See references/anti-patterns.md for the complete anti-pattern catalog with examples.

Reference Files

Consult these for detailed guidance: