@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-3h-variant-config.md

@@ -0,0 +1,333 @@
+# PHASE 3H — Variant Property Configuration Analysis
+
+Analyze how Figma variant/state properties (booleans, instance swaps) map to Swift configuration types.
+Detects when Figma's boolean-only exposure is insufficient for a sub-component's actual configuration needs.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 3A, 3B, 3C, 3E, 3F (all read from pass1/ independently)
+MUST COMPLETE BEFORE: Phase 3D (which consumes this output)
+
+---
+
+## PRE-CHECK
+
+```
+Read: {artifactPath}/pass1/component_properties.json
+Read: {artifactPath}/pass1/code_connect_map_response.json
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+```
+
+Extract: `componentName`, `artifactPath`.
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-3h
+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: INDEX_CODE_CONNECT_MAP
+
+Parse `code_connect_map_response.json` and classify every entry:
+
+| Entry Pattern | Classification |
+|---|---|
+| `label` = our platform (SwiftUI) AND no `componentName` AND `snippet` matches `Image.xxx` | `ICON` |
+| `label` = our platform AND `componentName` present AND `source` URL present | `SUBCOMPONENT` |
+| `label` ≠ our platform (e.g., Compose, React) | `CROSS_PLATFORM` — ignore |
+
+Build a lookup: `{ nodeId → { classification, componentName?, source?, snippet } }`
+
+If code_connect_map is empty or missing → set `codeConnectAvailable = false`. Continue — all booleans will be `UNCLASSIFIED` and 3D handles them.
+
+---
+
+## GATE 2: CLASSIFY_BOOLEAN_PROPERTIES
+
+For each entry in `booleanProperties` from `component_properties.json`, walk this decision tree:
+
+### Step 1: Check for paired Instance Swap
+
+Does a `nestedComponents` entry share the same base name?
+- Boolean `"Left Icon"` ↔ nestedComponent `"↪ Left Icon#965:54"` → **paired**
+
+If paired with INSTANCE_SWAP → go to Step 2.
+If not paired → go to Step 3.
+
+### Step 2: Resolve paired Bool + InstanceSwap
+
+Look up the instance swap's nodes in the code_connect_map index (GATE 1):
+
+| code_connect_map result | Classification | Notes |
+|---|---|---|
+| Found as `ICON` (`Image.xxx` snippet) | `ICON_BOOLEAN_GATED` | Swift type resolved in GATE 3 |
+| Found as `SUBCOMPONENT` (`componentName` + `source`) | `KNOWN_SUBCOMPONENT` | Swift type resolved in GATE 3 |
+| Not found in code_connect_map | `UNMAPPED_SUBCOMPONENT` | → **HALT** |
+
+**Node matching**: The instance swap's `nodeId` from `nestedComponents` is the definition ID. Variant-specific instance IDs appear in code_connect_map. Match by searching for code_connect_map entries whose `data-name` (from surrounding context) corresponds to the instance swap name. If ambiguous, check ALL code_connect_map ICON/SUBCOMPONENT entries — group by snippet pattern and correlate with the instance swap slot.
+
+### Step 3: Resolve unpaired Boolean
+
+**3a. Check for paired Text Slot:**
+Does a `textSlots` entry share the same base name?
+- Boolean `"Paragraph"` ↔ textSlot `"↪ Paragraph#965:56"` → **paired**
+
+If paired → classify as `CONTENT_LEAF`.
+
+**3b. Check code_connect_map for sub-component:**
+Are there code_connect_map entries classified as `SUBCOMPONENT` whose `componentName` matches the boolean's semantic meaning?
+- Boolean `"Text Link"` → code_connect_map has entries with `componentName: "Textlink"` → **match**
+
+If matched → classify as `KNOWN_SUBCOMPONENT`.
+
+**3c. Otherwise:**
+Classify as `UNCLASSIFIED`. Phase 3D will determine if this is a section toggle, decorative leaf, or behavioral bool using design_context HTML structure analysis.
+
+### Step 4: Check for Repeating Patterns
+
+Booleans that form a numbered series (e.g., `"List Item 1"`, `"List Item 2"`, ..., `"List Item 5"`) paired with corresponding text slots → classify all as `REPEATING_PATTERN_MEMBER`.
+
+Their container boolean (e.g., `"List"`) → classify as `REPEATING_PATTERN_CONTAINER`.
+
+### Step 5: Check for Paired Action Sub-Component
+
+For each `KNOWN_SUBCOMPONENT` classified in Step 2 or 3b, determine if the sub-component semantically requires a user action (closure):
+
+**Signals for action pairing:**
+- Sub-component is a button (TurkishButton, IconButton, TextLink, etc.)
+- Sub-component is an interactive element (link, toggle, tap target)
+- The boolean-gated element in Figma represents a tappable area
+
+**Signals against action pairing:**
+- Sub-component is display-only (badge, label, price section, indicator)
+- Sub-component shows information without user interaction
+
+If action pairing detected → reclassify as `PAIRED_ACTION_SUBCOMPONENT`.
+
+This classification tells downstream phases that:
+1. The sub-component needs both data (config props) and a closure (action)
+2. These must be paired at the call site — one without the other is nonsensical
+3. A paired modifier pattern is required (not separate config prop + closure)
+
+---
+
+## GATE 3: RESOLVE_SWIFT_TYPES
+
+For each classified boolean, determine the Swift type:
+
+### ICON_BOOLEAN_GATED
+
+Analyze whether the icon has a **computed default** that varies by component state:
+
+- Read the icon `snippet` values from code_connect_map entries across different variant instances
+- If ALL entries show the same `Image.xxx` value BUT the icon semantically correlates with a variant enum (e.g., `Image.warningCircle` correlates with `Feedback.warning`), check if the component logically needs different icons per variant state
+- If the icon default is **dynamic** (varies by variant state or is computed internally) → `Optional3<Image>`
+  - `.default` = component computes the icon from its own state
+  - `.none` = explicitly hidden
+  - `.some(Image)` = custom override
+- If the icon default is **static** (always the same, no variant dependency) → `Image?`
+  - `nil` = hidden
+  - `Image(...)` = shown
+
+**Signals for dynamic default:**
+- Icon name contains the variant value (e.g., `warningCircle` + variant `Feedback` has `Warning`)
+- Component has multiple feedback/state/type variants that typically drive icon changes
+- The old/discarded implementation (if mend mode) used a three-state or computed icon pattern
+
+**Signals for static default:**
+- Icon is generic (e.g., `caretDown`, `chevronRight`) with no variant correlation
+- Icon appears in ALL variants identically with no semantic relationship to variant values
+
+**When uncertain:** Prefer `Optional3<Image>` — it's strictly more expressive than `Image?` and never wrong. The consumer can always use `.default` instead of being forced to know the internal default.
+
+### KNOWN_SUBCOMPONENT
+
+1. Extract `componentName` and `source` from code_connect_map
+2. Check if `{ComponentName}Configuration.swift` exists in the codebase:
+   ```
+   Glob: Sources/UIComponents/**/{ComponentName}Configuration.swift
+   ```
+3. **Filter sub-component props — static vs dynamic:**
+
+   Read the sub-component's Configuration (or init for SIMPLE). For each property, determine:
+   - **Dynamic**: Content props that the caller controls (title, text, label, description, icon when context-dependent). These carry meaning unique to each usage.
+   - **Static**: Styling/layout props that the parent component dictates (style, size, colorTheme, iconPosition). These are internal design decisions — same for every instance of this sub-component within the parent.
+
+   **Rule:** If a prop's value is fixed by the parent's design (e.g., secondary button always uses `style: .ghost, size: .default`) → static. If a prop carries caller-specific content → dynamic.
+
+4. Resolve based on dynamic prop count:
+
+| Dynamic Props | Swift Type | Notes |
+|---|---|---|
+| 0 | `Bool?` or just the boolean presence | Sub-component is fully static, parent hardcodes everything |
+| 1 | Unwrap to the prop type (e.g., `String?`) | Single dynamic prop, nil = hidden |
+| 2+ | Mini config struct (e.g., `PriceConfiguration?`) | Multiple dynamic props grouped, nil = hidden |
+| Component doesn't exist | **HALT** | Sub-component must be implemented first |
+
+**Mini config structs** contain ONLY the dynamic props — static props are NOT exposed:
+```swift
+// TurkishButton has 6 props, but in BottomActions context only title is dynamic:
+// → secondaryButtonTitle: String?  (not TurkishButtonConfiguration?)
+
+// PriceSection has 5 props, 4 are dynamic, 1 (textStyle) is static:
+// → priceConfiguration: PriceConfiguration?
+// struct PriceConfiguration { label, currency, wholeAmount, decimalAmount }
+```
+
+Record the static props and their fixed values in the artifact — Phase 4B needs them to hardcode internally.
+
+### PAIRED_ACTION_SUBCOMPONENT
+
+Same prop filtering as KNOWN_SUBCOMPONENT (steps 1-4 above), plus:
+
+5. Record that a closure dependency is required alongside the config/prop
+6. The `swiftType` follows the same 0/1/2+ dynamic prop rules
+7. Add `pairedClosure` field to the artifact entry specifying the closure type (e.g., `() -> Void`)
+
+The pairing is expressed in Phase 4 as a **paired modifier** that binds data + closure at the call site:
+```swift
+// 1 dynamic prop + action:
+func secondaryButton(_ title: String, action: @escaping () -> Void) -> Self
+
+// 2+ dynamic props + action:
+func actionLink(_ config: ActionLinkConfiguration, action: @escaping () -> Void) -> Self
+
+// 0 dynamic props + action (fully static sub-component, just needs closure):
+func dismissButton(action: @escaping () -> Void) -> Self
+```
+
+### CONTENT_LEAF
+
+Swift type: `String?` — `nil` = hidden. The boolean is dropped (merged into the optional).
+
+### REPEATING_PATTERN_MEMBER / REPEATING_PATTERN_CONTAINER
+
+Swift type: merged into array (e.g., `[String]`, `[ItemRow]`). Empty array = hidden.
+
+### UNMAPPED_SUBCOMPONENT
+
+Swift type: **cannot determine**.
+
+```
+STATUS: HALT
+PHASE: phase-3h
+GATE: RESOLVE_SWIFT_TYPES
+REASON: Boolean "{boolName}" gates an unmapped sub-component with no code_connect_map entry.
+Figma key: {figmaKey}
+USER_ACTION_REQUIRED: The sub-component must be implemented and have Code Connect published first.
+  Then re-run Phase 1 (to get updated code_connect_map) → re-run Phase 3H.
+```
+
+### UNCLASSIFIED
+
+Swift type: deferred to Phase 3D. Output `"swiftType": null, "deferredTo": "3D"`.
+
+---
+
+## GATE 4: WRITE_ARTIFACTS
+
+### `{artifactPath}/pass3/04c_variant_config_analysis.json`
+
+```json
+{
+  "componentName": "{componentName}",
+  "generated": "{ISO_DATE}",
+  "codeConnectAvailable": true,
+  "classifications": [
+    {
+      "figmaProperty": "{boolean name}",
+      "figmaKey": "{figmaKey from component_properties}",
+      "type": "BOOLEAN",
+      "pairedWith": "{figmaKey of paired instance swap or text slot, or null}",
+      "pairedType": "INSTANCE_SWAP | TEXT | null",
+      "classification": "ICON_BOOLEAN_GATED | KNOWN_SUBCOMPONENT | PAIRED_ACTION_SUBCOMPONENT | CONTENT_LEAF | REPEATING_PATTERN_MEMBER | REPEATING_PATTERN_CONTAINER | UNMAPPED_SUBCOMPONENT | UNCLASSIFIED",
+      "codeConnectSignal": "{what was found in code_connect_map, or 'absent'}",
+      "subComponent": "{componentName from code_connect_map, if sub-component}",
+      "configExists": true,
+      "configType": "{Name}Configuration",
+      "swiftType": "Optional3<Image> | String? | PriceConfiguration? | Bool | null",
+      "swiftName": "{suggested Swift property name}",
+      "dynamicProps": ["{list of dynamic prop names and types, for KNOWN_SUBCOMPONENT / PAIRED_ACTION_SUBCOMPONENT}"],
+      "staticProps": ["{list of static prop names, values, and types — parent hardcodes these}"],
+      "pairedClosure": "(() -> Void)? | null — only for PAIRED_ACTION_SUBCOMPONENT",
+      "rationale": "{why this classification and type were chosen, including static/dynamic reasoning}",
+      "halt": false,
+      "deferredTo": null
+    }
+  ],
+  "summary": {
+    "total": 0,
+    "iconBooleanGated": 0,
+    "knownSubComponent": 0,
+    "pairedActionSubComponent": 0,
+    "contentLeaf": 0,
+    "sectionToggle": 0,
+    "repeatingPattern": 0,
+    "unmapped": 0,
+    "unclassified": 0,
+    "halted": false
+  }
+}
+```
+
+### `{artifactPath}/pass3/04c_variant_config_analysis.md`
+
+Human-readable version with full rationale for each classification. Include:
+- The decision tree path taken for each boolean
+- code_connect_map evidence (snippet, componentName, source)
+- Configuration existence check results
+- Dynamic vs static default reasoning for icons
+- HALT details for unmapped sub-components
+
+---
+
+## DOWNSTREAM CONSUMERS
+
+This output is consumed by:
+
+| Phase | Artifact Read | Usage |
+|---|---|---|
+| **3D** (GATE 2: Architecture) | `04c_variant_config_analysis.json` | Uses classifications for §2.2 Sub-Component Detection and §2.3 Property Classification. Does NOT re-classify — consumes directly. Resolves UNCLASSIFIED entries using design_context. |
+| **4A** (Configuration) | `04c_variant_config_analysis.json` | Uses `swiftType` for property declarations. Only `dynamicProps` go in config — `staticProps` are omitted. Creates mini config structs for 2+ dynamic props. |
+| **4B** (View) | `04c_variant_config_analysis.json` | For KNOWN_SUBCOMPONENT: instantiates sub-component internally with `staticProps` hardcoded. For PAIRED_ACTION_SUBCOMPONENT: generates paired modifier binding data+closure. For ICON with Optional3: switches on `.default`/`.none`/`.some`. |
+| **6** (Code Connect) | `04c_variant_config_analysis.json` | For KNOWN_SUBCOMPONENT/PAIRED_ACTION_SUBCOMPONENT: `@FigmaBoolean` maps to `nil`/default-config. For ICON with Optional3: `@FigmaBoolean` maps to `.default`/`.none`. No ternary expressions. |
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] component_properties.json fully parsed (booleans, instance swaps, text slots)
+[ ] code_connect_map_response.json indexed and classified (ICON, SUBCOMPONENT, CROSS_PLATFORM)
+[ ] Every boolean property has a classification
+[ ] All ICON_BOOLEAN_GATED entries have Image? vs Optional3<Image> decision with rationale
+[ ] All KNOWN_SUBCOMPONENT entries have dynamicProps/staticProps filtered
+[ ] All PAIRED_ACTION_SUBCOMPONENT entries have pairedClosure specified
+[ ] All UNMAPPED_SUBCOMPONENT entries have HALT with clear instructions
+[ ] UNCLASSIFIED entries are flagged for 3D with deferredTo: "3D"
+[ ] Sub-component prop filtering: only dynamic (caller-controlled) props in swiftType, static (design-fixed) recorded separately
+[ ] 04c_variant_config_analysis.json written to pass3/
+[ ] 04c_variant_config_analysis.md written to pass3/
+[ ] Summary counts are correct
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-3h
+GATES_PASSED: [PRE_CHECK, INDEX_CODE_CONNECT_MAP, CLASSIFY_BOOLEAN_PROPERTIES, RESOLVE_SWIFT_TYPES, WRITE_ARTIFACTS]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass3/04c_variant_config_analysis.json
+  - {artifactPath}/pass3/04c_variant_config_analysis.md
+SUMMARY: Classified {total} boolean properties: {iconBooleanGated} icon, {knownSubComponent} sub-component, {pairedActionSubComponent} paired action, {contentLeaf} content leaf, {repeatingPattern} repeating, {unclassified} unclassified (deferred to 3D). Halted: {halted}.
+```