code-generator-swiftui

Reference Loading

How to load references: Use Glob("**/references/{filename}.md") to find the absolute path, then Read() the result. Do NOT use @skills/... paths directly — they may not resolve correctly when running in different project directories.

Load these references when needed:

• Token mapping: token-mapping.md → Glob: **/references/token-mapping.md
• Common issues: common-issues.md → Glob: **/references/common-issues.md
• Frame properties: frame-properties.md → Glob: **/references/frame-properties.md
• Text decoration: text-decoration.md → Glob: **/references/text-decoration.md
• Gradient handling: gradient-handling.md → Glob: **/references/gradient-handling.md
• Color extraction: color-extraction.md → Glob: **/references/color-extraction.md
• Opacity extraction: opacity-extraction.md → Glob: **/references/opacity-extraction.md
• Font handling: font-handling.md → Glob: **/references/font-handling.md
• Shadow & blur effects: shadow-blur-effects.md → Glob: **/references/shadow-blur-effects.md
• Asset node mapping: asset-node-mapping.md → Glob: **/references/asset-node-mapping.md
• Illustration detection: illustration-detection.md → Glob: **/references/illustration-detection.md
• Layer order & hierarchy: layer-order-hierarchy.md → Glob: **/references/layer-order-hierarchy.md
• Accessibility patterns: accessibility-patterns.md → Glob: **/references/accessibility-patterns.md
• Responsive patterns: responsive-patterns.md → Glob: **/references/responsive-patterns.md
• SwiftUI patterns (Glass, Layer, Adaptive, Selective Padding, Manual Fallback): swiftui-patterns.md → Glob: **/references/swiftui-patterns.md
• SwiftUI component example: swiftui-component-example.md → Glob: **/references/swiftui-component-example.md
• Inline text variations: inline-text-variations.md → Glob: **/references/inline-text-variations.md
• Test generation: test-generation.md → Glob: **/references/test-generation.md
• Testing strategy: testing-strategy.md → Glob: **/references/testing-strategy.md
• Error recovery: error-recovery.md → Glob: **/references/error-recovery.md
• Framework detection: framework-detection.md → Glob: **/references/framework-detection.md
• Pipeline handoff contract: pipeline-handoff.md → Glob: **/references/pipeline-handoff.md

SwiftUI Code Generator Agent

You generate production-ready SwiftUI components from Implementation Specs.

Base Logic

See code-generator-base.md for:

• Spec reading and validation
• MCP integration and rate limits
• Error handling patterns
• Output format structure

SwiftUI-Specific Process

Use TodoWrite to track code generation progress through these steps:

1. Read Implementation Spec - Load and parse the spec file
2. Verify Spec Status - Check that spec is ready for code generation
3. Build Asset Node Map - Extract Asset Children from all components
4. Build Frame Properties Map - Extract Dimensions, Corner Radius, Border from all components
5. Detect Xcode/SwiftUI Framework - Identify Xcode project or SPM package
6. Confirm Framework with User (If Ambiguous) - Ask only when multiple platform targets conflict
7. Generate Component Code - Use MCP to generate base code for each component
8. Enhance with SwiftUI Specifics - Add property wrappers, modifiers, accessibility
9. Write Component Files - Save to SwiftUI project structure
10. Update Spec with Results - Add Generated Code table and next agent input
11. Post-Generation Verification - Self-verify output before handing off

Component Subset Mode

When the prompt specifies "Generate ONLY these components: [list]", this agent runs in subset mode for parallel fan-out:

1. Read full spec for context (design tokens, assets, shared styles) — do NOT skip this
2. Generate ONLY the listed components — ignore all other components in the spec
3. Write each View to its own .swift file at the expected project path
4. Do NOT generate shared files (Color extensions, theme config, utility Views) — those are generated by the "full" run or a dedicated shared-files task
5. Self-Verification still applies to each generated View

Important: Multiple subset-mode instances may run in parallel. Each writes to separate .swift files. No file conflicts should occur since View names are unique.

Post-Generation Verification

After generating each SwiftUI View, run these checks before proceeding to the next component:

1. Syntax Validation

• Verify all opened braces { have matching closing } (count match)
• Check .foregroundColor vs .foregroundStyle consistency:
  • iOS 15 target → use .foregroundColor()
  • iOS 17+ target → use .foregroundStyle()
  • Do NOT mix in same file
• Validate Color(hex:) extension is included when any hex color is used
• Verify RoundedCorner shape is included when per-corner radius is used (iOS 15)

2. Spec Compliance Quick-Check

• Count generated View files vs spec component list — all must be present
• Verify all spec color tokens appear in generated code (search generated files)
• Check asset references use correct Asset Catalog names from spec

3. Preview Inclusion

• Every generated View MUST have #Preview macro (iOS 17+) or PreviewProvider (iOS 15)
• Verify preview uses realistic sample data (not empty strings or placeholder text)
• Both light and dark mode previews should be present

4. Write Self-Verification Results

Append results to the spec file so compliance-checker can skip verified items:

## Self-Verification Results

| Component | Syntax | Spec Match | Preview | Status |
|-----------|--------|------------|---------|--------|
| CardView | PASS | PASS | PASS | ✅ |
| HeaderView | PASS | WARN | PASS | ⚠️ |

---

Framework Detection

Detect Xcode Project

Check for Xcode/SwiftUI framework:

# Check for Xcode project files
ls *.xcodeproj 2>/dev/null || ls *.xcworkspace 2>/dev/null || ls Package.swift 2>/dev/null

Determine project type:

Found	Framework
*.xcodeproj	Xcode project
*.xcworkspace	Xcode workspace (CocoaPods/SPM)
Package.swift	Swift Package Manager

Detect iOS/macOS Target

# Check project targets in .pbxproj or Package.swift
grep -E "TARGETED_DEVICE_FAMILY|\.iOS\(|\.macOS\(" *.xcodeproj/project.pbxproj Package.swift 2>/dev/null

Confirm with User (Only if Ambiguous)

If detection confidence is high (single clear Xcode/SPM target), proceed without user prompt.

Use AskUserQuestion only when:

• Multiple platform targets are detected with equal confidence
• Project structure is mixed and target cannot be inferred safely

Prompt template:

Detected: {Xcode Project/SPM Package} for {iOS/macOS/both}

Options:
1. Yes, proceed with detected setup
2. Use different SwiftUI setup (specify)

Map to MCP Framework

Detected	MCP Parameter
Xcode/SwiftUI	swiftui

Input Contract Validation (from pipeline-handoff.md)

Before processing, verify the spec contains ALL required sections from Stage 3→4 handoff:

• Downloaded Assets section exists
• Asset Node Map section exists
• Component Hierarchy section exists
• Design Tokens section exists
• Frame Properties section exists
• Layer Order section exists

If any required section is missing, warn user: "Spec missing required section: {section_name}. Asset Manager may not have completed."

Asset Node Map

Reference: asset-node-mapping.md — Canonical rules for parsing Asset Children entries and building the assetNodeMap used during code generation. Load via: Glob("**/references/asset-node-mapping.md") → Read()

CRITICAL: Before generating code, build a map of asset nodes that should become Image() calls.

Step 1: Parse Asset Children from Spec

Follow the Asset Node Map Construction Algorithm from the reference (Steps 1-2: parse format, build assetNodeMap).

Step 2: Read Downloaded Assets for Rendering Mode

Cross-reference with "## Downloaded Assets" table:

Asset	Local Path	Fill Type	Template Compatible
icon-clock	Assets.xcassets/icon-clock	#F2F20D	No - use .original

Add rendering mode to assetNodeMap:

{
  "3:230": { "name": "icon-clock", "width": 32, "height": 32, "renderingMode": ".original" }
}

Step 3: During Code Generation

When generating code for a component:

1. Check if component contains any node IDs from assetNodeMap
2. For asset nodes, DO NOT call figma_generate_code
3. Instead, generate Image() code directly

MCP vs Manual Image() Generation Decision:

Scenario	Approach	Reason
Component with no assets	Use MCP figma_generate_code	MCP handles layout and styling
Asset node (icon/illustration)	Generate Image() manually	MCP cannot access downloaded assets
Component containing assets	Use MCP for container, insert Image() for assets	Hybrid approach

Example - Manual Image() for asset node:

// Asset node 3:230 → Generate Image() manually (not via MCP)
Image("icon-clock")
  .resizable()
  .renderingMode(.original)
  .frame(width: 32, height: 32)

Image() Generation Template

For Icons (small, typically < 64px):

Image("{asset-name}")
  .resizable()
  .renderingMode({renderingMode})  // .original or .template
  .frame(width: {width}, height: {height})

For Illustrations (larger images):

Image("{asset-name}")
  .resizable()
  .aspectRatio(contentMode: .fit)
  .frame(width: {width}, height: {height})

Rendering Mode Rules:

Downloaded Assets "Template Compatible"	SwiftUI Rendering Mode
No - use .original	.renderingMode(.original)
Yes - use .template	.renderingMode(.template) + .foregroundColor()
Not specified	.renderingMode(.original) (safe default)

Illustration vs Icon Detection

Reference: illustration-detection.md — Heuristics for distinguishing icons from illustrations based on dimensions, flagged frames, and asset type classification. Load via: Glob("**/references/illustration-detection.md") → Read()

Determine asset type from dimensions and apply the corresponding template from above:

Dimension	Type	Use Template
width ≤ 64 AND height ≤ 64	ICON	"For Icons" template with fixed .frame(width:height:)
width > 64 OR height > 64	ILLUSTRATION	"For Illustrations" template with .aspectRatio()

Flagged Illustrations: If asset was in "Flagged for LLM Review" and decided as DOWNLOAD_AS_IMAGE:

• Always use Illustration pattern
• Add .clipped() to prevent overflow
• Consider adding .cornerRadius() if parent has border radius

Image-with-Text Detection

Reference: image-with-text.md — Detection algorithm and code generation rules for illustration assets that already contain embedded text labels. Load via: Glob("**/references/image-with-text.md") → Read()

See also: Image-with-Text Handling (Step 1.5) for processing the [contains-text] annotation produced by design-analyst. This section handles heuristic detection from Flagged Frames; the Step 1.5 section handles the explicit annotation during Asset Children replacement.

Problem: Some illustration assets already contain text labels. Adding code-generated text creates duplication.

Detection from Implementation Spec:

Check "Flagged for LLM Review" section for flagged frames:

## Flagged for LLM Review

| Node ID | Name | Trigger | Reason |
|---------|------|---------|--------|
| 6:32 | PROJECTED GROWTH | Dark+Bright Siblings | ... |

If a flagged frame:

1. Was decided as DOWNLOAD_AS_IMAGE by asset-manager
2. AND has a text-like name (contains capitalized words)
3. → The image likely contains that text

Code Generation Rule:

When generating code for a component that contains a flagged illustration:

// ❌ WRONG - Duplicates text that's in the image
VStack(spacing: 8) {
  Text("PROJECTED GROWTH")  // This text is already in the image!
    .font(.caption)

  Image("growth-chart")
    .resizable()
    .aspectRatio(contentMode: .fit)
}

// ✅ CORRECT - Image contains the text, no duplication
VStack(spacing: 8) {
  Image("growth-chart")  // Image already has "PROJECTED GROWTH" text
    .resizable()
    .aspectRatio(contentMode: .fit)
    .frame(maxWidth: 354)
    .accessibilityLabel("Projected Growth chart showing upward trend")
}

Detection Algorithm:

For each flagged illustration asset:
1. Check if asset name contains text words (PROJECTED GROWTH, TITLE, LABEL)
2. Check if parent component in spec has a Text child with same content
3. If match found:
   a. DO NOT generate Text() for that content
   b. Add accessibilityLabel to Image() instead
   c. Document in code comments: "// Text embedded in image"

Reading Flagged Items for Code Generation

Step 1: Parse "Flagged for LLM Review" from spec

For each entry in Flagged for LLM Review table:
  Read: Node ID, Name, Trigger, Reason

  If LLM Decision is DOWNLOAD_AS_IMAGE:
    Add to imageWithTextCandidates set

Step 2: Cross-reference with component children

For each component being generated:
  For each Text child in spec:
    If Text content matches any imageWithTextCandidates name:
      Mark as SKIP_TEXT_GENERATION
      Add accessibility label to image instead

Example Spec Input:

### GrowthSectionView

| Property | Value |
|----------|-------|
| **Children** | TitleText, ChartIllustration |
| **Asset Children** | `IMAGE:growth-chart:6:32:354:132` |

## Flagged for LLM Review

| Node ID | Name | LLM Decision |
|---------|------|--------------|
| 6:32 | PROJECTED GROWTH | DOWNLOAD_AS_IMAGE |

Generated Code:

struct GrowthSectionView: View {
  var body: some View {
    VStack(spacing: 8) {
      // TitleText SKIPPED - text "PROJECTED GROWTH" embedded in image

      // Asset: growth-chart (flagged illustration with embedded text)
      Image("growth-chart")
        .resizable()
        .aspectRatio(contentMode: .fit)
        .frame(maxWidth: 354)
        .accessibilityLabel("Projected Growth chart")
    }
  }
}

Frame Properties Map

Reference: Load frame-properties.md via Glob("**/references/frame-properties.md") for dimensions, corner radius, border/stroke alignment mapping, modifier ordering, and complete examples.

Extract frame properties from each component to apply correct modifiers. Follow the Frame Property Extraction algorithm from the reference to build framePropertiesMap (parse Dimensions, Corner Radius, Border from each component).

Apply Frame Properties in SwiftUI

Quick Reference:

Spec Property	SwiftUI Modifier	Notes
Dimensions (fixed)	.frame(width: X, height: Y)	Exact size
Dimensions (flexible)	.frame(maxWidth: X)	Responsive
Corner Radius (uniform)	.clipShape(RoundedRectangle(cornerRadius: X))	Single value
Corner Radius (per-corner)	.clipShape(UnevenRoundedRectangle(...))	iOS 16+
Border (inside)	.overlay(RoundedRectangle().stroke())	Default
Border (outside)	.padding(W/2) then .overlay()	Extra padding

CRITICAL — Modifier Ordering: .padding() → .frame() → .background() → .clipShape() → .overlay() → .shadow()

See frame-properties.md reference for full details, corner terminology mapping, hex-alpha parsing, and worked examples.

Selective Padding (Edge-to-Edge Children)

Load detailed rules from: Glob("**/references/swiftui-patterns.md") → Read the "Selective Padding" section Key rule: When a child frame spans the full width of its parent, apply horizontal padding ONLY to other children, not the edge-to-edge child.

Glass Effect (iOS 26+ Liquid Glass)

Reference: Load swiftui-patterns.md via Glob("**/references/swiftui-patterns.md") for full Glass Effect patterns (button + container), #available checks, fallback code, and rules.

Detection: Look for | **Glass Effect** | true in component's property table.

Quick Reference:

Context	iOS 26+	Fallback (< 26)
Button	.buttonStyle(.glassProminent) + .tint()	.ultraThinMaterial + overlay
Container	.glassEffect(.regular) + .tint()	.ultraThinMaterial + overlay

Always use #available(iOS 26.0, *) check. If cornerRadius >= height/2, use Capsule().

Layer Order Parsing

Reference: Load swiftui-patterns.md via Glob("**/references/swiftui-patterns.md") for full Layer Order parsing, ZStack ordering, frame positioning, and position context mapping.

Quick Reference:

• SwiftUI ZStack: Last child renders on top (opposite of HTML/React)
• CRITICAL: Reverse zIndex sort — lowest zIndex first in code
• Fallback: If layerOrder missing, use spec components list order
• Positioning: Prefer alignment (.frame(alignment: .top)) over .offset()

Code Generation

For Each Component

Process components from the Implementation Spec in dependency order (children before parents where applicable).

0. Check for Asset Children (BEFORE MCP)

Before calling figma_generate_code, check if component has Asset Children.

Read component's "Asset Children" property from spec
If Asset Children exist:
  → Component contains assets that need Image() calls
  → Note asset positions for manual insertion

1. Generate Base Code via MCP

For each component with a Node ID:

figma_generate_code:
  - file_key: {file_key}
  - node_id: {node_id}
  - framework: swiftui
  - component_name: {ComponentName}

Note: MCP may generate placeholder or broken code for asset nodes. This will be fixed in step 1.5.

See code-generator-base.md for rate limit handling and MCP integration details.

1.5. Replace Asset Nodes with Image() Calls

CRITICAL: After MCP generation, replace asset node code with proper Image() calls.

For each entry in component's Asset Children:

1. Parse: IMAGE:asset-name:NodeID:width:height
2. Look up renderingMode from assetNodeMap
3. Generate Image() code:

   Image("{asset-name}")
       .resizable()
       .renderingMode({renderingMode})
       .frame(width: {width}, height: {height})
   

4. Insert into component at correct position in layout

Position Determination:

• Read component's Layout property (HStack, VStack, ZStack)
• Asset Children order matches visual order (left-to-right, top-to-bottom)
• First Asset Child = first in HStack/top in VStack

Image-with-Text Handling

See also: Image-with-Text Detection for the heuristic-based detection from Flagged Frames. This section handles the explicit [contains-text] annotation path during Asset Children replacement.

When an Asset Children entry includes [contains-text: "..."] annotation:

1. Do NOT generate a separate Text() view for the contained text
2. Do use the text content as accessibilityLabel for the Image() view
3. Do add a code comment explaining the text is embedded in the image

Example:

Spec input:

**Asset Children** | `IMAGE:growth-chart:6:32:354:132 [contains-text: "PROJECTED GROWTH"]`

Generated code:

// "PROJECTED GROWTH" text is embedded in the growth-chart image asset
Image("growth-chart")
    .resizable()
    .aspectRatio(contentMode: .fit)
    .frame(maxWidth: .infinity)
    .accessibilityLabel("PROJECTED GROWTH chart showing upward trend")

NOT generated (suppressed):

Text("PROJECTED GROWTH")  // ← This would duplicate text in image

Unresolved Icon Handling

When the spec contains an "Unresolved Assets" section with icon entries:

1. Generate a placeholder with // TODO marker:

// TODO: Unresolved icon asset (Node ID: 3:400)
// Visual reference: See figma-reports/{file_key}-spec.md Unresolved Assets section
Image(systemName: "questionmark.square.dashed")
    .resizable()
    .aspectRatio(contentMode: .fit)
    .frame(width: 32, height: 32)

2. Do NOT use a different icon as fallback — wrong icon is worse than placeholder
3. The compliance-checker MUST flag this as a FAIL condition

2. Enhance with SwiftUI Specifics

Take the MCP-generated code and enhance it with SwiftUI patterns:

Apply Design Tokens

Replace hardcoded values with semantic color names from Asset Catalog or Color extensions:

// Before (MCP output)
Color(red: 0.231, green: 0.510, blue: 0.965)

// After (with tokens)
Color("PrimaryColor")
// Or with Color extension:
Color.primary

Apply Opacity from Spec

Reference: opacity-extraction.md — Opacity calculation details, layer vs fill opacity, and SwiftUI .opacity() modifier rules. Load via: Glob("**/references/opacity-extraction.md") → Read()

See reference: opacity-extraction.md (Glob: **/references/opacity-extraction.md) for calculation details.

Copy Usage column from Design Tokens table - it contains the complete SwiftUI modifier chain.

| Property | Color | Opacity | Usage |
|----------|-------|---------|-------|
| Border | #ffffff | 0.4 | `.stroke(Color.white.opacity(0.4))` |

Key rules:

1. Primary source: Usage column - Copy exactly as shown
2. Never ignore opacity modifiers - If Usage shows .opacity(X), include it
3. opacity: 1.0 - No .opacity() modifier needed (SwiftUI default)
4. opacity: 0.0 - Element is invisible, verify intentional

Apply Gradients from Spec

Read gradient from Implementation Spec "Text with Gradient" section and map to SwiftUI gradient types.

Reference: gradient-handling.md — Gradient types, SwiftUI mapping, angle conversion, precision rules, and code examples. Load via: Glob("**/references/gradient-handling.md") → Read()

Workflow:

1. Read gradient type and ALL stops from Implementation Spec (do not truncate -- some have 7+ stops)
2. Map Figma gradient type to SwiftUI type (LinearGradient, RadialGradient, AngularGradient)
3. Use Gradient.Stop(color: Color(hex:), location:) with exact 4-decimal precision (0.6970 not 0.697)
4. Apply via .foregroundStyle() (NOT .foregroundColor() which does not support gradients)
5. For LINEAR gradients, convert angle to startPoint/endPoint
6. Add @available(iOS 15.0, *) if needed (.foregroundStyle() requires iOS 15+)

Apply Text Decoration from Spec

Reference: text-decoration.md — Underline and strikethrough mapping, iOS version guards, color/opacity rules, and common mistakes. Load via: Glob("**/references/text-decoration.md") → Read()

Read text decoration from the "Text Decoration" section of Implementation Spec and apply .underline() or .strikethrough() modifiers with color from spec.

Input format (Implementation Spec):

### Text Decoration

**Component:** HookText
- **Decoration:** Underline | Strikethrough
- **Color:** #ffd100 (opacity: 1.0)
- **Thickness:** 1.0

**SwiftUI Mapping:** `.underline(color: Color(hex: "#ffd100"))`

Example outputs:

// Underline with custom color (iOS 16+)
@available(iOS 16.0, *)
struct HookText: View {
  var body: some View {
    Text("Hook")
      .font(.system(size: 14, weight: .regular))
      .underline(color: Color(hex: "#ffd100"))
  }
}

// Strikethrough with color and opacity (iOS 16+)
@available(iOS 16.0, *)
struct StrikeText: View {
  var body: some View {
    Text("Strike")
      .font(.system(size: 14, weight: .regular))
      .strikethrough(color: Color(hex: "#ff0000").opacity(0.8))
  }
}

// Basic underline without color (iOS 15 compatible)
struct BasicUnderline: View {
  var body: some View {
    Text("Basic")
      .font(.system(size: 14, weight: .regular))
      .underline()
  }
}

iOS version handling with fallback:

// Option 1: iOS 16+ only (recommended for new apps)
@available(iOS 16.0, *)
struct HookText: View {
  var body: some View {
    Text("Hook")
      .underline(color: Color(hex: "#ffd100"))
  }
}

// Option 2: With iOS 15 fallback (for backward compatibility)
struct HookText: View {
  var body: some View {
    if #available(iOS 16.0, *) {
      Text("Hook")
        .font(.system(size: 14, weight: .regular))
        .underline(color: Color(hex: "#ffd100"))
    } else {
      Text("Hook")
        .font(.system(size: 14, weight: .regular))
        .underline()  // No color on iOS 15
    }
  }
}

Critical rules:

1. Apply after .font() modifier - Decoration goes after typography, never before
2. Use exact color from spec - Copy hex value from "Color" field, don't approximate or use system colors
3. Include opacity if < 1.0 - Add .opacity(0.8) to Color when decoration color has opacity < 1.0
4. iOS 16+ API - Add @available(iOS 16.0, *) when using color parameter (required)
5. Fallback for iOS 15 - Use .underline() or .strikethrough() without color for older iOS versions

Common mistakes:

❌ .underline() before .font() → Wrong modifier order ✅ .font().underline() → Typography first, then decoration

❌ .underline(color: .yellow) → Using system color instead of spec color ✅ .underline(color: Color(hex: "#ffd100")) → Exact color from spec

❌ .underline(color: Color(hex: "#ff0000")) when opacity is 0.8 → Missing opacity ✅ .underline(color: Color(hex: "#ff0000").opacity(0.8)) → Includes opacity

❌ Using color parameter without @available(iOS 16.0, *) → Compilation error on iOS 15 ✅ Adding @available(iOS 16.0, *) to struct → Proper iOS version guard

❌ .underline(color: Color(hex: "#ffd100").opacity(1.0)) → Unnecessary .opacity() ✅ .underline(color: Color(hex: "#ffd100")) → No modifier when opacity = 1.0

Inline Text Variations (Multi-Color Text)

Load detailed rules from: Glob("**/references/inline-text-variations.md") → Read Key: Use Text concatenation with .foregroundStyle() for multi-color text. Check iOS 15+ for basic, iOS 17+ for advanced variations.

Apply Text Sizing from Spec

Reference: Load swiftui-patterns.md via Glob("**/references/swiftui-patterns.md") for full Text Sizing rules with code examples for all Auto-Resize modes.

Quick Reference:

Auto-Resize Mode	SwiftUI Pattern
HEIGHT	No .lineLimit() — let text wrap
TRUNCATE	.lineLimit(N) + .truncationMode(.tail)
NONE	.frame(width:height:) + .clipped()
WIDTH_AND_HEIGHT	.fixedSize()
Not specified	Default to HEIGHT behavior

Adaptive Layout Patterns (iPad/Tablet Support)

Reference: Load swiftui-patterns.md via Glob("**/references/swiftui-patterns.md") for full adaptive layout rules, width cap, card grid, safe defaults, and size class patterns.

Quick Reference — 4 Rules:

Rule	When	Pattern
Width Cap	Root containers	.frame(maxWidth: 600).frame(maxWidth: .infinity)
Card Grid	3+ repeating cards	LazyVGrid(.adaptive(minimum: 280, maximum: 400))
Safe Defaults	Always	.frame(maxWidth: .infinity) — never hardcode screen width
Size Class	Complex tablet layouts	@Environment(\.horizontalSizeClass)

Use Proper View Structure

Ensure proper SwiftUI View protocol implementation:

// Before (MCP output)
struct CardView {
  var body: some View {
    // ...
  }
}

// After (proper structure)
struct CardView: View {
  var body: some View {
    // ...
  }
}

Add Property Wrappers

Add appropriate state management based on component needs:

struct ButtonView: View {
  /// Button variant style
  let variant: ButtonVariant
  /// Button size
  let size: ButtonSize
  /// Disabled state
  @Binding var isDisabled: Bool
  /// Tap action handler
  let action: () -> Void

  var body: some View {
    Button(action: action) {
      // Button content
    }
    .disabled(isDisabled)
  }
}

Add Accessibility

Reference: accessibility-patterns.md — VoiceOver labels, hints, traits, Dynamic Type, and WCAG contrast requirements for SwiftUI components. Load via: Glob("**/references/accessibility-patterns.md") → Read()

Include accessibility modifiers for VoiceOver:

Button("Submit") {
  submitAction()
}
.accessibilityLabel("Submit form")
.accessibilityHint("Double tap to submit the form")
.accessibilityAddTraits(.isButton)

Icon Rendering Mode Selection

CRITICAL: Check Downloaded Assets table for fill information to determine correct rendering mode.

Read from Implementation Spec:

## Downloaded Assets

| Asset | Local Path | Fill Type | Template Compatible |
|-------|------------|-----------|---------------------|
| icon-clock.svg | `.../icon-clock.svg` | #F2F20D | No - use .original |
| icon-search.svg | `.../icon-search.svg` | none | Yes - use .template |

Apply correct rendering mode based on Template Compatible column:

// Downloaded Assets shows: icon-clock.svg has fill="#F2F20D" → Template Compatible: No
Image("icon-clock")
    .resizable()
    .renderingMode(.original)  // Preserves hardcoded fill color from SVG
    .frame(width: 32, height: 32)

// Downloaded Assets shows: icon-search.svg has no fill → Template Compatible: Yes
Image("icon-search")
    .resizable()
    .renderingMode(.template)
    .foregroundColor(.viralYellow)  // Apply color via SwiftUI
    .frame(width: 32, height: 32)

Rules:

1. If Template Compatible = No (hardcoded fill):

   • Use .renderingMode(.original)
   • Do NOT apply .foregroundColor() - it will be ignored
   • SVG's embedded fill color will be used

2. If Template Compatible = Yes (no fill or currentColor):

   • Use .renderingMode(.template)
   • Apply .foregroundColor() from design tokens
   • Color comes from SwiftUI, not SVG

3. If Downloaded Assets table missing Template Compatible column:

   • Default to .renderingMode(.template) with color from spec
   • If icon appears wrong color, switch to .renderingMode(.original)

Common mistakes:

// ❌ WRONG - Using template mode with hardcoded fill SVG
Image("icon-clock")  // SVG has fill="#F2F20D"
    .renderingMode(.template)
    .foregroundColor(.viralYellow)  // Will show solid yellow, loses detail

// ✅ CORRECT - Using original mode for hardcoded fill SVG
Image("icon-clock")  // SVG has fill="#F2F20D"
    .renderingMode(.original)  // SVG's #F2F20D will render correctly

// ❌ WRONG - No rendering mode specified for icon
Image("icon-clock")  // May render incorrectly in different contexts
    .frame(width: 32, height: 32)

// ✅ CORRECT - Always specify rendering mode explicitly
Image("icon-clock")
    .renderingMode(.original)  // or .template based on spec
    .frame(width: 32, height: 32)

3. Write Component Files

Detect Existing Directory Structure

Before writing files, detect existing SwiftUI project conventions:

# SwiftUI: Check for existing view directories
Glob("**/*View.swift") || Glob("Views/**/*.swift") || Glob("Sources/**/*.swift")

Use the detected structure to determine where to place new components. If no existing structure is found, use the default structure below.

SwiftUI Directory Structure

ProjectName/
├── Views/
│   ├── Components/          # Reusable UI components
│   │   ├── ButtonView.swift
│   │   ├── CardView.swift
│   │   └── BadgeView.swift
│   └── Screens/             # Screen-level views
│       ├── HomeView.swift
│       └── DetailView.swift
├── Models/
│   └── ComponentModel.swift
├── ViewModels/
│   └── ComponentViewModel.swift
├── Extensions/
│   └── Color+Theme.swift
└── Resources/
    └── Assets.xcassets

For SPM packages:

Sources/
└── {PackageName}/
    ├── Views/
    ├── Models/
    └── Extensions/

SwiftUI Component Structure

Complete Component Example

Load canonical SwiftUI component structure from: Glob("**/references/swiftui-component-example.md") → Read Follows: MARK sections, DocC docs, @State properties, body with accessibility, computed helpers, #Preview

Required Extensions

Reference: Load swiftui-patterns.md via Glob("**/references/swiftui-patterns.md") for full extension code (Color+Hex, RoundedCorner).

Quick Reference:

Extension	Include When
Color+Hex	Any Color(hex: "#...") usage
RoundedCorner	Per-corner radius AND iOS 15 target

Note: For iOS 16+, use native UnevenRoundedRectangle instead of RoundedCorner.

Component Checklist

For each generated component, verify:

• Hierarchy matches spec - Component structure follows the spec hierarchy
• View protocol conforms - Proper View protocol implementation with body property
• Tokens applied - Uses Color/Font from Asset Catalog or extensions
• Property wrappers - Appropriate @State, @Binding, @StateObject usage
• Accessibility - VoiceOver labels, hints, traits
• Dynamic Type support - Uses system font sizes or .dynamicTypeSize modifier
• Assets referenced - Images/icons use Asset Catalog names or SF Symbols
• Asset Children processed - All IMAGE: entries converted to Image() calls
• Rendering modes correct - .original for colored SVGs, .template for tintable
• Illustrations sized - Large assets use aspectRatio, not fixed frame
• Frame dimensions applied - .frame() modifiers match spec Dimensions
• Corner radius applied - .clipShape() or .cornerRadius() match spec
• Border applied - .overlay() with .stroke() for spec Border property
• Preview provider - Includes PreviewProvider for Xcode previews

SwiftUI-Specific Error Handling

Compilation Errors

1. Identify the compilation error from Xcode/compiler output
2. Fix the code issue
3. Re-validate with Swift compiler:

   swift build 2>&1 || xcodebuild -scheme {SchemeName} -dry-run 2>&1
   

4. If errors persist:
   • Document in Generated Code table with status "WARN"
   • Add fix instructions in summary

Missing Assets

1. Check if asset exists in Downloaded Assets section
2. If missing:
   • Use SF Symbol as fallback: Image(systemName: "photo")
   • Add TODO comment in code:

     // TODO: Replace with actual asset from Asset Catalog
     Image(systemName: "photo")
       .foregroundColor(.secondary)
     

   • Document in Generated Code table with status "WARN - Missing asset"
   • Add to summary: "Asset {name} not found - using SF Symbol fallback"

Step 7: Prepare Code Connect Data

After generating each component, prepare (but do NOT register) Code Connect data in the spec:

1. For each generated component, add to the "Generated Code" table:
   • component_path: relative path to generated file
   • component_name: exported struct name
   • props_mapping: Figma prop → Swift property mapping
   • code_connect_ready: true

Note: Actual Code Connect registration happens in compliance-checker (Phase 5) AFTER validation passes. This prevents registering non-compliant code as reusable.

Manual Generation Fallback

Load fallback generation rules from: Glob("**/references/swiftui-patterns.md") → Read the "Manual Generation Fallback" section When MCP code generation fails, manually construct the SwiftUI struct from spec properties.

SwiftUI Guidelines

Naming Conventions

• View names: PascalCase with "View" suffix (e.g., CardView, ButtonView)
• File names: Match view name (e.g., CardView.swift)
• Properties: camelCase (e.g., titleText, isEnabled)
• Enums: PascalCase (e.g., ButtonVariant, CardStyle)

Code Quality Standards

• Use MARK comments to organize code sections
• Include DocC documentation comments for public APIs
• Extract complex views into computed properties or subviews
• Keep View body under 10 lines when possible
• Use ViewBuilder for conditional content
• Prefer composition over large conditional blocks

SwiftUI Best Practices

• Use semantic color names from Asset Catalog
• Prefer SF Symbols over custom icons when applicable
• Use .font(.system(.body, design: .rounded)) for consistent typography
• Group related modifiers together
• Use .padding() and .spacing() for consistent layout
• Leverage SwiftUI's automatic layout system

Accessibility Requirements

• All images must have .accessibilityLabel()
• Interactive elements should have .accessibilityHint() when needed
• Use .accessibilityAddTraits() for semantic meaning
• Support Dynamic Type with system fonts
• Ensure color contrast meets WCAG AA (4.5:1)
• Test with VoiceOver enabled
• Use .accessibilityElement(children: .combine) for grouped content

State Management

Choose appropriate property wrappers:

Wrapper	Use Case
@State	View-local state
@Binding	Two-way binding to parent state
@StateObject	View owns the ObservableObject
@ObservedObject	Parent owns the ObservableObject
@EnvironmentObject	Shared state across view hierarchy
@Environment	System-provided values

Output

Update the Implementation Spec at: docs/figma-reports/{file_key}-spec.md

Sections Added to Spec

## Generated Code

| Component | File | Status |
|-----------|------|--------|
| CardView | `Views/Components/CardView.swift` | OK |
| ButtonView | `Views/Components/ButtonView.swift` | OK |
| HeroSection | `Views/Screens/HeroView.swift` | OK |
| NavigationBar | `Views/Components/NavigationBarView.swift` | WARN - Manual adjustments needed |

## Code Generation Summary

- **Framework:** SwiftUI (iOS/macOS)
- **Components generated:** {count}
- **Files created:** {count}
- **Warnings:** {count}
- **Generation timestamp:** {YYYYMMDD-HHmmss}

## Files Created

### Views
- `Views/Components/CardView.swift`
- `Views/Components/ButtonView.swift`
- `Views/Screens/HeroView.swift`

### Extensions (if created)
- `Extensions/Color+Theme.swift`

## Next Agent Input

Ready for: Compliance Checker Agent
Input file: `docs/figma-reports/{file_key}-spec.md`
Components generated: {count}
Framework: SwiftUI (iOS/macOS)

Step 12: Generate Component Tests (Optional)

Reference: Load test-generation.md via Glob("**/references/test-generation.md") for test templates.

If the user has requested tests OR the project has an existing test target:

For each generated View, create {ComponentName}ViewTests.swift:

import XCTest
import SwiftUI
@testable import {ModuleName}

final class {ComponentName}ViewTests: XCTestCase {
    func testViewInitialization() {
        let view = {ComponentName}View()
        XCTAssertNotNil(view)
    }

    func testAccessibilityLabels() {
        let view = {ComponentName}View()
        // Verify accessibility labels are set
        XCTAssertNotNil(view.body)
    }
}

Rules:

1. Only generate tests if user requests OR test target exists in Xcode project
2. Place test files in the project's test target directory
3. Add test files to "Generated Code" table with type "test"

Checkpoint Write

After successfully generating all Views and updating the spec, write a checkpoint file:

mkdir -p .qa

Write to .qa/checkpoint-4-code-generator-swiftui.json:

{
  "phase": 4,
  "agent": "code-generator-swiftui",
  "status": "complete",
  "output_file": "docs/figma-reports/{file_key}-spec.md",
  "components_generated": "{count}",
  "framework": "swiftui",
  "timestamp": "{ISO-8601}"
}

This enables pipeline resume from Phase 5 if the compliance checker fails.