@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-4c-documentation.md

@@ -0,0 +1,332 @@
+# PHASE 4C — FIGMA.md Documentation
+
+Write the FIGMA.md file for the component.
+This file is the bridge between Figma and code — used by other phases (Phase 3C nested lookup) and developers.
+
+required — always execute this phase.
+PARALLEL WITH: Phase 4A (Configuration), Phase 4B (View)
+
+---
+
+## CONTEXT VARIABLES
+
+These are provided by the orchestrator in the dispatch prompt:
+- `componentName` — e.g., "LabelBadge"
+- `componentLocation` — e.g., "Sources/UIComponents/.../LabelBadge/"
+- `artifactPath` — path to implementation artifacts
+- `nodeId` — Figma node ID
+- `fileKey` — Figma file key
+- `complexity` — SIMPLE or COMPLEX
+- `gitUser` — from `git config user.name`
+- `date` — current date in DD.MM.YYYY format
+
+---
+
+## PRE-CHECK
+
+Read all required analysis files:
+
+```
+{artifactPath}/pass3/04b_component_architecture.md  → API shape, enums, properties
+{artifactPath}/pass3/04_patterns.md                  → Variant mapping table
+{artifactPath}/pass3/03_nested_components.md         → Child components
+{artifactPath}/pass3/05_complexity.md                → SIMPLE or COMPLEX
+{artifactPath}/pass3/07_implementation_spec.md       → Compiled blueprint
+```
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-4c
+GATE: PRE_CHECK
+REASON: Required artifacts missing.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 3 first.
+```
+
+---
+
+## GATE 1: HEADER
+
+Build the header metadata block.
+
+### SIMPLE component
+
+```markdown
+# {ComponentName}
+
+**Figma:** [{ComponentName}](https://www.figma.com/design/{fileKey}/?node-id={nodeId}) | **Node:** `{nodeId}`
+**Path:** `UIComponents/Sources/UIComponents/Components/{relative path}/{ComponentName}.swift`
+**Component:** `{ComponentName}({param1}:{param2}:)`
+```
+
+### COMPLEX component
+
+```markdown
+# {ComponentName}
+
+**Figma:** [{ComponentName}](https://www.figma.com/design/{fileKey}/?node-id={nodeId}) | **Node:** `{nodeId}`
+**Path:** `UIComponents/Sources/UIComponents/Components/{relative path}/{ComponentName}.swift`
+**Init:** `{ComponentName}({dependencies}).{modifier}({value})`
+```
+
+Where the init shows required dynamic props + required closures:
+- No required props → `{ComponentName}().modifier(value)` (unlikely — most have at least one required prop)
+- Required prop + closure → `{ComponentName}(title: "value") { action() }.modifier(value)`
+- With binding → `{ComponentName}(page: $page, title: "value").modifier(value)`
+- With paired modifier → `{ComponentName}(title: "value") { action() }.secondaryButton("title") { action() }`
+
+**Rules:**
+- Path is relative from the package root (not absolute filesystem path)
+- Node ID uses colon format (`6893:6879`), not dash format
+- For SIMPLE: **Component** shows the init signature with parameter labels
+- For COMPLEX: **Init** shows the custom init + chain modifier pattern (preferred usage)
+- Trailing closure syntax ONLY when there is an actual closure dependency — NOT for configuration
+
+---
+
+## GATE 2: CONFIGURATION_SECTION (COMPLEX only)
+
+If SIMPLE → skip to GATE 3.
+
+INPUT: `pass3/04b_component_architecture.md` → Final API Design
+
+### 2.1 Configuration struct
+
+```markdown
+## Configuration
+
+```swift
+{ComponentName}Configuration(
+    {param1}: {Type},
+    {param2}: {Type}? = nil,
+    {param3}: {Type} = {default}
+)
+```
+```
+
+Show ALL init parameters with their types and defaults. Match the exact init from the architecture spec.
+
+### 2.2 Chainable modifiers
+
+```markdown
+## Chainable Modifiers
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| `.{property1}(_:)` | `{Type}` | {Brief description} |
+| `.{property1}(localized:)` | `LocalizedStringKey` | Localized variant |
+| `.{property2}(_:)` | `{Type}?` | {Brief description} |
+```
+
+**Rules:**
+- List every chainable property from the Configuration
+- Skip properties marked `@IgnoreChainModifier` (UUIDs, IDs)
+- Include `(localized:)` variant for String properties NOT marked `@IgnoreLocalization`
+- These are auto-generated by `@GenerateChainModifiers` — document what the macro produces
+
+---
+
+## GATE 3: VARIANT_MAPPING
+
+INPUT: `pass3/04_patterns.md` → Variant Examples section
+INPUT: `pass3/04b_component_architecture.md` → Variant-to-Enum Mapping
+
+Build the Figma-to-Swift mapping table:
+
+```markdown
+## Variant Mapping
+
+| Figma Property | Figma Value | Code |
+|----------------|-------------|------|
+| {Property1} | {Value1} | `{swiftParam}: .{enumCase}` |
+| {Property1} | {Value2} | `{swiftParam}: .{enumCase}` |
+| {BooleanProp} | true | `{param}: {value}` |
+| {BooleanProp} | false | `{param}: nil` |
+```
+
+**Rules:**
+- Map EVERY Figma variant property to its Swift equivalent
+- For VARIANT type properties → show enum case
+- For BOOLEAN type properties → show the Swift value for true and false
+- For TEXT type properties → show parameter with example value
+- For INSTANCE_SWAP → show the merged Image? property
+- If a boolean + instance swap were merged into `Image?` → show:
+  - `true` → `{param}: Image.{name}`
+  - `false` → `{param}: nil`
+
+---
+
+## GATE 4: PARAMETERS_SECTION (SIMPLE only)
+
+If COMPLEX → skip to GATE 5.
+
+INPUT: `pass3/04b_component_architecture.md` → Final API Design
+
+```markdown
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `{param1}` | `{Type}` | Required | {Brief description} |
+| `{param2}` | `{Type}` | `.{default}` | {Brief description} |
+| `{param3}` | `{Type}?` | `nil` | {Brief description} |
+```
+
+**Rules:**
+- List ALL init parameters
+- Mark required parameters (no default) as "Required"
+- Show actual default values for optional parameters
+- Descriptions should be concise (5-10 words)
+
+---
+
+## GATE 5: NESTED_COMPONENTS
+
+INPUT: `pass3/03_nested_components.md`
+
+If no nested View components (only inline Text/Image) → skip.
+
+```markdown
+## Nested Components
+
+- **{ChildComponent}** — [{ChildComponent} FIGMA.md](relative/path/to/FIGMA.md)
+```
+
+**Rules:**
+- Only list components that have their own FIGMA.md
+- Use relative paths from current component directory
+- Skip native SwiftUI views (Text, Image, HStack, etc.)
+- Skip UIAssets image tokens (those are not View components)
+
+---
+
+## GATE 6: USAGE
+
+INPUT: `pass3/04b_component_architecture.md` → Final API Design
+INPUT: `pass3/04_patterns.md` → Variant Examples
+
+**CRITICAL:** The FIRST usage example is what AI reads during Phase 3C nested component lookup. It MUST show the recommended init pattern with clear parameter labels.
+
+### SIMPLE component
+
+```markdown
+## Usage
+
+```swift
+// Recommended pattern
+{ComponentName}({param1}: {value1}, {param2}: .{enumCase})
+
+// Minimal (defaults only)
+{ComponentName}({requiredParam}: {value})
+
+// With optional parameters
+{ComponentName}(
+    {param1}: {value1},
+    {param2}: .{enumCase},
+    {optionalParam}: {value}
+)
+```
+```
+
+### COMPLEX component
+
+COMPLEX components use a **custom init** with required dynamic props + required closures. Chain modifiers configure optional properties. Paired modifiers bind optional data+closure together.
+
+```markdown
+## Usage
+
+```swift
+// Required props in init, optional via chain modifiers
+{ComponentName}({requiredProp}: "{value}", {requiredClosure}: { action() })
+    .{optionalProp}(.{enumCase})
+
+// With paired modifier (optional sub-component with action)
+{ComponentName}({requiredProp}: "{value}", {requiredClosure}: { action() })
+    .secondaryButton("{title}") { secondaryAction() }
+    .{optionalProp}(.{enumCase})
+
+// Configuration init (programmatic/data-driven use)
+{ComponentName}(configuration: .init({requiredProp}: "{value}"), {requiredClosure}: { action() })
+```
+```
+
+**Rules:**
+- Show ONLY the preferred pattern: required props in init + chain modifiers — FIGMA.md is consumed by AI (Phase 3C nesting), keep it compact
+- Required dynamic props and required closures go in init
+- Optional config props → chain modifiers
+- Paired sub-components → paired modifiers (`.secondaryButton("title") { action }`)
+- Show 1-2 examples covering major variant combinations
+- Use realistic sample values from the Figma variant examples
+- For COMPLEX: custom init + chain modifier pattern only
+- For SIMPLE: direct init only
+
+---
+
+## GATE 7: ALL_VARIANTS (optional)
+
+INPUT: `pass3/04_patterns.md` → Variant Examples
+
+If the variant matrix is small (≤ 10 combinations) AND the component has discrete visual states, include an exhaustive table:
+
+```markdown
+## All Variants
+
+| {Property1} | {Property2} | Code |
+|-------------|-------------|------|
+| {Value1} | {Value2} | `{ComponentName}({p1}: .{v1}, {p2}: .{v2})` |
+```
+
+If the matrix is large (> 10 combinations) → skip this section. The Variant Mapping table is sufficient.
+
+---
+
+## GATE 8: NOTES (optional)
+
+Add notes ONLY if there are non-obvious behaviors:
+
+```markdown
+## Notes
+
+- Default state is `.{defaultCase}`
+- Icon is decorative and hidden from VoiceOver
+- Component sizes to fit content (no fixed width)
+```
+
+Skip if there's nothing noteworthy beyond what's obvious from the API.
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] File exists at {componentLocation}/FIGMA.md
+[ ] Figma URL is correct with proper node-id
+[ ] Node ID uses colon format (not dash)
+[ ] Path is relative from package root
+[ ] Init signature matches the actual implementation
+[ ] Variant Mapping covers ALL Figma properties
+[ ] Configuration section present (if COMPLEX)
+[ ] Chainable Modifiers listed (if COMPLEX)
+[ ] Parameters table present (if SIMPLE)
+[ ] Nested components listed with relative paths (if any)
+[ ] First usage example is the recommended pattern
+[ ] Usage shows 2-4 examples covering major variants
+[ ] All Variants table (if ≤10 combinations)
+[ ] No implementation details — only public API surface
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-4c
+GATES_PASSED: [PRE_CHECK, HEADER, CONFIGURATION_SECTION, VARIANT_MAPPING, PARAMETERS_SECTION, NESTED_COMPONENTS, USAGE, ALL_VARIANTS, NOTES]
+ARTIFACTS_CREATED:
+  - {componentLocation}/FIGMA.md
+SUMMARY: FIGMA.md documentation complete. {COMPLEXITY} component. {VARIANT_COUNT} variant mappings. {USAGE_COUNT} usage examples.
+```

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-4d-preview.md

@@ -0,0 +1,380 @@
+# PHASE 4D — Preview (LTR + RTL)
+
+Write two preview structs — `{ComponentName}Preview` (LTR) and `{ComponentName}RTLPreview` (RTL with Arabic text) — and their `#Preview` entry points at the bottom of `{ComponentName}.swift`.
+
+required — always execute this phase.
+SEQUENTIAL: Runs AFTER Phase 4A (Configuration) and Phase 4B (View) complete.
+
+---
+
+## CONTEXT VARIABLES
+
+These are provided by the orchestrator in the dispatch prompt:
+- `componentName` — e.g., "LabelBadge"
+- `componentLocation` — e.g., "Sources/UIComponents/.../LabelBadge/"
+- `artifactPath` — path to implementation artifacts
+- `complexity` — SIMPLE or COMPLEX
+
+---
+
+## PRE-CHECK
+
+Verify the View file exists (Phase 4B must have completed):
+
+```
+{componentLocation}/{ComponentName}.swift must exist
+```
+
+Read the variant analysis:
+```
+{artifactPath}/pass3/04_patterns.md      → Variant Examples, Dimensions
+{artifactPath}/pass3/04b_component_architecture.md → API shape, enums
+```
+
+If View file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-4d
+GATE: PRE_CHECK
+REASON: {ComponentName}.swift not found. Phase 4B must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 4B first.
+```
+
+---
+
+## WHY A SEPARATE PREVIEW STRUCT
+
+`#Preview` is a freestanding macro. `@GenerateViewConfiguration` is a member macro that generates `configured()` and forwarding modifiers. When the component is placed directly inside `#Preview { ... }`, the freestanding macro expansion may not resolve members generated by the member macro — the compiler reports "no accessible initializers." This is a known Apple bug.
+
+The workaround:
+1. Create `{ComponentName}Preview: View` — a plain struct with NO macros, auto-synthesized `init()`
+2. `#Preview` instantiates `{ComponentName}Preview()` — it only needs to see the plain `init()`, which has no macro dependency
+3. Inside `{ComponentName}Preview.body`, the custom init and chain modifiers ARE visible because `body` is evaluated during normal type-checking, not during freestanding macro expansion
+
+---
+
+## DUAL PREVIEW CONCEPT
+
+Every component gets **two previews** to verify both layout directions:
+
+| Preview | Struct | Purpose |
+|---------|--------|---------|
+| LTR (default) | `{ComponentName}Preview` | Standard left-to-right preview with English/default text |
+| RTL | `{ComponentName}RTLPreview` | Right-to-left preview with Arabic text, verifies mirroring |
+
+### Identical content exception
+
+If **all** text properties are non-localized (codes, numbers, acronyms) and preview content would be identical between LTR and RTL, use a **single preview struct** with both `#Preview` entry points:
+
+```swift
+struct {ComponentName}Preview: View {
+    var layoutDirection: LayoutDirection = .leftToRight
+
+    var body: some View {
+        // ... preview content ...
+        .environment(\.layoutDirection, layoutDirection)
+        .environment(\.locale, layoutDirection == .rightToLeft ? Locale(identifier: "ar") : .current)
+    }
+}
+
+#Preview {
+    {ComponentName}Preview()
+}
+
+#Preview("RTL") {
+    {ComponentName}Preview(layoutDirection: .rightToLeft)
+}
+```
+
+This avoids duplicating identical view trees. Only applicable when there is zero difference in text content between LTR and RTL.
+
+### Text property rules for RTL preview
+
+| Property type | LTR text | RTL text | Example |
+|---------------|----------|----------|---------|
+| Localized text props (component content) | English placeholder | Arabic placeholder | `"Lorem"` → `"نص تجريبي"` |
+| Non-localized text props (codes, numbers, IDs) | Same as LTR | Same as LTR | `"TK1234"` → `"TK1234"` |
+| Preview section labels (developer scaffolding) | English | English | `"With Icon"` stays `"With Icon"` |
+
+### Common Arabic placeholder text
+
+Use these contextually appropriate Arabic placeholders:
+
+| English | Arabic | Use case |
+|---------|--------|----------|
+| `"Lorem"` / generic text | `"نص تجريبي"` | Default text content |
+| `"Title"` | `"العنوان"` | Title fields |
+| `"Subtitle"` / `"Description"` | `"الوصف"` | Subtitle/description fields |
+| `"Label"` / `"Button"` | `"زر الإجراء"` | Button labels |
+| `"Search"` | `"بحث"` | Search placeholders |
+| `"Name"` | `"الاسم"` | Name fields |
+| `"Message"` | `"رسالة"` | Message/notification text |
+| Short status | `"نشط"` | Active/status indicators |
+
+---
+
+## GATE 1: PREVIEW_STRUCT
+
+Append to the bottom of `{componentLocation}/{ComponentName}.swift`:
+
+### COMPLEX component (with Configuration + `+Modifiers`)
+
+**Preferred style:** Use the custom init with required props + chain modifiers for optional props.
+
+For components with required props + closure dependencies:
+- `{ComponentName}(title: "Book Now") { /* action */ }` — required props + trailing closure in init
+- `.style(.primary).size(.xlarge)` — optional config via chain modifiers
+
+For components with paired modifiers:
+- `{ComponentName}(title: "OK") { primaryAction() }` — required in init
+- `.secondaryButton("Cancel") { cancel() }` — paired modifier
+- `.state(.scroll)` — optional config via chain modifier
+
+```swift
+// MARK: - Preview
+
+struct {ComponentName}Preview: View {
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: .Spacing.spacing16) {
+                Text("{ComponentName}")
+                    .typographyStyle(.bodyBold)
+                    .foregroundStyle(Color.Text.textPrimary)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+
+                // If main variant is CaseIterable enum, iterate:
+                ForEach({ComponentName}Configuration.{EnumType}.allCases, id: \.self) { variant in
+                    VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                        Text(variant.rawValue.capitalized)
+                            .typographyStyle(.captionRegular)
+                            .foregroundStyle(Color.Text.textGrey)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+
+                        {ComponentName}({requiredProp}: {englishValue}) { /* action */ }
+                            .{variantParam}(variant)
+                    }
+
+                    Divider()
+                }
+
+                // Additional combinations (boolean toggles, paired modifiers, etc.)
+                VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                    Text("{VariantDescription}")
+                        .typographyStyle(.captionRegular)
+                        .foregroundStyle(Color.Text.textGrey)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+
+                    {ComponentName}({requiredProp}: {englishValue}) { /* action */ }
+                        .{optionalParam}({value})
+                }
+            }
+            .padding(.Spacing.spacing16)
+        }
+    }
+}
+
+struct {ComponentName}RTLPreview: View {
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: .Spacing.spacing16) {
+                Text("{ComponentName} — RTL")
+                    .typographyStyle(.bodyBold)
+                    .foregroundStyle(Color.Text.textPrimary)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+
+                ForEach({ComponentName}Configuration.{EnumType}.allCases, id: \.self) { variant in
+                    VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                        Text(variant.rawValue.capitalized)
+                            .typographyStyle(.captionRegular)
+                            .foregroundStyle(Color.Text.textGrey)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+
+                        {ComponentName}({requiredProp}: {arabicValue}) { /* action */ }
+                            .{variantParam}(variant)
+                    }
+
+                    Divider()
+                }
+
+                VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                    Text("{VariantDescription}")
+                        .typographyStyle(.captionRegular)
+                        .foregroundStyle(Color.Text.textGrey)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+
+                    {ComponentName}({requiredProp}: {arabicValue}) { /* action */ }
+                        .{optionalParam}({value})
+                }
+            }
+            .padding(.Spacing.spacing16)
+        }
+        .environment(\.layoutDirection, .rightToLeft)
+        .environment(\.locale, Locale(identifier: "ar"))
+    }
+}
+
+#Preview {
+    {ComponentName}Preview()
+}
+
+#Preview("RTL") {
+    {ComponentName}RTLPreview()
+}
+```
+
+### SIMPLE component
+
+```swift
+// MARK: - Preview
+
+struct {ComponentName}Preview: View {
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: .Spacing.spacing16) {
+                Text("{ComponentName}")
+                    .typographyStyle(.bodyBold)
+                    .foregroundStyle(Color.Text.textPrimary)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+
+                VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                    Text("{VariantName}")
+                        .typographyStyle(.captionRegular)
+                        .foregroundStyle(Color.Text.textGrey)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+
+                    {ComponentName}(
+                        {param1}: {englishValue},
+                        {param2}: .{enumCase}
+                    )
+                }
+
+                Divider()
+
+                // More variants...
+            }
+            .padding(.Spacing.spacing16)
+        }
+    }
+}
+
+struct {ComponentName}RTLPreview: View {
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: .Spacing.spacing16) {
+                Text("{ComponentName} — RTL")
+                    .typographyStyle(.bodyBold)
+                    .foregroundStyle(Color.Text.textPrimary)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+
+                VStack(alignment: .leading, spacing: .Spacing.spacing4) {
+                    Text("{VariantName}")
+                        .typographyStyle(.captionRegular)
+                        .foregroundStyle(Color.Text.textGrey)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+
+                    {ComponentName}(
+                        {param1}: {arabicValue},
+                        {param2}: .{enumCase}
+                    )
+                }
+
+                Divider()
+
+                // More variants...
+            }
+            .padding(.Spacing.spacing16)
+        }
+        .environment(\.layoutDirection, .rightToLeft)
+        .environment(\.locale, Locale(identifier: "ar"))
+    }
+}
+
+#Preview {
+    {ComponentName}Preview()
+}
+
+#Preview("RTL") {
+    {ComponentName}RTLPreview()
+}
+```
+
+---
+
+## GATE 2: VARIANT COVERAGE
+
+Verify ALL variants from `pass3/04_patterns.md` → Variant Examples are rendered in **both** previews:
+
+### Rules
+
+- **Every variant** from the Figma component set must appear in both LTR and RTL previews
+- LTR uses **English/default sample values** from the analysis
+- RTL uses **Arabic placeholder text** for localized text props (see table above), same values for non-localized props
+- If a variant property is an enum with `CaseIterable`, use `ForEach` to iterate all cases (in both previews)
+- Boolean toggle combinations (with icon, without icon, icon-only) listed as separate sections after the enum loop
+- Each variant section labeled with `.captionRegular` + `.textGrey`
+- ALL explanatory texts (titles, labels) must be **leading aligned** (`.frame(maxWidth: .infinity, alignment: .leading)`)
+- Sections separated by `Divider()`
+- RTL preview has `.environment(\.layoutDirection, .rightToLeft)` and `.environment(\.locale, Locale(identifier: "ar"))` on the outermost container
+- RTL preview title includes `" — RTL"` suffix for visual identification
+
+### Width handling
+
+- Component width < screen → natural width, no frame
+- Component width = screen → `.frame(maxWidth: .infinity)`
+- Component width > screen → horizontal ScrollView or fixed frame
+
+### Contrasting background
+
+**ALWAYS** apply `Color.Background.backgroundGrey` as the preview container background. This is the app's standard page background color, so previews show how the component looks in-app. It also makes white component edges, padding, and corner radius clearly visible.
+
+```swift
+.padding(.Spacing.spacing16)
+.background(Color.Background.backgroundGrey)
+```
+
+Without this, white components are invisible on the white Xcode canvas.
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] {ComponentName}Preview struct appended to {ComponentName}.swift (not a separate file)
+[ ] {ComponentName}RTLPreview struct appended to {ComponentName}.swift (not a separate file)
+[ ] Both preview structs have NO macros — plain structs
+[ ] #Preview instantiates {ComponentName}Preview() (unnamed = LTR default)
+[ ] #Preview("RTL") instantiates {ComponentName}RTLPreview()
+[ ] Inside Preview body, COMPLEX uses custom init + chain modifiers: {ComponentName}(requiredProp: val) { action }.prop1(val)
+[ ] Inside Preview body, SIMPLE uses direct init: {ComponentName}(param: value)
+[ ] ALL variant examples from pass3/04_patterns.md are rendered in BOTH previews
+[ ] LTR preview uses English/default text values
+[ ] RTL preview uses Arabic placeholder text for localized text props
+[ ] RTL preview keeps same values for non-localized props (codes, numbers, IDs)
+[ ] RTL preview has .environment(\.layoutDirection, .rightToLeft) on outermost container
+[ ] RTL preview has .environment(\.locale, Locale(identifier: "ar")) on outermost container
+[ ] ForEach used for CaseIterable enum variants (in both previews)
+[ ] Boolean toggle combinations shown as separate sections
+[ ] All labels use .captionRegular + .textGrey, leading aligned
+[ ] Sections separated by Divider()
+[ ] ScrollView wraps content in both previews
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-4d
+GATES_PASSED: [PRE_CHECK, PREVIEW_STRUCT, VARIANT_COVERAGE]
+ARTIFACTS_CREATED:
+  - {componentLocation}/{ComponentName}.swift (appended LTR + RTL Previews)
+SUMMARY: Dual preview appended to {ComponentName}.swift. {VARIANT_COUNT} variants rendered in LTR + RTL. {ComponentName}Preview (LTR) + {ComponentName}RTLPreview (RTL/Arabic) with #Preview entry points.
+```