@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3d-patterns.md

@@ -0,0 +1,871 @@
+# PHASE 3D — Pattern Detection + Component Architecture + Complexity
+
+Analyze design data to detect structural patterns, design the Swift API shape, and evaluate complexity.
+This is the most critical analysis phase — its output defines the API that Phase 4 implements.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3A, 3B, 3C, 3E, 3F (all read from pass1/ independently)
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+Read: {artifactPath}/pass1/design_context_response.json
+Read: {artifactPath}/pass1/component_properties.json
+Read: {artifactPath}/pass1/metadata_response.xml
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`, `nodeId`, `fileKey`.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3d
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## GATE 1: PATTERN_DETECTION
+
+Analyze design_context for structural patterns to reduce parameters and improve API.
+
+INPUT: `{artifactPath}/pass1/design_context_response.json`
+INPUT: `{artifactPath}/pass1/component_properties.json`
+
+### 1.1 Repeating Pattern
+
+Sibling elements with same structure, different content.
+
+**Detection:**
+- Count siblings with identical structure (same child types, same nesting depth)
+- If count >= 2 → REPEATING
+- Minor variations (hidden element, optional field) = same pattern
+- Different content (text, image, color) = same pattern
+
+**Action:** Model as array with generic fields.
+
+```swift
+// Before pattern reduction: 12 explicit parameters
+// After: 1 array parameter
+public struct Row: Identifiable {
+    public let id = UUID()
+    public let label: String
+    public let value: String
+    public let detail: String?  // Hidden in some instances
+}
+```
+
+### 1.2 Variant Pattern
+
+Same component with property-based variations.
+
+**Detection from component_properties.json:**
+- Variant properties with enumerated values → Swift enum
+- Boolean properties → Bool parameter
+- Instance swap properties → Sub-component slot
+- Text override properties → String parameter
+
+**Detection from design_context_response.json:**
+- Multiple variants showing visibility differences → Optional properties
+- Multiple variants showing styling differences → Enum-driven styling
+- Multiple variants showing content differences → Configuration-driven
+
+**Action:** Classify each variant property:
+
+| Figma Property Type | Swift Mapping | Example |
+|---------------------|---------------|---------|
+| Variant with 2-5 named values | `enum` | `State: Active/Inactive/Disabled` → `enum State` |
+| Variant with true/false | `Bool` | `HasIcon: true/false` → `showIcon: Bool` |
+| Variant with only visibility toggle | `Bool` or `Optional` | `ShowSubtitle: true/false` → `subtitle: String?` |
+| Instance swap slot | Child view or configuration | `Icon: IconA/IconB` → `icon: IconConfiguration` |
+| Text override | `String` | `Title: "..."` → `title: String` |
+
+### 1.2.1 Boolean Visibility Merge Rule
+
+**When a Figma boolean ONLY toggles visibility of a single content element, merge the boolean into the content property as an optional type. Do NOT generate a separate `Bool` parameter.**
+
+| Figma Pattern | Swift Result | Example |
+|---|---|---|
+| Boolean toggles ONE content element | Optional type, drop the boolean | `Label boolean` + `Text` → `text: String?` (nil = hidden) |
+| Boolean + Instance swap for same element | Optional type, drop the boolean | `Icon boolean` + `Icon swap` → `icon: Image?` (nil = hidden) |
+| Boolean toggles MULTIPLE elements | Keep `Bool`, keep content properties | `ShowHeader boolean` controls title + subtitle + icon → `showHeader: Bool` |
+| Boolean controls behavior (not visibility) | Keep `Bool` | `IsInteractive boolean` → `isInteractive: Bool` |
+
+**Rationale:** In Figma, a boolean + content slot is two properties because Figma has no optionals. In Swift, `Optional` naturally expresses "present or absent." Keeping a separate `showX: Bool` alongside the content creates redundant state — you can have `showLabel: false` but `text: "Hello"`, which is a contradiction the API shouldn't allow.
+
+**Apply this merge consistently** — if the icon boolean was merged into `Image?`, the label boolean must also be merged into `String?`. Same pattern, same treatment.
+
+**Cross-source merges (Figma boolean + LAYER_TEXT):** After Layer Text Classification (§1.5), re-evaluate the merge rule against the combined property set. A Figma boolean may gate a LAYER_TEXT dynamic property — if the boolean toggles visibility of that single text element, merge the boolean into the LAYER_TEXT property as `String?`. The merge rule applies identically regardless of whether the content property originated from a Figma TEXT override or from layer text classification.
+
+**Shared-content exception:** When MULTIPLE booleans independently gate sections that share ONE content source, do NOT merge. Each boolean provides independent per-section visibility that a single optional can't express. Example: `/Money&Mil` and `+Money&Mil` both display `milesAmount` — merging would destroy the ability to show one section but not the other. Keep the booleans; the view short-circuits via `if showX, let content = sharedContent { ... }`.
+
+### 1.3 Extract Variant Examples
+
+From design_context, extract exact sample values for preview rendering:
+- Text content (actual strings used in variants)
+- Image names/references
+- Dimensions (width, height from metadata)
+- Background color (if component has transparent bg that needs container)
+
+### 1.4 Extract Dimensions
+
+From metadata_response.xml:
+- Component width
+- Component height
+- Background fill (transparent, white, colored)
+
+### 1.5 Layer Text Classification
+
+Figma component properties capture variant axes, boolean toggles, text overrides, and instance swaps — but NOT the actual text content rendered inside layers. That layer text often contains **sample/placeholder data** that must become dynamic API parameters.
+
+**Procedure:**
+
+1. Extract every visible text value from `design_context_response.json` (from the generated code / layer content)
+2. Filter out texts already captured as Figma TEXT properties in `component_properties.json` — these are already handled
+3. Filter out texts that have a localization key assigned in `pass2/utility_localization.json` (read if available) — these are static labels managed by the localization system
+4. For each remaining text, classify as STATIC or DYNAMIC using contextual reasoning
+
+**Classification — reason about the component's semantic purpose and each text's role:**
+
+| Question | If YES → |
+|----------|----------|
+| Would different instances of this component show different values here? | DYNAMIC |
+| Is this a data value (price, amount, count, percentage, date, name, currency code)? | DYNAMIC |
+| Does the text only make sense as sample data given the component's domain? | DYNAMIC |
+| Is this a fixed UI label describing what adjacent data represents? | STATIC |
+| Is this a structural/grammatical element (separator, connector, operator like "/" or "+")? | STATIC |
+
+**Key principle:** Reason about what the component IS FOR. A Price component displays prices — price amounts are inherently variable. A "Total Amount" label is inherently fixed — it describes the data, it IS not data. A currency code like "TRY" is variable — the same component shows USD, EUR, GBP in different contexts.
+
+**Edge cases:**
+- Currency codes/symbols (TRY, USD, €) → DYNAMIC: varies by market/context
+- Percentage values (%30, 15%) → DYNAMIC: varies per instance
+- "Step 1 of 3" → "Step" and "of" are STATIC, the numbers are DYNAMIC
+- A text that COULD be dynamic but already has a localization key → STATIC (localization handles it)
+- Structural operators that visually separate data ("+", "/", "·") → STATIC
+
+**For each DYNAMIC text, propose:**
+- Swift property name (camelCase, descriptive of the semantic role — e.g., `currencyCode` not `tryText`)
+- Swift type: `String` (formatting is the caller's responsibility — even for numeric data)
+- Whether required or optional (based on whether the element's parent section is boolean-gated)
+
+**Output:** Include classification in `04_patterns.md` (Layer Text Classification table) and carry DYNAMIC entries into GATE 2 as additional API properties.
+
+### 1.5.1 Price Pattern Detection
+
+When Layer Text Classification identifies a **currency code + numeric amount** pair (e.g., "TRY" + "10.000", or "USD" + "1,250.99"), this is a **price pattern**.
+
+**IMPORTANT:** When a price pattern is detected, read the `/figma-price-integration` skill instructions at `.instructions/figma/figma-price-integration/SKILL.md` for the full integration guide.
+
+**Detection:** Two adjacent DYNAMIC texts where one is a currency code (3-letter ISO 4217 or known symbol) and the other is a numeric amount. Also triggered when a nested `Price` component instance is detected.
+
+**Rules:**
+- Define a **nested `Price` struct** conforming to `PriceRepresentable` — include ONLY the properties this component needs (amount + currency at minimum)
+- The amount parameter type MUST be `Double`, NOT `String` — formatting is handled by `toConfiguration()` → `CurrencyAmountFormatter` at render time
+- Do NOT flatten price fields into the parent Configuration — keep them grouped in the nested `Price` type
+- The view uses `Price(priceModel)` for standalone price display or `CurrencyTextRenderer` for inline attributed text
+- Do NOT hardcode currency placement (left/right) — `CurrencyFormatProvider` determines this from the currency code
+
+**Additional price properties to check for in the design:**
+- Strikethrough/original price → `originalAmount: Double?`
+- Sale badge (e.g., "%30") → `saleBadgeText: String?`
+- Miles section (e.g., "/ 2000 Mil") → `milesValue: Int?`
+- Green/red coloring with +/- prefix → `sign: PriceSign?`
+
+**Architecture output:** When a price pattern is detected, the property coverage should list:
+- `price: ComponentName.Price` (PRICE_PATTERN, IMPLEMENT) — nested `PriceRepresentable` conformance
+
+### 1.5.1b Inline Price in Attributed Text
+
+When a **price pattern** (§1.5.1) appears **inside a text element** alongside static surrounding text (e.g., "TRY 10.000 dan başlayan fiyatlarla"), this is an **inline price attributed text pattern**.
+
+**Detection:** A DYNAMIC price (currency + amount) adjacent to STATIC text within the same visual text block, where the price portion has different typography (bold, larger) than the surrounding text.
+
+**This is NOT a standalone Price view.** It is a formatted `AttributedString` rendered inside a `Text()` view.
+
+**Rules:**
+- The surrounding text → localization format key with `%@` placeholder (e.g., `"%@ dan başlayan fiyatlarla"`)
+- The price portion → `PriceRepresentable` model, rendered via `price.attributedString(style:)` 
+- Compose with `AttributedString.format()` from `UIExtensions`:
+  ```swift
+  var template = AttributedString(localized: .Component.startingFromPrice)
+  template.font = .bodyRegular
+  template.foregroundColor = .Text.textGrey
+  
+  let result = template.format(
+      price.attributedString(style: CurrencyTextStyle(
+          currencyFont: .smallRegular,
+          amountFont: .smallBold,
+          color: .Text.textPrimary
+      ))
+  )
+  Text(result)
+  ```
+
+**Architecture output:** When an inline price attributed text pattern is detected, the property coverage should list:
+- `price: ComponentName.Price` (PRICE_PATTERN, IMPLEMENT) — nested `PriceRepresentable` conformance
+- Note in patterns output: "Inline price in attributed text — use `price.attributedString(style:)` with `AttributedString.format()`"
+
+**This pattern must be explicitly confirmed during analysis.** If a price appears near text, ask: is this a standalone `Price` view + separate `Text`, or a single attributed string combining both? Check the Figma layer structure — if the price and surrounding text are in the same text layer with different font styles, it's inline attributed text.
+
+### 1.5.1a Attributed Text Pattern (Multi-Font Text)
+
+**Detection during Layer Text Classification:** When examining text elements in `design_context_response.json`, look for text where the generated code has multiple sibling `<span>` tags with different `font-family` or `font-weight` classes. Each distinct style run within a single text element indicates a multi-font attributed text pattern.
+
+**Classify each style run independently** using the same DYNAMIC/STATIC rules from §1.5 — a highlighted portion may be a dynamic prop (varies per instance) OR a static localization key (fixed but styled differently).
+
+**Rules:**
+- The surrounding text → localization format key with `%@` placeholders
+- Each differently-styled portion → classify as DYNAMIC (`String` prop) or STATIC (its own localization key)
+- Render using `AttributedString.format()` from `UIExtensions` — template gets base styling, each `%@` argument gets its own styling
+
+### 1.5.3 Form Pattern Detection
+
+When Sub-Component analysis identifies embedded instances of form-capable design-system components — **Selectbox, Checkbox, CheckboxButton, Radio, RadioButton, TextboxTextarea, DatepickerSchedule** — this is a **form pattern**.
+
+**IMPORTANT:** When a form pattern is detected, read the `/figma-form-integration` skill instructions at `.instructions/figma/figma-form-integration/SKILL.md` for the full integration guide.
+
+**Detection (count form-capable instances):**
+- 0 → no form pattern; skip.
+- 1 → **atomic form**: component exposes ONE `*FormField` directly on Configuration / View init; no `FormSection` wrapper.
+- 2+ → **composite form**: nested `Section: FormSection` class declared in an extension on the component namespace, owned via Configuration.
+
+**Rules:**
+- Every form input MUST be modeled as a `*FormField` subclass — no `Binding<Value>`, no `@State` values, no ad-hoc `isChecked: Bool` / `selectedOption` properties.
+- The caller (scene view-model) constructs fields and rules. The component is headless — it never instantiates fields and never calls `validate()`.
+- Static copy (labels, placeholders, helper text, toggle captions) lives in Configuration; fields carry value+state+rules only.
+- Non-form actions (e.g. "Sil", "Edit", "Detaylar") stay as paired closures on the View — they are NOT fields and NOT Configuration values.
+
+**Figma → FormField mapping:**
+
+| Figma sub-component | FormField subclass |
+|---|---|
+| Selectbox (single value) | `PickerFormField<Option>` |
+| Selectbox (multi select) | `MultiPickerFormField<Option>` |
+| Checkbox / CheckboxButton | `CheckboxFormField` |
+| Checkbox group | `CheckboxGroupFormField<Option>` |
+| Radio / RadioButton group | `RadioFormField<Option>` |
+| TextboxTextarea | `TextFormField` |
+| DatepickerSchedule (single date) | `DatePickerFormField` |
+| DatepickerSchedule (range) | `DateRangePickerFormField` |
+| Visual Switch (Bool) | `CheckboxFormField` (atomic view decides Switch rendering) |
+
+**Architecture output (composite, 2+ fields):**
+
+```swift
+extension ComponentName {
+    @FormSection
+    @Observable
+    public final class Section: FormSection {
+        public let {field1}: {FormFieldType1}
+        public let {field2}: {FormFieldType2}
+        // ... only the fields this component renders
+        public init(...) { ... }
+    }
+}
+```
+
+Configuration then carries `public let section: ComponentName.Section` plus static copy.
+
+**Architecture output (atomic, 1 field):** Configuration (or View init) carries the FormField directly, e.g. `public let terms: CheckboxFormField`.
+
+### 1.5.2 Image Asset Classification
+
+Figma designs contain images that are either **static assets** (bundled in the app) or **dynamic content** (loaded remotely at runtime). Classify each image in the design context.
+
+**Classification — reason about what the image represents:**
+
+| Signal | Classification |
+|--------|---------------|
+| Photograph of real place, person, food, destination | DYNAMIC (remote) |
+| Large raster image filling a container (hero, banner, card cover) | DYNAMIC (remote) |
+| Layer named "image", "photo", "hero", "banner", "thumbnail", "cover" | DYNAMIC (remote) |
+| Content that varies per user/context (profile photo, campaign, product) | DYNAMIC (remote) |
+| Small vector icon (monochrome, brand colors, <48px) | STATIC (bundled) |
+| Logo (airline, payment provider, partner) | STATIC (bundled) |
+| Illustration or decorative artwork (brand-specific) | STATIC (bundled) |
+| Figma layer is a component instance swap with icon variants | STATIC (bundled) |
+
+**For DYNAMIC images:**
+- Swift type: `URL` or `String` (the remote image URL)
+- The view MUST use the remote image component from `CoreUI` (Kingfisher-backed) for async loading, caching, and placeholder handling
+- Do NOT download the Figma placeholder image — it's sample data, not a real asset
+- Add a `placeholder` parameter or use a default placeholder view for loading state
+
+**For STATIC images:**
+- Download the asset from Figma (SVG or PNG)
+- Add to the uncategorized images directory in `{project.slug}-common`: `Shared/UIAssets/Images/`
+- Run `swift package plugin --allow-writing-to-package-directory generate-ui-assets` to regenerate asset extensions
+- Reference via the generated `Image.` accessor
+
+**Architecture output:** When a dynamic image is detected, the property coverage should list:
+- `{imageName}URL: URL` (LAYER_IMAGE, IMPLEMENT) — or `String` if the URL comes as a string from the API
+
+### 1.6 Write `{artifactPath}/pass3/04_patterns.md`
+
+```markdown
+# Pattern Detection
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass1/component_properties.json
+
+## Repeating Patterns
+
+| Pattern | Count | Fields | Parameter Reduction |
+|---------|-------|--------|---------------------|
+| Row items | 4 | label, value, detail? | 12 → 2 params (1 array + 1 struct) |
+
+OR: None detected.
+
+## Variant Properties
+
+| Figma Property | Type | Values | Swift Mapping |
+|----------------|------|--------|---------------|
+| State | Variant | Active, Inactive, Disabled | `enum State` |
+| HasIcon | Boolean | true, false | `showIcon: Bool` |
+| ShowSubtitle | Boolean | true, false | `subtitle: String?` |
+
+## Variant Examples (for Preview)
+
+| Variant | Sample Values |
+|---------|---------------|
+| Default | title: "Flight Details", state: .active |
+| Disabled | title: "Unavailable", state: .disabled |
+
+## Dimensions
+
+| Property | Value |
+|----------|-------|
+| Width | {width} |
+| Height | {height} |
+| Background | {fill color or transparent} |
+| Container Needed | {Yes (transparent bg) / No} |
+
+## Layer Text Classification
+
+| Layer Text | Semantic Role | Classification | Swift Property | Notes |
+|------------|--------------|----------------|----------------|-------|
+| "{text}" | {role} | DYNAMIC / STATIC | `{propName}: String` / — | {rationale} |
+
+OR: All layer text already captured as Figma TEXT properties or localization keys — no additional dynamic parameters.
+
+## Image Asset Classification
+
+| Image | Layer Name | Classification | Swift Property | Notes |
+|-------|-----------|----------------|----------------|-------|
+| {description} | {layerName} | DYNAMIC / STATIC | `{propName}: URL` / bundled | {rationale} |
+
+OR: No images detected in component.
+```
+
+---
+
+## GATE 2: COMPONENT_ARCHITECTURE
+
+**This is the core analysis gate.** Using pattern data from GATE 1, determine the complete Swift API shape.
+
+INPUT: GATE 1 output (in memory — just computed)
+INPUT: `{artifactPath}/pass1/design_context_response.json`
+INPUT: `{artifactPath}/pass1/component_properties.json`
+INPUT: `{artifactPath}/pass3/04c_variant_config_analysis.json` (from Phase 3H)
+
+### 2.0 Consume Phase 3H Classifications
+
+Read `04c_variant_config_analysis.json`. This contains typed recommendations for every boolean property. **Do NOT re-classify** — use 3H output directly.
+
+For entries with `"deferredTo": "3D"` (UNCLASSIFIED booleans): analyze using `design_context_response.json` HTML structure to determine if the boolean is a section toggle (controls multiple children → `Bool`), decorative leaf (`Bool`), or behavioral bool (`Bool`).
+
+Update 3H entries with resolved types and include in the architecture output.
+
+### 2.1 List Inference
+
+Analyze child elements to determine if they form lists:
+
+**Homogeneous list detection:**
+- Multiple children with identical structure but different content
+- Variant property controls count (e.g., "Items: 1/2/3")
+- Same child component type repeated
+
+→ Model as `[ItemType]` array
+
+```swift
+// Homogeneous: all items are the same struct
+public struct PassengerRow: Identifiable {
+    public let id = UUID()
+    public let name: String
+    public let seatNumber: String
+}
+
+// Usage in component
+public let passengers: [PassengerRow]
+```
+
+**Heterogeneous list detection:**
+- Multiple children with DIFFERENT structures in the same container
+- Instance swap property cycles through different component types
+- Each slot has fundamentally different content (not just styling)
+
+→ Model as enum with associated values (CONCRETE types, NOT protocols)
+
+```swift
+// Heterogeneous: different item types in same list
+public enum CardSection {
+    case header(title: String, subtitle: String?)
+    case flightInfo(departure: String, arrival: String, duration: String)
+    case priceBreakdown(rows: [PriceRow])
+    case action(buttonTitle: String)
+}
+
+// Usage in component
+public let sections: [CardSection]
+```
+
+**NOT a list (false positive guards):**
+- Different children serve structurally different roles (header vs body vs footer)
+- Children are at different hierarchy levels
+- Only 1 instance exists across all variants
+
+→ Model as separate properties
+
+### 2.2 Sub-Component Integration
+
+**This section consumes Phase 3H output.** Do NOT re-detect sub-components — 3H has already classified them.
+
+Phase 3H provides `dynamicProps` and `staticProps` for each sub-component entry. Only dynamic props are exposed to the caller. Static props are hardcoded internally by the parent View (Phase 4B).
+
+**For each `KNOWN_SUBCOMPONENT` entry:**
+
+Use the `swiftType` from 3H directly — it's already resolved based on dynamic prop count:
+
+| Dynamic Props | Result |
+|---|---|
+| 0 | Boolean presence only |
+| 1 | Unwrapped to prop type (e.g., `String?`) |
+| 2+ | Mini config struct (e.g., `PriceConfiguration?`) — define it in the parent's Configuration |
+
+```swift
+// 1 dynamic prop (title only): unwrapped to String?
+public let toggleLinkTitle: String?  // nil = hidden
+
+// 2+ dynamic props: mini config (only dynamic props, no styling)
+public struct PriceConfiguration: Sendable {
+    public let label: String
+    public let currency: String
+    public let wholeAmount: String
+    public let decimalAmount: String
+    // textStyle is STATIC — not exposed, hardcoded in View body
+}
+public let priceConfiguration: PriceConfiguration?  // nil = hidden
+```
+
+**For each `PAIRED_ACTION_SUBCOMPONENT` entry:**
+
+Same prop filtering as KNOWN_SUBCOMPONENT, plus a paired closure. The data goes in Configuration, the closure is a View dependency. Phase 4B generates a **paired modifier** that binds them at the call site:
+
+```swift
+// 1 dynamic prop + action → title in config, closure in View, paired modifier
+// Config: secondaryButtonTitle: String?
+// View: secondaryAction: (() -> Void)?
+// Modifier: .secondaryButton("Details") { action() }
+
+// 2+ dynamic props + action → mini config in config, closure in View, paired modifier
+// Config: actionLinkConfiguration: ActionLinkConfiguration?
+// View: actionLinkAction: (() -> Void)?
+// Modifier: .actionLink(.init(text: "Download", icon: .download)) { action() }
+
+// 0 dynamic props + action → nothing in config, closure in View, closure-only modifier
+// View: dismissAction: (() -> Void)?
+// Modifier: .dismissButton { action() }
+```
+
+**For each `ICON_BOOLEAN_GATED` entry:**
+- Use the `swiftType` from 3H (`Image?` or `Optional3<Image>`)
+- Use the `swiftName` from 3H for naming
+
+**For `UNCLASSIFIED` entries resolved in §2.0:**
+- Integrate the resolved type (`Bool` for section toggles, etc.)
+
+### 2.3 Property Classification
+
+For each property identified in GATE 1, classify into its final Swift form:
+
+| Classification | When | Swift Pattern |
+|----------------|------|---------------|
+| Required parameter | Always visible, component meaningless without it | `init(title: String)` |
+| Optional parameter | Sometimes hidden/absent | `subtitle: String? = nil` — chain modifier |
+| Merged optional | Boolean toggles ONE content element | `text: String?` — boolean dropped, nil = hidden |
+| Enum | Variant with named values | `enum State { case active, inactive }` |
+| Bool toggle | Binary behavior OR toggles MULTIPLE elements | `isInteractive: Bool = true` |
+| Array | Repeated homogeneous children | `items: [ItemRow]` |
+| Enum array | Repeated heterogeneous children | `sections: [CardSection]` |
+| Mini config (display) | Boolean-gated sub-component, 2+ dynamic props, no action | `priceConfiguration: PriceConfiguration?` — chain modifier |
+| Mini config (paired) | Boolean-gated sub-component, 2+ dynamic props + action | Paired modifier: `.actionLink(config) { action }` |
+| Paired single prop | Boolean-gated sub-component, 1 dynamic prop + action | Paired modifier: `.secondaryButton(title) { action }` |
+| Paired closure-only | Boolean-gated sub-component, 0 dynamic props + action | Paired modifier: `.dismissButton { action }` |
+| Closure | Interactive action (always present, not boolean-gated) | `onTap: (() -> Void)?` |
+| Layer text (dynamic) | Sample/placeholder data in Figma layers (from §1.5 classification) | `{propName}: String` |
+
+### 2.3.1 Coexistent Property Rule
+
+When two properties are semantically meaningless without each other, they MUST be paired at the call site. Do NOT allow them to be set independently.
+
+**Detection:** Ask "does prop A without prop B create a nonsensical state?" If yes → coexistent pair.
+
+**Common patterns:**
+- title + action (button without action or action without button = nonsensical)
+- icon + iconAction (tappable icon without handler = broken)
+- label + labelAccessory (accessory without context = orphaned)
+
+**Resolution:** Coexistent pairs are expressed as **paired modifiers** on the View. The data prop goes in Configuration (for nil = hidden), the closure stays as a View dependency. The modifier sets both atomically.
+
+This is NOT limited to sub-components — any two semantically bound props follow this rule.
+
+### 2.4 Configuration Hierarchy
+
+Determine if properties need grouping into sub-configurations:
+
+**Flat init (no sub-config needed):**
+- Total properties ≤ 5
+- No logical grouping exists
+- All properties are at the same conceptual level
+
+```swift
+public init(
+    title: String,
+    subtitle: String?,
+    state: State,
+    showIcon: Bool
+)
+```
+
+**Sub-configuration needed when:**
+- A group of 3+ properties always appear together
+- A group represents a conceptual sub-entity (price, badge, action)
+- A group maps to a distinct visual region of the component
+
+```swift
+// Group "price" properties into sub-configuration
+public struct PriceConfiguration {
+    public let amount: String
+    public let currency: String
+    public let originalAmount: String?  // Strikethrough price
+}
+
+public init(
+    title: String,
+    price: PriceConfiguration,
+    state: State
+)
+```
+
+**Rules:**
+- Configuration models are CONCRETE structs, not protocols
+- Sub-configurations are also concrete structs
+- Use `public let` for immutable data, `public var` only if component mutates it
+- All configurations must be `Sendable`
+- Nested configurations use composition, not inheritance
+
+### 2.5 Variant-to-Enum Mapping
+
+For each variant property that maps to an enum:
+
+```swift
+// Figma variant: "State" with values "Active", "Inactive", "Disabled", "Error", "Success"
+public enum State: String, CaseIterable, Sendable {
+    case active
+    case inactive
+    case disabled
+    case error
+    case success
+}
+```
+
+**Naming rules:**
+- Enum name = Figma property name in PascalCase
+- Case names = Figma values in camelCase
+- If Figma value is "Default" → use `.standard` (avoid Swift keyword)
+- If enum is purely visual (only affects colors/styling) → internal to component, not in public API
+- If enum affects content/structure → public, exposed in init
+
+### 2.6 Final API Design
+
+Compile the complete public API:
+
+```swift
+// FINAL API DESIGN for {componentName}
+
+// Enums
+public enum {EnumName}: String, CaseIterable, Sendable {
+    case {value1}
+    case {value2}
+}
+
+// Sub-configurations (if any)
+public struct {SubConfig}: Sendable {
+    public let {property}: {Type}
+}
+
+// Data models (if list patterns detected)
+public struct {ItemType}: Identifiable, Sendable {
+    public let id = UUID()
+    public let {field}: {Type}
+}
+
+// Main init
+public init(
+    {param1}: {Type},
+    {param2}: {Type} = {default},
+    {param3}: {Type}? = nil
+)
+```
+
+### 2.7 Write `{artifactPath}/pass3/04b_component_architecture.md`
+
+```markdown
+# Component Architecture
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass1/component_properties.json
+
+## List Inference
+
+| Element Group | Type | Count Across Variants | Conclusion |
+|---------------|------|----------------------|------------|
+| Passenger rows | Homogeneous | 1-3 | `[PassengerRow]` array |
+| Card sections | Heterogeneous | 3-5 | `[CardSection]` enum array |
+
+OR: No list patterns detected.
+
+## Sub-Components
+
+| Element | Scope | Configuration |
+|---------|-------|---------------|
+| Badge | Optional sub-component | `BadgeConfiguration` struct |
+| Price | Always present group | `PriceConfiguration` struct |
+
+OR: No sub-components detected. All properties are flat.
+
+## Property Classification
+
+| Property | Classification | Swift Type | Default |
+|----------|---------------|------------|---------|
+| title | Required | `String` | — |
+| subtitle | Optional | `String?` | `nil` |
+| state | Enum | `State` | — |
+| showIcon | Bool toggle | `Bool` | `true` |
+| passengers | Array | `[PassengerRow]` | — |
+| onTap | Closure | `(() -> Void)?` | `nil` |
+
+## Enum Definitions
+
+### {EnumName}
+
+| Figma Value | Swift Case | Visual Effect |
+|-------------|------------|---------------|
+| Active | `.active` | Green border, checkmark |
+| Inactive | `.inactive` | Grey border, no icon |
+| Disabled | `.disabled` | Light grey, reduced opacity |
+
+## Configuration Hierarchy
+
+{Flat / Grouped}
+
+### Sub-Configurations (if grouped)
+
+#### {SubConfigName}
+
+| Property | Type | Required |
+|----------|------|----------|
+| amount | `String` | Yes |
+| currency | `String` | Yes |
+| originalAmount | `String?` | No |
+
+## Final API Design
+
+```swift
+{Complete API from 2.6}
+```
+
+## Preview Data
+
+```swift
+// Default variant
+static var preview: {componentName} {
+    .init(
+        title: "{sample}",
+        state: .active
+    )
+}
+```
+```
+
+### 2.8 Write `{artifactPath}/pass3/04b_component_architecture.json`
+
+Alongside the markdown, emit a structured JSON so Phase 3G (Property Coverage) can verify coverage deterministically without AI interpretation.
+
+```json
+{
+  "componentName": "{componentName}",
+  "generated": "{ISO_DATE}",
+  "properties": [
+    {
+      "figmaKey": "{exact key from componentPropertyDefinitions, e.g. State or Text#6893:1}",
+      "name": "{display name}",
+      "type": "{VARIANT|BOOLEAN|TEXT|INSTANCE_SWAP|LAYER_TEXT}",
+      "status": "{IMPLEMENT|SKIP}",
+      "swiftType": "{enum State | String? | Image? | Bool | ...}",
+      "reason": "{only for SKIP — mandatory, e.g. 'Boolean merged into icon: Image? per Boolean Visibility Merge Rule'}"
+    }
+  ],
+  "enums": [
+    {
+      "name": "{EnumName}",
+      "cases": ["{case1}", "{case2}"]
+    }
+  ],
+  "complexity": "{SIMPLE|COMPLEX}",
+  "propertyCount": 0
+}
+```
+
+**Rules:**
+- Every key from `componentPropertyDefinitions` in `component_properties.json` MUST appear in `properties`
+- DYNAMIC entries from Layer Text Classification (§1.5) MUST also appear in `properties` with `"type": "LAYER_TEXT"` and `"figmaKey": null`
+- IMPLEMENT properties MUST have `swiftType`
+- SKIP properties MUST have `reason`
+- `propertyCount` = count of IMPLEMENT properties (used by GATE 3 complexity check)
+
+---
+
+## GATE 3: COMPLEXITY_EVALUATION
+
+### 3.1 Count Properties
+
+Count total configurable properties from the FINAL API DESIGN (after pattern reduction and architecture decisions):
+- Init parameters
+- Enum cases (count the enum itself as 1 property, not each case)
+- Sub-configuration structs (count as 1 property each)
+
+### 3.2 Determine Complexity
+
+```
+PROPERTY_COUNT = <COUNT from final API, not raw Figma properties>
+SIMPLE = PROPERTY_COUNT <= 3
+COMPLEX = PROPERTY_COUNT > 3
+```
+
+| Result | Configuration File | Workflow |
+|--------|-------------------|----------|
+| SIMPLE | No | Direct init parameters |
+| COMPLEX | Yes | Configuration struct wraps all init params |
+
+For COMPLEX components, the Configuration struct pattern:
+
+```swift
+// Configuration struct holds all init params
+public struct {componentName}Configuration: Sendable {
+    public let {param1}: {Type}
+    public let {param2}: {Type}
+    // ...
+
+    public init(
+        {param1}: {Type},
+        {param2}: {Type} = {default}
+    ) {
+        self.{param1} = {param1}
+        self.{param2} = {param2}
+    }
+}
+
+// Component accepts configuration
+public struct {componentName}: View {
+    private let configuration: {componentName}Configuration
+
+    public init(configuration: {componentName}Configuration) {
+        self.configuration = configuration
+    }
+}
+```
+
+### 3.3 Write `{artifactPath}/pass3/05_complexity.md`
+
+```markdown
+# Complexity Evaluation
+
+Component: {componentName}
+Generated: {ISO_DATE}
+
+## Property Count
+
+| Source | Count | Details |
+|--------|-------|---------|
+| Raw Figma properties | {RAW_COUNT} | Before pattern reduction |
+| After pattern reduction | {REDUCED_COUNT} | Arrays, enums collapsed |
+| Final API properties | {FINAL_COUNT} | From component architecture |
+
+## Result
+
+| Field | Value |
+|-------|-------|
+| Complexity | {SIMPLE / COMPLEX} |
+| Configuration struct | {Required / Not required} |
+| Property count | {FINAL_COUNT} |
+
+## Rationale
+
+{Brief explanation: e.g., "5 init parameters including 1 enum, 1 optional, and 1 array. Configuration struct recommended for clean API."}
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+Before marking complete, verify:
+
+```
+[ ] design_context_response.json fully analyzed for patterns
+[ ] component_properties.json fully analyzed for variant types
+[ ] All repeating patterns identified and modeled as arrays
+[ ] All variant properties classified (enum, bool, optional, array)
+[ ] Layer text classification performed — all sample/placeholder data identified as DYNAMIC API parameters
+[ ] Image asset classification performed — stock photos as DYNAMIC (remote URL), icons/logos as STATIC (bundled)
+[ ] List inference performed — homogeneous vs heterogeneous determined
+[ ] Sub-component detection performed — configurations created where needed
+[ ] Configuration hierarchy decided — flat vs grouped
+[ ] All enums defined with correct case names
+[ ] Final API design is complete and compilable
+[ ] NO protocols used — all types are concrete structs/enums
+[ ] All configurations are Sendable
+[ ] Complexity evaluated using FINAL property count (not raw Figma count)
+[ ] 04_patterns.md written to pass3/
+[ ] 04b_component_architecture.md written to pass3/
+[ ] 04b_component_architecture.json written to pass3/ (structured, for 3G script)
+[ ] 05_complexity.md written to pass3/
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3d
+GATES_PASSED: [PRE_CHECK, PATTERN_DETECTION, COMPONENT_ARCHITECTURE, COMPLEXITY_EVALUATION]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/04_patterns.md
+  - {artifactPath}/pass3/04b_component_architecture.md
+  - {artifactPath}/pass3/04b_component_architecture.json
+  - {artifactPath}/pass3/05_complexity.md
+SUMMARY: Patterns: {REPEATING_COUNT} repeating, {VARIANT_COUNT} variant properties. Architecture: {ENUM_COUNT} enums, {SUBCONFIG_COUNT} sub-configurations, {LIST_COUNT} lists. Complexity: {SIMPLE/COMPLEX} ({FINAL_COUNT} properties).
+```