ahmedhamadto/software-forge/design-code-review

Design+Code Review

Overview

A structured design and code review methodology based on Design+Code by Meng To. Guides you through 8 sequential phases to systematically evaluate SwiftUI interfaces against the principles that separate amateur from professional Apple platform apps. Covers visual hierarchy, layout structure, animation quality, visual effects, gestures, data management, platform conventions, and accessibility.

When to Use

• When building a new SwiftUI screen or component and want to validate it against best practices
• During code review of SwiftUI views before merging
• When an interface "feels off" but you cannot pinpoint why
• Before submitting an app to the App Store
• When porting an iOS app to macOS (or vice versa)
• When refactoring a view that has accumulated design debt

When NOT to Use

• For backend/API code that has no UI component
• For UIKit/AppKit code (this is SwiftUI-focused)
• As a replacement for user testing with real people
• For brand/marketing design decisions (logo, brand colors) -- this is about implementation quality

Process

Work through each phase sequentially. At each phase:

1. Ask targeted questions about the specific interface
2. Read the relevant chapter summary from apple-development/design-and-code/ for detailed guidance
3. Suggest and execute concrete tests (grep patterns in SwiftUI source, Xcode preview configurations, Accessibility Inspector checks)
4. Flag findings with severity: CRITICAL / HIGH / MEDIUM / LOW / INFO
5. Summarize findings before moving to the next phase

If the interface does not have a relevant surface for a phase (e.g., no animations in a static settings screen), acknowledge and skip with rationale.

digraph review_phases {
  rankdir=TB;
  node [shape=box, style=rounded];
 
  p1 [label="Phase 1\nVisual Hierarchy &\nDesign Fundamentals"];
  p2 [label="Phase 2\nSwiftUI Structure\n& Layout"];
  p3 [label="Phase 3\nAnimation Quality"];
  p4 [label="Phase 4\nVisual Effects\n& Materials"];
  p5 [label="Phase 5\nGestures & Haptics"];
  p6 [label="Phase 6\nData & State\nManagement"];
  p7 [label="Phase 7\nPlatform\nConventions"];
  p8 [label="Phase 8\nAccessibility\n& Polish"];
  report [label="Design+Code\nReview Report", shape=note];
 
  p1 -> p2 -> p3 -> p4 -> p5 -> p6 -> p7 -> p8 -> report;
}

Phase 1: Visual Hierarchy & Design Fundamentals

Reference: apple-development/design-and-code/s01-design-fundamentals.md

Goal: Verify the interface communicates a clear visual hierarchy and follows foundational design principles.

Questions to ask:

• What is the app's personality? (Professional, playful, minimal, expressive?)
• Is there a defined spacing scale, or are padding/spacing values arbitrary?
• Is there a defined type scale, or are font sizes chosen ad hoc?
• Does the interface pass the squint test? (Blur your eyes -- can you identify primary, secondary, and tertiary content?)

Tests to run:

Color usage (60-30-10 rule):

# Check for hardcoded color values instead of semantic/system colors
grep -rn "Color(red:\|Color(#\|UIColor(red:\|NSColor(red:\|\.color(red:" --include="*.swift"
 
# Check for system/semantic color usage (good practice)
grep -rn "Color\.primary\|Color\.secondary\|Color\.accentColor\|Color(.system" --include="*.swift"
 
# Check for dark mode support via asset catalogs
find . -name "*.colorset" -type d

Typography hierarchy:

# Check for hardcoded font sizes (prefer system text styles)
grep -rn "\.font(.system(size:" --include="*.swift"
 
# Check for system text style usage (good practice)
grep -rn "\.font(\.largeTitle\|\.font(\.title\|\.font(\.headline\|\.font(\.body\|\.font(\.caption\|\.font(\.subheadline\|\.font(\.callout\|\.font(\.footnote" --include="*.swift"
 
# Check for font weight hierarchy
grep -rn "\.fontWeight(\|\.bold(\|\.semibold\|\.light\|\.thin\|\.heavy" --include="*.swift"

Spacing consistency:

# Find arbitrary padding/spacing values (magic numbers)
grep -rn "\.padding(\.[0-9]\|\.padding(EdgeInsets\|spacing: [0-9]" --include="*.swift"
 
# Check for a defined spacing system (good practice)
grep -rn "enum Spacing\|struct Spacing\|extension CGFloat" --include="*.swift"

Dark mode support:

# Check for hardcoded colors that will not adapt to dark mode
grep -rn "Color\.white\|Color\.black\|Color(\.white)\|Color(\.black)" --include="*.swift"
 
# Check for colorScheme environment usage
grep -rn "colorScheme\|\.preferredColorScheme\|@Environment.*colorScheme" --include="*.swift"

Flag:

• HIGH -- No dark mode support (hardcoded light-only colors throughout)
• MEDIUM -- Hardcoded font sizes instead of system text styles
• MEDIUM -- No spacing system (arbitrary padding values everywhere)
• LOW -- Minor inconsistencies in spacing or type scale
• INFO -- Opportunity to strengthen visual hierarchy with the 60-30-10 rule

Deliverable: Assessment of visual hierarchy quality, color system, type scale, and spacing consistency.

Phase 2: SwiftUI Structure & Layout

Reference: apple-development/design-and-code/s02-swiftui-fundamentals.md, apple-development/design-and-code/s05-layout-and-composition.md

Goal: Verify SwiftUI code follows structural best practices -- correct property wrappers, clean layout, appropriate navigation, and responsive design.

Questions to ask:

• What is the target platform? (iOS, macOS, both?)
• Does the interface need to adapt to different screen sizes?
• How complex is the view hierarchy? Can it be simplified?

Tests to run:

State management correctness:

# Check for @StateObject vs @ObservedObject misuse
grep -rn "@ObservedObject.*=.*\(\)" --include="*.swift"
# ^ CRITICAL: creating objects inline with @ObservedObject causes re-creation on every render
 
# Check for @State not marked private
grep -rn "@State [^p]\|@State$" --include="*.swift"
# @State should always be private
 
# Check for single source of truth violations (duplicate state)
grep -rn "@State.*var.*=.*@State\|@Published.*var.*=.*@Published" --include="*.swift"

GeometryReader overuse:

# Count GeometryReader usage (should be rare)
grep -rn "GeometryReader" --include="*.swift"
# If used frequently, suggest alternatives: .onGeometryChange(), Layout protocol, frame modifiers

Hardcoded frame sizes:

# Find hardcoded frame dimensions (may indicate non-responsive design)
grep -rn "\.frame(width: [0-9]\|\.frame(height: [0-9]" --include="*.swift"
 
# Check for responsive alternatives
grep -rn "\.frame(maxWidth: \.infinity\|ViewThatFits\|horizontalSizeClass\|AnyLayout" --include="*.swift"

Navigation pattern:

# Check navigation container usage
grep -rn "NavigationStack\|NavigationSplitView\|NavigationView" --include="*.swift"
# NavigationView is deprecated -- should use NavigationStack or NavigationSplitView
 
# Check for programmatic navigation support
grep -rn "NavigationPath\|navigationDestination" --include="*.swift"

Magic numbers in padding/spacing:

# Find raw numeric values in padding and spacing
grep -rn "\.padding([0-9]\|\.padding(\.[a-z]*, [0-9]\|spacing: [0-9]" --include="*.swift"

Modifier order issues:

# Check for common modifier order mistakes
# .background before .padding means background is tight to content
# .clipShape should come after .background
grep -rn -A2 "\.background\|\.clipShape\|\.shadow" --include="*.swift"

Lazy stack usage for lists:

# Check for non-lazy stacks with ForEach (performance issue for large lists)
grep -rn "VStack.*{" --include="*.swift" -A5 | grep "ForEach"
# Should use LazyVStack inside ScrollView for long lists

Flag:

• CRITICAL -- @ObservedObject with inline initialization (state loss on re-render)
• HIGH -- Deprecated NavigationView usage
• HIGH -- Non-lazy VStack/HStack with ForEach over large collections
• MEDIUM -- Excessive GeometryReader usage where simpler alternatives exist
• MEDIUM -- Hardcoded frame sizes preventing responsive layout
• LOW -- Magic numbers in padding/spacing values
• INFO -- Opportunity to use ViewThatFits or AnyLayout for adaptive layouts

Deliverable: Assessment of SwiftUI code structure, state management correctness, and layout quality.

Phase 3: Animation Quality

Reference: apple-development/design-and-code/s03-animations-and-transitions.md

Goal: Verify animations are purposeful, well-tuned, and performant -- every animation should communicate something.

Questions to ask:

• What state changes occur in this interface? Are they all animated?
• Are interactive elements providing feedback on press/tap?
• Are view transitions smooth, or do views appear/disappear abruptly?

Tests to run:

Animation curve quality:

# Find linear animations on interactive elements (almost never appropriate for UI)
grep -rn "\.linear\b\|animation(.linear" --include="*.swift"
# Linear is only appropriate for progress bars and loading spinners
 
# Check for spring animation usage (preferred for UI)
grep -rn "\.spring(\|\.interactiveSpring\|\.bouncy\|\.snappy\|\.smooth" --include="*.swift"
 
# Check for well-tuned spring parameters
grep -rn "spring(response:\|dampingFraction:" --include="*.swift"

Transition quality:

# Check for transitions on conditional views
grep -rn "\.transition(" --include="*.swift"
 
# Find if/else view swaps that may lack transitions
grep -rn "if.*{" --include="*.swift" -A3 | grep -B1 "} else {"

matchedGeometryEffect for hero animations:

# Check for matchedGeometryEffect usage (hero transitions)
grep -rn "matchedGeometryEffect\|@Namespace" --include="*.swift"

Animation duration check:

# Find animations longer than 0.5 seconds (likely too slow for UI)
grep -rn "duration: [0-9]*\.\?[5-9]\|duration: [1-9]" --include="*.swift"

Micro-interactions:

# Check for button press effects (custom ButtonStyle)
grep -rn "ButtonStyle\|configuration\.isPressed\|PressableButton\|scaleEffect.*isPressed" --include="*.swift"
 
# Check for loading state indicators
grep -rn "ProgressView\|isLoading\|shimmer\|skeleton" --include="*.swift"

Animation performance:

# Check for drawingGroup usage on complex graphics
grep -rn "\.drawingGroup()" --include="*.swift"
 
# Check for layout property animation (less performant than transform animation)
# Animating frame/padding triggers layout recalculation; offset/scale/rotation are GPU-accelerated
grep -rn "withAnimation.*{" --include="*.swift" -A5 | grep "frame\|padding"

Flag:

• HIGH -- Linear animations on interactive elements (feels robotic)
• HIGH -- Missing transitions on conditional view changes (abrupt appear/disappear)
• MEDIUM -- Animations longer than 0.5 seconds (feels sluggish)
• MEDIUM -- No button press feedback (buttons feel unresponsive)
• MEDIUM -- No loading states (users stare at blank screens)
• LOW -- Spring parameters could be better tuned
• LOW -- Missing success/error animation feedback
• INFO -- Opportunity for matchedGeometryEffect hero transitions
• INFO -- Opportunity for micro-interactions that add delight

Deliverable: Assessment of animation purpose, curve quality, transitions, and performance.

Phase 4: Visual Effects & Materials

Reference: apple-development/design-and-code/s04-visual-effects-and-materials.md

Goal: Verify visual effects create appropriate depth and hierarchy -- materials, gradients, shadows, and layering follow Apple's design language.

Questions to ask:

• Does the interface communicate elevation/depth, or is everything flat?
• Are shadows consistent across similar elements?
• Are materials used where the background context adds value?

Tests to run:

Material usage:

# Check for system material usage (glass effects)
grep -rn "\.ultraThinMaterial\|\.thinMaterial\|\.regularMaterial\|\.thickMaterial\|\.ultraThickMaterial" --include="*.swift"