swift-design

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:

File	Contents	When to Load
references/review-checklist.md	40 rules, severity, grade rubric	Every review
references/deprecated-apis.md	Before/after for every deprecated API	Reviews with modern API violations, generation
references/design-tokens.md	Spacing, typography, color, radius tokens	Generation mode
references/hig-rules.md	HIG fundamentals for generation	Generation mode
references/accessibility-guide.md	VoiceOver, Dynamic Type, contrast, motor	Reviews with accessibility issues
references/component-patterns.md	TabView, NavigationStack, List, Form, states	Reviews with structural issues, generation
references/animation-guide.md	Spring animations, haptics, micro-interactions	Generation, animation reviews
references/visual-review-rubric.md	5-dimension screenshot evaluation	Visual review mode
references/anti-patterns.md	AI-generated code smells and fixes	Quick checks, all reviews