@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-7a-confluence-generate.md

@@ -0,0 +1,659 @@
+# PHASE 7A — Confluence Documentation: Generate XHTML
+
+Generate platform-agnostic main page + iOS sub-page as XHTML artifacts.
+No network access required. Upload is handled by Phase 7B.
+REF: `reference/confluence-xhtml.md`, `reference/confluence-api.md`
+
+PREV: Phase 6 (Code Connect)
+NEXT: Phase 7B (Upload to Confluence, VPN required)
+TOOL RESTRICTIONS: No Edit
+
+> **VPN Note:** This phase generates XHTML locally — no VPN needed. Colleagues
+> without VPN access can run this phase and commit the Confluence documentation directory.
+> A colleague with VPN then runs Phase 7B to upload.
+>
+> The global Component Implementation Status dashboard
+> (`.instructions/figma/figma-to-swiftui/scripts/confluence-component-status.py`) also requires
+> VPN. Run it separately after uploading component pages.
+
+---
+
+## PRE_CHECK
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {componentLocation}/{componentName}.swift
+Read: {componentLocation}/FIGMA.md
+Read: {artifactPath}/pass1/screenshot.png (verify exists)
+Read: {artifactPath}/pass1/screenshots/variants.md (if exists — variant property values)
+Read: {artifactPath}/pass3/07_implementation_spec.md
+Read: {artifactPath}/pass3/08_utility_integration.md
+Read: {artifactPath}/pass3/03_nested_components.md
+Read: {artifactPath}/pass2/utility_analytics.md (if exists)
+```
+
+Also find iOS snapshot tests and reference images:
+
+```
+Glob: Tests/UIComponentsTests/Snapshot/**/{componentName}SnapshotTests.swift
+Glob: Tests/UIComponentsTests/Snapshot/**/{componentName}/__Snapshots__/{componentName}SnapshotTests/*.png
+```
+
+Read the snapshot test file to extract test names and the Swift code each test uses.
+
+Also read the per-component registry:
+
+```bash
+$REGISTRY utility-lookup --node-id '{nodeId}'
+```
+
+Run from repo root: `cd {repos.common.path} && .build/debug/FigmaRegistryUtility`
+
+EXTRACT:
+- `componentName`, `nodeId`, `fileKey`
+- `componentLocation`, `artifactPath`, `confluencePath`
+- `complexity` (SIMPLE/COMPLEX from pass3/07)
+- `registryData` (testingIdentifiers, localizationKeys, accessibilityKeys, analyticsEvents)
+- `confluenceStatus` — from registry `confluence` field: `{ page, ios, android }` (null = not yet created)
+- Initializer signature (from FIGMA.md)
+- Usage examples (from FIGMA.md)
+- Nested components (from FIGMA.md / pass3/03)
+- Code Connect status (from FIGMA.md Code Connect section, if exists)
+- Description, screen, section, size (from pass3/07)
+
+If `confluence.page` is non-null, this is an **update** — note existing URLs in the output.
+If `confluence.page` is null, this is a **first-time creation**.
+
+If IMPLEMENTATION_HISTORY.md, the Swift file, or FIGMA.md is missing:
+
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: PRE_CHECK
+REASON: Required artifacts not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Ensure Phase 4 completed. Required: IMPLEMENTATION_HISTORY.md, {componentName}.swift, FIGMA.md
+```
+
+---
+
+## GATE 1: CREATE_STRUCTURE
+
+Create output directory and copy screenshots.
+
+```bash
+mkdir -p {confluencePath}/assets
+cp {artifactPath}/pass1/screenshot.png {confluencePath}/assets/screenshot.png
+```
+
+If variant screenshots exist:
+
+```bash
+if [ -d "{artifactPath}/pass1/screenshots" ]; then
+    cp {artifactPath}/pass1/screenshots/*.png {confluencePath}/assets/
+fi
+```
+
+If iOS snapshot test reference images exist, copy with `ios_` prefix:
+
+```bash
+# Snapshot image filenames are: test_snapshot_{mode}_{variant}.{mode}_{variant}.png
+# Extract the named part (after the dot) and prefix with ios_
+# e.g. test_snapshot_light_success.light_success.png → ios_light_success.png
+for f in __Snapshots__/{ComponentName}SnapshotTests/*.png; do
+    named=$(echo "$(basename "$f")" | sed 's/.*\.\(.*\)\.png/\1/')
+    cp "$f" {confluencePath}/assets/ios_${named}.png
+done
+```
+
+List all copied assets for the ARTIFACTS_CREATED output.
+
+---
+
+## GATE 2: GENERATE_MAIN_XHTML
+
+Write `{confluencePath}/main.html` using the template below.
+
+### Data Mapping
+
+| Template Variable | Source |
+|-------------------|--------|
+| `{DESCRIPTION}` | Synthesize 1-line from pass3/07 overview |
+| `{FILE_KEY}`, `{NODE_ID}` | From context |
+| `{SCREEN}`, `{SECTION}`, `{SIZE}` | From pass3/07 metadata |
+| `{OVERVIEW_TEXT}` | 2-3 sentence description from pass3/07 |
+| Testing Identifiers table | `registryData.testingIdentifiers` — columns: Element (usage), Key, Value |
+| Localization Keys table | `registryData.localizationKeys` — columns: Element, Key, Default |
+| Accessibility tables | `registryData.accessibilityKeys` — Labels + Hints |
+| Analytics Events | `registryData.analyticsEvents` — element + event (markdown text) |
+| Sub-Components | From FIGMA.md nested components / pass3/03 |
+| Platform links | `{ComponentName} - iOS`, `{ComponentName} - Android` |
+| Changelog | Current date + "Initial documentation" |
+
+### Empty Section Handling
+
+- If `testingIdentifiers` is empty: `<p>No testing identifiers registered.</p>`
+- If `localizationKeys` is empty: `<p>No localization keys. Text content is dynamic.</p>`
+- If `accessibilityKeys` is empty: `<p>No dedicated accessibility keys.</p>`
+- If `analyticsEvents` is empty: `<p>No analytics events. No interactive elements.</p>`
+- If no nested components: `<p>No nested View components.</p>`
+- If no variant screenshots: show only main screenshot, skip Light/Dark table
+
+### Main Page Template
+
+```xml
+<p><em>{DESCRIPTION}</em></p>
+
+<p><ac:image ac:width="375"><ri:attachment ri:filename="screenshot.png"/></ac:image></p>
+
+<p><a href="https://www.figma.com/design/{FILE_KEY}/?node-id={NODE_ID_DASH}">View in Figma</a></p>
+
+<p><strong>Screen:</strong> {SCREEN}<br/>
+<strong>Section:</strong> {SECTION}<br/>
+<strong>Size:</strong> {SIZE}</p>
+
+<hr/>
+
+<ac:structured-macro ac:name="toc">
+<ac:parameter ac:name="printable">true</ac:parameter>
+<ac:parameter ac:name="style">disc</ac:parameter>
+<ac:parameter ac:name="maxLevel">2</ac:parameter>
+<ac:parameter ac:name="minLevel">2</ac:parameter>
+</ac:structured-macro>
+
+<hr/>
+
+<h2>Variants</h2>
+<!-- IF variant screenshots exist (pass1/screenshots/): -->
+<table><tbody>
+<tr><th>Variant</th><th>Properties</th><th>Figma Screenshot</th></tr>
+<tr><td>{VariantName}</td><td><code>{FigmaPropertyName}={Value}</code></td><td><ac:image ac:width="100"><ri:attachment ri:filename="{VariantName}.png"/></ac:image></td></tr>
+</tbody></table>
+<!-- Use pass1/screenshots/variants.md for variant names + property values -->
+<!-- ELSE just show the main screenshot (already in header). Skip this section. -->
+
+<hr/>
+
+<h2>Overview</h2>
+<p>{OVERVIEW_TEXT}</p>
+
+<hr/>
+
+<h2>Testing Identifiers</h2>
+<p><em>Shared across platforms</em></p>
+<table><tbody>
+<tr><th>Element</th><th>Key</th><th>Value</th></tr>
+<tr><td>{usage}</td><td><code>{key}</code></td><td><code>{value}</code></td></tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Localization Keys</h2>
+<p><em>Shared across platforms</em></p>
+<table><tbody>
+<tr><th>Element</th><th>Key</th><th>Default (EN)</th></tr>
+<tr><td>{element}</td><td><code>{key}</code></td><td>{default}</td></tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Accessibility</h2>
+<p><em>Shared across platforms</em></p>
+
+<h3>Labels</h3>
+<table><tbody>
+<tr><th>Element</th><th>Key</th></tr>
+<tr><td>{element}</td><td><code>{key}</code></td></tr>
+</tbody></table>
+
+<h3>Hints</h3>
+<table><tbody>
+<tr><th>Element</th><th>Key</th></tr>
+<tr><td>{element}</td><td><code>{key}</code></td></tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Analytics Events</h2>
+<p><em>Shared across platforms</em></p>
+
+<h3>{event_element}</h3>
+<p>{event_description_from_registry_event_field}</p>
+<table><tbody>
+<tr><th>Property</th><th>Value</th></tr>
+<tr><td>Element</td><td>{element}</td></tr>
+<tr><td>Identifier Key</td><td><code>{identifierKey}</code></td></tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Sub-Components</h2>
+<table><tbody>
+<tr><th>Component</th><th>Description</th></tr>
+<tr>
+<td><ac:link><ri:page ri:content-title="{SubComponentName}"/><ac:plain-text-link-body><![CDATA[{SubComponentName}]]></ac:plain-text-link-body></ac:link></td>
+<td>{description}</td>
+</tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Platform Implementations</h2>
+<table><tbody>
+<tr><th>Platform</th><th>Status</th><th>Documentation</th></tr>
+<tr>
+<td>iOS</td>
+<td>Implemented</td>
+<td><ac:link><ri:page ri:content-title="{ComponentName} - iOS"/><ac:plain-text-link-body><![CDATA[{ComponentName} - iOS]]></ac:plain-text-link-body></ac:link></td>
+</tr>
+<tr>
+<td>Android</td>
+<td>Pending</td>
+<td><ac:link><ri:page ri:content-title="{ComponentName} - Android"/><ac:plain-text-link-body><![CDATA[{ComponentName} - Android]]></ac:plain-text-link-body></ac:link></td>
+</tr>
+</tbody></table>
+
+<hr/>
+
+<h2>Changelog</h2>
+<table><tbody>
+<tr><th>Date</th><th>Change</th></tr>
+<tr><td>{DATE}</td><td>Initial documentation</td></tr>
+</tbody></table>
+```
+
+**IMPORTANT:** Replace all template variables with actual data. Remove HTML comments. The output must be valid XHTML.
+
+**XHTML Attribute Escaping:** All dynamic text inserted into XML attribute values (`ri:filename`, `ri:content-title`) MUST have these characters escaped:
+- `&` → `&amp;` (e.g., `Miles&Smiles` → `Miles&amp;Smiles`)
+- `"` → `&quot;`
+- `<` → `&lt;`, `>` → `&gt;`
+
+Text inside `<![CDATA[...]]>` blocks does NOT need escaping. Text inside element content (between tags) needs `&` and `<` escaped. Filenames on disk keep the original characters — the XML parser decodes `&amp;` back to `&` when resolving attachment references.
+
+---
+
+## GATE 3: GENERATE_IOS_XHTML
+
+Write `{confluencePath}/ios.html` using the template below.
+
+### Data Mapping
+
+| Template Variable | Source |
+|-------------------|--------|
+| Back-link | `{ComponentName}` (main page title) |
+| Initializer | From FIGMA.md header section |
+| Parameters | From FIGMA.md API/Parameters section |
+| Usage | From FIGMA.md Usage section (first example) |
+| Configuration | From FIGMA.md Configuration section (COMPLEX only) |
+| Testing iOS Usage | From pass3/08 Testing Identifiers section |
+| Localization iOS Usage | From pass3/08 Localization section |
+| Accessibility iOS | From pass3/08 Accessibility section |
+| Analytics iOS | From pass2/utility_analytics.md Implementation section |
+| Code Connect | From FIGMA.md Code Connect section (if exists) |
+
+### iOS Sub-Page Template
+
+```xml
+<p><ac:link><ri:page ri:content-title="{ComponentName}"/><ac:plain-text-link-body><![CDATA[&larr; Back to {ComponentName}]]></ac:plain-text-link-body></ac:link></p>
+
+<hr/>
+
+<ac:structured-macro ac:name="toc">
+<ac:parameter ac:name="printable">true</ac:parameter>
+<ac:parameter ac:name="style">disc</ac:parameter>
+<ac:parameter ac:name="maxLevel">2</ac:parameter>
+<ac:parameter ac:name="minLevel">2</ac:parameter>
+</ac:structured-macro>
+
+<hr/>
+
+<h2>Initializer</h2>
+
+<!-- IF SIMPLE: -->
+<ac:structured-macro ac:name="code">
+<ac:parameter ac:name="language">java</ac:parameter>
+<ac:plain-text-body><![CDATA[{INIT_SIGNATURE}]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<h3>Parameters</h3>
+<table><tbody>
+<tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr>
+<tr><td><code>{param}</code></td><td><code>{Type}</code></td><td>{default}</td><td>{description}</td></tr>
+</tbody></table>
+
+<!-- IF COMPLEX: -->
+<ac:structured-macro ac:name="code">
+<ac:parameter ac:name="language">java</ac:parameter>
+<ac:plain-text-body><![CDATA[// Chain modifiers (recommended)
+{ComponentName} { /* dependency closure */ }
+    .{modifier}({value})
+
+// Configuration closure
+{ComponentName} { config in
+    config
+        .{modifier}({value})
+}
+
+// Direct configuration
+{ComponentName}(configuration: {ComponentName}Configuration(
+    {param}: {value}
+))]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<h3>Configuration Properties</h3>
+<table><tbody>
+<tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr>
+<tr><td><code>{param}</code></td><td><code>{Type}</code></td><td>{default}</td><td>{description}</td></tr>
+</tbody></table>
+
+<h3>Chain Modifiers</h3>
+<p>Auto-generated by <code>@GenerateChainModifiers</code>.</p>
+<table><tbody>
+<tr><th>Modifier</th><th>Type</th><th>Description</th></tr>
+<tr><td><code>.{property}(_:)</code></td><td><code>{Type}</code></td><td>{description}</td></tr>
+</tbody></table>
+<!-- END complexity branching -->
+
+<hr/>
+
+<h2>Usage</h2>
+<ac:structured-macro ac:name="code">
+<ac:parameter ac:name="language">java</ac:parameter>
+<ac:plain-text-body><![CDATA[import UIComponents
+
+{USAGE_CODE}]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<hr/>
+
+<!-- IF testing identifiers exist: -->
+<h2>Testing Identifiers - iOS</h2>
+<table><tbody>
+<tr><th>Element</th><th>iOS Usage</th></tr>
+<tr><td>{element}</td><td><code>.accessibilityIdentifier(.{ComponentName}.{element})</code></td></tr>
+</tbody></table>
+
+<hr/>
+<!-- END IF -->
+
+<!-- IF localization keys exist: -->
+<h2>Localization - iOS</h2>
+<table><tbody>
+<tr><th>Element</th><th>iOS Usage</th></tr>
+<tr><td>{element}</td><td><code>Text(.{ComponentName}.{element})</code></td></tr>
+</tbody></table>
+
+<hr/>
+<!-- END IF -->
+
+<!-- IF accessibility keys exist: -->
+<h2>Accessibility - iOS</h2>
+<table><tbody>
+<tr><th>Element</th><th>iOS Usage</th></tr>
+<tr><td>{element}</td><td><code>.accessibilityLabel(.{ComponentName}.{element})</code></td></tr>
+</tbody></table>
+
+<hr/>
+<!-- END IF -->
+
+<!-- IF analytics events exist: -->
+<h2>Analytics - iOS</h2>
+
+<h3>{event_element}</h3>
+<p><strong>Modifier:</strong></p>
+<ac:structured-macro ac:name="code">
+<ac:parameter ac:name="language">java</ac:parameter>
+<ac:plain-text-body><![CDATA[{ANALYTICS_MODIFIER_CODE_FROM_PASS2}]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<p><strong>Firebase Schema:</strong></p>
+<ac:structured-macro ac:name="code">
+<ac:parameter ac:name="language">java</ac:parameter>
+<ac:plain-text-body><![CDATA[{FIREBASE_SCHEMA_JSON}]]></ac:plain-text-body>
+</ac:structured-macro>
+
+<hr/>
+<!-- END IF analytics -->
+
+<!-- Code Connect section: SKIP — decoupled from Confluence. Lives in Figma Dev Mode. -->
+<!-- If a .figma.swift file exists, optionally show a one-line "Code Connect: Published" badge. -->
+<!-- Otherwise omit entirely. -->
+
+<hr/>
+
+<h2>Snapshot Tests</h2>
+<p><em>Reference snapshots generated by <code>{ComponentName}SnapshotTests</code>.</em></p>
+<!-- Find snapshot test file: Tests/UIComponentsTests/Snapshot/.../{ComponentName}SnapshotTests.swift -->
+<!-- Find reference images: __Snapshots__/{ComponentName}SnapshotTests/*.png -->
+<!-- Copy snapshot PNGs to {confluencePath}/assets/ with ios_ prefix (e.g. ios_light_success.png) -->
+<!-- Group by test category (State Variants, Optional Variants, etc.) -->
+
+<h3>{Category}</h3>
+<table><tbody>
+<tr><th>Variant</th><th>Code</th><th>Light</th><th>Dark</th></tr>
+<!-- Repeat <tr> for each variant in this category -->
+
+<!-- IF SIMPLE component (direct init): -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({param}: .{value}, {param}: .{value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_dark_{variant}.png"/></ac:image></td>
+</tr>
+
+<!-- IF COMPLEX component — check dependencies from component's init: -->
+<!-- No closure deps: ComponentName().modifier(value) -->
+<!-- With closure dep (trailing): ComponentName { action() }.modifier(value) -->
+<!-- With non-closure dep: ComponentName(dep: value).modifier(value) -->
+<!-- With both: ComponentName(dep: value) { action() }.modifier(value) -->
+<!-- Trailing closure is ONLY for closure dependencies, NOT for configuration. -->
+
+<!-- COMPLEX, no closure dependencies: -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({deps})
+    .{modifier}({value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_dark_{variant}.png"/></ac:image></td>
+</tr>
+
+<!-- COMPLEX, with closure dependency (trailing): -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({non-closure deps}) {
+    // closure dependency
+}
+    .{modifier}({value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_dark_{variant}.png"/></ac:image></td>
+</tr>
+<!-- END complexity branching -->
+
+</tbody></table>
+<!-- Code: full component init from test file using default init + chain modifier style. -->
+<!-- {deps}: empty () if no dependencies, or (param: value) for non-closure deps. -->
+<!-- Trailing closure ONLY if component has a closure dependency property. -->
+<!-- {SNAPSHOT_WIDTH}: read from test file's frame width (e.g. width=60 → ac:width="60", width=375 → ac:width="375"). -->
+<!-- Pair light/dark for same variant side by side. -->
+<!-- Group by test category from MARK comments in snapshot test file (e.g. "Loyalty Type Variants", "Size Variants"). -->
+<!-- Skip this section if no snapshot tests exist. -->
+
+<!-- RTL section: always include if RTL snapshot tests exist -->
+<h3>RTL Variants (Arabic)</h3>
+<table><tbody>
+<tr><th>Variant</th><th>Code</th><th>Light</th><th>Dark</th></tr>
+<!-- Repeat <tr> for each RTL variant -->
+
+<!-- IF SIMPLE component: -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({param}: "{arabicText}", {param}: .{value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_dark_{variant}.png"/></ac:image></td>
+</tr>
+
+<!-- IF COMPLEX, no closure dependencies: -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({deps})
+    .text("{arabicText}")
+    .{modifier}({value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_dark_{variant}.png"/></ac:image></td>
+</tr>
+
+<!-- IF COMPLEX, with closure dependency: -->
+<tr>
+<td><strong>{VariantName}</strong></td>
+<td><pre style="background:#f4f5f7; border:1px solid #dfe1e6; border-radius:3px; padding:8px; font-family:SFMono-Regular,Menlo,Monaco,monospace; font-size:12px; margin:0; white-space:pre">{ComponentName}({non-closure deps}) {
+    // closure dependency
+}
+    .text("{arabicText}")
+    .{modifier}({value})</pre></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_light_{variant}.png"/></ac:image></td>
+<td><ac:image ac:width="{SNAPSHOT_WIDTH}"><ri:attachment ri:filename="ios_rtl_dark_{variant}.png"/></ac:image></td>
+</tr>
+<!-- END complexity branching -->
+
+</tbody></table>
+<!-- RTL snapshots use ios_rtl_ prefix. Arabic text from phase-5b Arabic Sample Text table. -->
+
+<hr/>
+
+<h2>Changelog</h2>
+<table><tbody>
+<tr><th>Date</th><th>Change</th></tr>
+<tr><td>{DATE}</td><td>Initial iOS documentation</td></tr>
+</tbody></table>
+```
+
+**IMPORTANT:** Replace all template variables. Remove HTML comments. Output valid XHTML. Include only sections that have data — skip empty sections entirely (don't show "No X" on the iOS page, just omit the section).
+
+---
+
+## GATE 4: VALIDATE_GENERATED_XHTML
+
+Run the validation script to programmatically check both XHTML files, asset integrity, and snapshot coverage.
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/validate-phase7a.py \
+    --confluence-path "{confluencePath}" \
+    --component-name "{ComponentName}"
+```
+
+The script outputs JSON with `status`, `violations`, `warnings`, and `stats`.
+
+### What the script checks
+
+**main.html — Structure:**
+- Required sections: Variants, Overview, Testing Identifiers, Localization Keys, Accessibility, Analytics Events, Sub-Components, Platform Implementations, Changelog
+- Placeholder text accepted for empty sections (e.g., "No testing identifiers")
+
+**ios.html — Structure:**
+- Required sections: Initializer, Usage, Changelog
+- Back-link to main page present
+- Snapshot Tests section present if snapshot assets exist
+
+**Both files — Integrity:**
+- No unreplaced template variables (`{ComponentName}`, `{DESCRIPTION}`, etc.)
+- No remaining template comments (`<!-- IF`, `<!-- END`, `<!-- ELSE`)
+- No unescaped `&` in XML attributes (`ri:filename`, `ri:content-title`)
+- main.html does NOT contain Swift code patterns (`import UIComponents`, `.accessibilityIdentifier(`, `func test_`)
+
+**Asset Reference Integrity:**
+- Every `ri:filename` reference in XHTML has a matching file in `{confluencePath}/assets/`
+- Orphan detection: files in `assets/` not referenced by any XHTML (warning, not failure)
+- `screenshot.png` exists
+
+**Snapshot Coverage (the critical check):**
+- Every snapshot variant has both `ios_light_{variant}.png` AND `ios_dark_{variant}.png` in assets
+- Every snapshot asset file is referenced by an `<ac:image>` tag in ios.html
+- RTL variants: same bidirectional check for `ios_rtl_light_` / `ios_rtl_dark_` pairs
+- Reports: total variants, missing assets, missing references, orphan ios_ assets
+
+### Interpreting results
+
+| `status` | Action |
+|----------|--------|
+| `PASS` | Proceed to GATE 5 |
+| `FAIL` | Fix violations, re-generate XHTML, re-run validation |
+
+`warnings` are informational (orphan assets, unreferenced variant screenshots) — do NOT block.
+`violations` are failures that MUST be fixed before proceeding.
+
+### On failure
+
+Fix each violation in the generated XHTML or asset copy step, then re-run the script. Common fixes:
+- Missing section → add it to the template output
+- Template variable remaining → replace with actual data
+- Snapshot asset missing → re-copy from `__Snapshots__/` directory
+- Snapshot not referenced → add `<ac:image>` row to ios.html Snapshot Tests table
+
+```
+STATUS: HALT
+PHASE: phase-7a
+GATE: VALIDATE_GENERATED_XHTML
+REASON: Generated XHTML validation failed.
+VIOLATIONS: {violations from script JSON}
+WARNINGS: {warnings from script JSON}
+STATS: {stats from script JSON}
+COMPLETED_GATES: [PRE_CHECK, CREATE_STRUCTURE, GENERATE_MAIN_XHTML, GENERATE_IOS_XHTML]
+USER_ACTION_REQUIRED: Fix the violations listed above and re-generate the XHTML.
+```
+
+---
+
+## GATE 5: UPDATE_HISTORY
+
+Append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 7A: Confluence XHTML Generation
+- Status: Complete
+- Main Page: {confluencePath}/main.html
+- iOS Sub-page: {confluencePath}/ios.html
+- Assets: {COUNT} screenshots
+- Validation: Passed (main.html + ios.html structure verified, no template variables remaining)
+- Upload: Pending (run phase-7b or .instructions/figma/figma-to-swiftui/scripts/confluence-publish.py)
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] {confluencePath}/main.html exists and is valid XHTML
+[ ] {confluencePath}/ios.html exists and is valid XHTML
+[ ] {confluencePath}/assets/screenshot.png exists
+[ ] main.html sections: description, TOC, variants (with property values), overview, testing IDs, localization, accessibility, analytics, sub-components, platform implementations, changelog
+[ ] main.html "Variants" section has variant property values (e.g. State=Success) and Figma screenshots
+[ ] main.html does NOT contain: Swift code, .accessibilityIdentifier patterns, import UIComponents
+[ ] ios.html sections: back-link, initializer, usage, iOS utility patterns, code connect, snapshot tests, changelog
+[ ] ios.html "Snapshot Tests" section has light/dark pairs with code from test file
+[ ] ios.html "Snapshot Tests" section uses preferred style (SIMPLE: direct init, COMPLEX: chain modifiers)
+[ ] ios.html "Snapshot Tests" ac:width matches snapshot dimensions from test file
+[ ] ios.html "Snapshot Tests" section includes RTL Variants (Arabic) subsection if RTL tests exist
+[ ] ios.html does NOT contain: testing ID definitions (those are on main page)
+[ ] All template variables replaced with actual data
+[ ] No HTML comments remaining in output
+[ ] All referenced image filenames exist in {confluencePath}/assets/
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 7A entry
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-7a
+GATES_PASSED: [PRE_CHECK, CREATE_STRUCTURE, GENERATE_MAIN_XHTML, GENERATE_IOS_XHTML, VALIDATE_GENERATED_XHTML, UPDATE_HISTORY]
+ARTIFACTS_CREATED:
+  - {confluencePath}/main.html (validated)
+  - {confluencePath}/ios.html (validated)
+  - {confluencePath}/assets/ ({COUNT} screenshots)
+  - {artifactPath}/IMPLEMENTATION_HISTORY.md (updated)
+SUMMARY: Confluence XHTML generated and validated. Main page: {SECTION_COUNT} sections. iOS sub-page: {SECTION_COUNT} sections. {SCREENSHOT_COUNT} assets. Ready for phase-7b upload (requires VPN).
+```