@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.0

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

@@ -1,333 +0,0 @@
-# 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 section2.2 Sub-Component Detection and section2.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}.
-```