@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/reference/remote-mcp-script.md

@@ -0,0 +1,153 @@
+# REMOTE MCP SCRIPT REFERENCE
+
+Script: `scripts/remote-mcp-fetch.py`
+
+Standalone Python script to call Figma remote MCP (`mcp.figma.com`) from subagents, CI, or any context where Claude MCP tools are unavailable.
+
+---
+
+## Usage
+
+```bash
+python3 scripts/remote-mcp-fetch.py \
+    --tool get_design_context \
+    --file-key "ps4xrJzhn7WNbfkZs895Bi" \
+    --node-id "5:17752" \
+    --output /path/to/output.json
+```
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--tool` | yes | MCP tool name (see below) |
+| `--file-key` | yes | Figma file key from URL |
+| `--node-id` | yes | Node ID (`X:Y` format) |
+| `--mcp-token` | no | OAuth token override |
+| `--output` | no | Write text output to file (omit → stdout) |
+| `--output-image` | no | Write screenshot PNG to file |
+| `--extra-args` | no | JSON string merged into tool arguments |
+
+---
+
+## Supported Tools
+
+| Tool | Output Type | Description |
+|------|-------------|-------------|
+| `get_metadata` | XML text | Layer hierarchy with IDs, types, positions |
+| `get_design_context` | Code text | Reference code + Code Connect snippets |
+| `get_variable_defs` | JSON text | Resolved design token values |
+| `get_code_connect_map` | JSON text | Component-to-source mappings |
+| `get_screenshot` | PNG image | Visual snapshot of node |
+
+---
+
+## Token Resolution Chain
+
+The script resolves the OAuth token in this order:
+
+1. **`--mcp-token` CLI arg** — explicit token passed at invocation
+2. **Keychain `FIGMA_MCP_TOKEN`** — dedicated entry stored by `/figma-setup` (CHECK 3b)
+3. **Keychain `Claude Code-credentials`** — extracts `figma-remote` OAuth token via regex
+
+Fallback #2 is fast (direct keychain lookup). Fallback #3 works but parses a large JSON blob.
+Run `/figma-setup` to pre-store the token for fast access.
+
+---
+
+## Token Details
+
+- **Type:** OAuth access token (NOT a personal access token)
+- **Prefix:** `figu_` (vs `figd_` for PATs)
+- **Source:** Claude Code's MCP OAuth flow for `figma-remote` server
+- **PATs do NOT work** with remote MCP — always returns 401
+
+---
+
+## Protocol
+
+- **Endpoint:** `https://mcp.figma.com/mcp`
+- **Auth:** `Authorization: Bearer <figu_token>`
+- **Protocol:** JSON-RPC 2.0 over HTTP with SSE responses
+- **Stateless:** Each call does `initialize` + `tools/call` (no session persistence)
+- **Default params:** `clientLanguages=swift`, `clientFrameworks=swiftui`
+
+### Request Flow
+
+```
+1. POST /mcp  →  {"method": "initialize", ...}  →  HTTP 200 (SSE)
+2. POST /mcp  →  {"method": "tools/call", "params": {"name": "<tool>", "arguments": {...}}}  →  HTTP 200 (SSE)
+```
+
+### SSE Response Parsing
+
+Response body contains SSE events. The JSON payload is in the `data:` line and may span multiple physical lines (embedded newlines in text content). The script handles this by finding the `data:` prefix and parsing the full JSON object.
+
+---
+
+## Examples
+
+**Get metadata:**
+```bash
+python3 scripts/remote-mcp-fetch.py \
+    --tool get_metadata \
+    --file-key ps4xrJzhn7WNbfkZs895Bi \
+    --node-id "5:17752" \
+    --output artifacts/metadata_response.xml
+```
+
+**Get design context with force-code:**
+```bash
+python3 scripts/remote-mcp-fetch.py \
+    --tool get_design_context \
+    --file-key ps4xrJzhn7WNbfkZs895Bi \
+    --node-id "1411:18186" \
+    --extra-args '{"forceCode": true}' \
+    --output artifacts/design_context_response.json
+```
+
+**Get screenshot:**
+```bash
+python3 scripts/remote-mcp-fetch.py \
+    --tool get_screenshot \
+    --file-key ps4xrJzhn7WNbfkZs895Bi \
+    --node-id "5:17752" \
+    --output-image artifacts/screenshot.png
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Failure (JSON error printed to stderr) |
+
+---
+
+## Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `no_mcp_token` | No token found in any fallback | Run `/figma-setup` or pass `--mcp-token` |
+| `MCP init failed: HTTP 401` | Token expired or invalid | Re-authenticate figma-remote in Claude Code, re-run `/figma-setup` |
+| `MCP <tool>: HTTP 4xx` | Bad request or auth failure | Check file-key, node-id, token validity |
+| `An unexpected error occurred` | Figma server-side error | Retry; check node-id exists in file |
+
+---
+
+## Local vs Remote MCP Comparison
+
+| Aspect | Local MCP | Remote MCP (this script) |
+|--------|-----------|--------------------------|
+| Endpoint | `http://127.0.0.1:3845/mcp` | `https://mcp.figma.com/mcp` |
+| Auth | None | OAuth Bearer token |
+| `fileKey` required | No (uses open file) | Yes (always) |
+| `dirForAssetWrites` | Supported (writes SVGs to disk) | Not supported (returns URLs) |
+| Requires Figma Desktop | Yes | No |
+| Works in subagents/CI | Yes (HTTP) | Yes (HTTP) |
+| Code Connect output | Returns ALL platforms | Filters by target platform |
+| Rate limits | Daily cap (varies) | Per plan (see tools.md §1.7) |

package/pipeline/skills/figma-ios/figma-to-component/reference/rest-api-script.md

@@ -0,0 +1,130 @@
+# FIGMA REST API — SCRIPT USAGE REFERENCE
+
+How the Phase 1 script (`scripts/phase1-gather.py`) uses the Figma REST API for data that MCP doesn't efficiently provide.
+
+---
+
+## Auth
+
+```bash
+# Token stored in macOS Keychain by /figma-setup (CHECK 4)
+TOKEN=$(security find-generic-password -a "$USER" -s "FIGMA_ACCESS_TOKEN" -w)
+```
+
+```python
+# In scripts:
+token = subprocess.check_output(
+    ["security", "find-generic-password", "-a", os.environ["USER"],
+     "-s", "FIGMA_ACCESS_TOKEN", "-w"],
+    stderr=subprocess.DEVNULL,
+).decode().strip()
+```
+
+**Header:** `X-Figma-Token: <token>` (NOT `Authorization: Bearer`)
+
+---
+
+## Endpoints Used by Phase 1 Script
+
+### 1. Node Data — Component Properties
+
+```
+GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}
+```
+
+Returns full node JSON including `componentPropertyDefinitions` for the component set. The script processes this into `component_properties.json` with variant axes, types, and default values.
+
+**Why REST not MCP:** MCP `get_design_context` returns code, not raw component property definitions. REST gives the structured node data needed for variant enumeration.
+
+---
+
+### 2. Screenshot Export — Single Node
+
+```
+GET https://api.figma.com/v1/images/{fileKey}?ids={nodeId}&format=png&scale=2
+```
+
+Returns JSON with `images` map: `{ "nodeId": "https://...s3.amazonaws.com/..." }`. The script downloads the URL to save as `screenshot.png`.
+
+**Why REST not MCP:** MCP `get_screenshot` returns base64 inline (works but larger payload). REST returns a URL — better for scripts that save to disk.
+
+---
+
+### 3. Batch Screenshot Export — Variants
+
+```
+GET https://api.figma.com/v1/images/{fileKey}?ids={id1},{id2},{id3},...&format=png&scale=2
+```
+
+Same endpoint, comma-separated IDs. Returns all image URLs in one call. The script downloads each to `screenshots/VariantName.png`.
+
+**Why batch:** A component with 288 variants would need 288 individual MCP `get_screenshot` calls. The REST batch endpoint returns all URLs in one request (~2-3s total).
+
+---
+
+### 4. Variable Definitions (Fallback)
+
+```
+GET https://api.figma.com/v1/files/{fileKey}/variables/local
+```
+
+**Note:** Returns 403 on non-Enterprise Figma plans. The script uses MCP `get_variable_defs` as primary, falls back to this endpoint, and writes an error placeholder if both fail.
+
+---
+
+## Rate Limits
+
+The REST API has no documented hard rate limit for PAT-authenticated requests. In practice:
+- Parallel requests work fine (script uses `ThreadPoolExecutor(max_workers=10)`)
+- Batch image endpoint is preferred over individual calls
+- No 429s observed during testing with 288-variant batch exports
+
+---
+
+## Script Integration Pattern
+
+```python
+# Standard request helper from phase1-gather.py
+def figma_api(path):
+    """GET from Figma REST API. Returns parsed JSON."""
+    url = f"https://api.figma.com/v1{path}"
+    req = Request(url, headers={"X-Figma-Token": FIGMA_TOKEN})
+    with urlopen(req, timeout=60) as resp:
+        return json.loads(resp.read().decode())
+
+# Node data
+data = figma_api(f"/files/{FILE_KEY}/nodes?ids={NODE_ID}")
+
+# Batch images
+ids_param = ",".join(variant_ids)
+data = figma_api(f"/images/{FILE_KEY}?ids={ids_param}&format=png&scale=2")
+for node_id, url in data["images"].items():
+    download(url, f"screenshots/{variant_name}.png")
+```
+
+---
+
+## REST vs MCP — When to Use What
+
+| Data | Use REST | Use MCP | Reason |
+|------|----------|---------|--------|
+| Component properties/variants | yes | — | MCP doesn't expose raw property defs |
+| Screenshot (single) | ok | ok | Both work; MCP is simpler for inline use |
+| Screenshots (batch) | yes | — | One REST call vs N MCP calls |
+| Design context (code) | — | yes | MCP generates reference code |
+| Metadata (XML hierarchy) | — | yes | MCP returns structured XML |
+| Variable definitions | fallback | primary | MCP preferred; REST 403 on non-Enterprise |
+| Code Connect mappings | — | yes | MCP-only feature |
+
+---
+
+## Error Handling
+
+| Status | Meaning | Script Action |
+|--------|---------|---------------|
+| 200 | Success | Parse JSON response |
+| 400 | Bad request | Log error, halt gate |
+| 403 | Forbidden / no access | Log warning, skip (e.g., variables endpoint) |
+| 404 | File/node not found | Halt with user action |
+| 429 | Rate limited | Not observed in practice |
+| 5xx | Server error | Retry once, then halt |

package/pipeline/skills/figma-ios/figma-to-component/reference/scripts-inventory.md

@@ -0,0 +1,218 @@
+# SCRIPTS INVENTORY
+
+All scripts in `.instructions/figma/figma-to-swiftui/scripts/`. Each replaces slow LLM subagent turns with deterministic, fast execution.
+
+---
+
+## Data Gathering
+
+### `phase1-gather.py` — Phase 1 Data Collection
+
+Replaces the Phase 1 LLM subagent. Collects all Figma data for a component in one run.
+
+```bash
+python3 scripts/phase1-gather.py \
+    --file-key "ps4xrJzhn7WNbfkZs895Bi" \
+    --node-id "5:17752" \
+    --artifact-path "path/to/ComponentName/" \
+    --component-name "Button" \
+    [--figma-token TOKEN] \
+    [--mcp-url "http://127.0.0.1:3845/mcp"]
+```
+
+| Aspect | Detail |
+|--------|--------|
+| Runtime | 5-15s (small), 25-40s (large/288 variants) |
+| Data sources | Local MCP (HTTP) + REST API |
+| Auth | `FIGMA_ACCESS_TOKEN` from Keychain + local MCP (no auth) |
+| Output | JSON summary to stdout, artifacts to `--artifact-path` |
+
+**Artifacts produced:**
+
+| File | Source |
+|------|--------|
+| `pass1/screenshot.png` | REST API `/v1/images` |
+| `pass1/metadata_response.xml` | MCP `get_metadata` |
+| `pass1/design_context_response.json` | MCP `get_design_context` |
+| `pass1/design_context_assets.txt` | Asset URL list from design context |
+| `pass1/variable_defs_response.json` | MCP `get_variable_defs` → REST fallback |
+| `pass1/code_connect_map_response.json` | MCP `get_code_connect_map` |
+| `pass1/component_properties.json` | REST API `/v1/files/.../nodes` (processed) |
+| `pass1/component_summary.json` | Compiled from all above |
+| `pass1/screenshots/*.png` | REST API batch image export |
+
+**Key features:**
+- Sublayer auto-split: If `get_design_context` returns "too large" XML, recursively splits into sublayer calls (max depth 3)
+- Parallel variant screenshots: `ThreadPoolExecutor(max_workers=10)`
+- Variable defs fallback: MCP → REST API (403 on non-Enterprise) → error placeholder
+
+---
+
+### `remote-mcp-fetch.py` — Remote MCP Tool Caller
+
+Calls Figma remote MCP from any context (subagents, CI, scripts). See `reference/remote-mcp-script.md` for full docs.
+
+```bash
+python3 scripts/remote-mcp-fetch.py \
+    --tool get_design_context \
+    --file-key "ps4xrJzhn7WNbfkZs895Bi" \
+    --node-id "5:17752" \
+    --output output.json
+```
+
+| Aspect | Detail |
+|--------|--------|
+| Runtime | 2-10s per call |
+| Auth | OAuth token: `--mcp-token` → Keychain `FIGMA_MCP_TOKEN` → Claude Code credentials |
+| Tools | `get_metadata`, `get_design_context`, `get_variable_defs`, `get_code_connect_map`, `get_screenshot` |
+
+---
+
+## Phase Processing
+
+### `phase2-finalize.py` — Phase 2 Finalization
+
+Builds `component-utilities.json` from Phase 2 sub-phase JSON sidecars and registers with FigmaRegistryUtility.
+
+```bash
+python3 scripts/phase2-finalize.py \
+    --artifact-path /path/to/artifacts \
+    --node-id "9047:386" \
+    --file-key "ps4xrJzhn7WNbfkZs895Bi" \
+    --component-name "AvatarMembership"
+```
+
+| Input | Output |
+|-------|--------|
+| `pass2/utility_identifiers.json` (2A) | `pass2/component-utilities.json` |
+| `pass2/utility_localization.json` (2B) | `pass2/_index.md` |
+| `pass2/utility_accessibility.json` (2C) | Registry entry (via CLI) |
+| `pass2/utility_analytics.json` (2D) | |
+
+---
+
+### `phase3-scripts.py` — Phase 3 Scriptable Sub-Phases
+
+Runs deterministic Phase 3 sub-phases that don't need AI reasoning.
+
+```bash
+python3 scripts/phase3-scripts.py 3b --artifact-path /path   # Token mapping
+python3 scripts/phase3-scripts.py 3e --artifact-path /path   # Asset inventory
+python3 scripts/phase3-scripts.py 3f --artifact-path /path   # Utility integration
+python3 scripts/phase3-scripts.py 3g --artifact-path /path   # Coverage check
+python3 scripts/phase3-scripts.py wave1 --artifact-path /path # 3b+3e+3f together
+```
+
+| Sub-command | Phase | What it does | Runtime |
+|-------------|-------|-------------|---------|
+| `3b` | Token Mapping | Parses `variable_defs_response.json` → CLI lookup → `02_token_mapping.md` | <0.1s |
+| `3e` | Assets | Parses asset list → CLI lookup → identifies existing assets → `06_assets.md` | <0.1s |
+| `3f` | Utilities | Reads `component-utilities.json` → formats → `08_utility_integration.md` | <0.1s |
+| `3g` | Coverage | Reads `component_properties.json` + `04b_component_architecture.json` → diff → coverage report | <0.1s |
+| `wave1` | 3b+3e+3f | Parallel run of all three | <0.2s |
+
+---
+
+## Validation
+
+### `validate-phase4.sh` — Phase 4 Output Validation
+
+Checks Phase 4 (code generation) output for completeness.
+
+```bash
+bash scripts/validate-phase4.sh /path/to/artifacts
+```
+
+### `validate-phase6.sh` — Phase 6 Output Validation
+
+Checks Phase 6 (Code Connect) output for completeness.
+
+```bash
+bash scripts/validate-phase6.sh /path/to/artifacts
+```
+
+### `code-connect-publish.sh` — Resilient Code Connect Publish
+
+Wrapper around `npx figma connect publish` that auto-excludes stale components causing validation failures, retries once, and restores `figma.config.json` via trap.
+
+```bash
+bash scripts/code-connect-publish.sh [--dry-run]
+```
+
+Must be run from the uicomponents package root. Requires `FIGMA_ACCESS_TOKEN` env var.
+
+---
+
+## Utilities
+
+### `sync-skills.sh` — Sync Skill Files
+
+Copies `.instructions/figma/figma-to-swiftui/` to `.gemini/skills/figma/` and `.github/skills/figma/`.
+
+```bash
+bash scripts/sync-skills.sh
+```
+
+### `run-uicomponents-tests.sh` — Run UIComponents Tests
+
+Runs the Swift test suite for the UIComponents package.
+
+```bash
+bash scripts/run-uicomponents-tests.sh
+```
+
+---
+
+## Code Connect
+
+### `register-icons-codeconnect.py` — Batch Icon Registration
+
+Registers icon assets in Figma via Code Connect.
+
+```bash
+python3 scripts/register-icons-codeconnect.py [options]
+```
+
+### `figma-subcomponent-graph.py` — Component Dependency Graph
+
+Builds a graph of nested component dependencies from Figma metadata.
+
+```bash
+python3 scripts/figma-subcomponent-graph.py [options]
+```
+
+---
+
+## Confluence
+
+### `confluence-publish.py` — Publish to Confluence
+
+Publishes component documentation to Confluence.
+
+```bash
+python3 scripts/confluence-publish.py [options]
+```
+
+### `confluence-component-status.py` — Component Status Tracker
+
+Tracks implementation status across components in Confluence.
+
+```bash
+python3 scripts/confluence-component-status.py [options]
+```
+
+### `confluence-page-ids.json` — Page ID Mapping
+
+Static JSON mapping of Confluence page IDs for documentation targets.
+
+---
+
+## Performance Summary
+
+| Script | Replaces | Old Time | New Time | Speedup |
+|--------|----------|----------|----------|---------|
+| `phase1-gather.py` | Phase 1 LLM subagent | ~20 min | 5-40s | ~30-240x |
+| `phase2-finalize.py` | Phase 2 orchestrator merge | ~2 min | <1s | ~120x |
+| `phase3-scripts.py` (wave1) | Phase 3 AI agents (3B+3E+3F) | ~3 min | 0.2s | ~900x |
+| `phase3-scripts.py` (3g) | Phase 3G AI agent | ~1 min | <0.1s | ~600x |
+| `remote-mcp-fetch.py` | Inline MCP calls (chat only) | N/A | 2-10s | Enables subagent/CI use |

package/pipeline/skills/figma-ios/figma-to-component/reference/snapshot-testing.md

@@ -0,0 +1,188 @@
+# SNAPSHOT TESTING REFERENCE
+
+Point-Free swift-snapshot-testing for SwiftUI visual regression testing.
+
+Package: `https://github.com/pointfreeco/swift-snapshot-testing`
+Version: `1.17.6` (latest as of Aug 2025)
+License: MIT
+
+---
+
+## FRAMEWORK SUPPORT
+
+| Framework | Supported |
+|-----------|-----------|
+| XCTest | Yes |
+| Swift Testing | Yes (auto-detects context) |
+
+---
+
+## BASIC USAGE
+
+### XCTest
+
+```swift
+import SnapshotTesting
+import SwiftUI
+import XCTest
+
+final class MyComponentTests: XCTestCase {
+    func testDefaultState() {
+        let view = MyComponent(title: "Hello")
+        let vc = UIHostingController(rootView: view)
+        vc.view.frame = CGRect(x: 0, y: 0, width: 375, height: 100)
+        assertSnapshot(of: vc, as: .image)
+    }
+}
+```
+
+### Swift Testing
+
+```swift
+import SnapshotTesting
+import SwiftUI
+import Testing
+
+@Suite(.snapshots(record: .missing))
+struct MyComponentTests {
+    @Test func defaultState() {
+        let vc = UIHostingController(rootView: MyComponent(title: "Hello"))
+        vc.view.frame = CGRect(x: 0, y: 0, width: 375, height: 100)
+        assertSnapshot(of: vc, as: .image)
+    }
+}
+```
+
+---
+
+## RECORD MODES
+
+| Mode | Behavior |
+|------|----------|
+| `.missing` | Record only if snapshot doesn't exist |
+| `.all` | Overwrite all existing snapshots |
+| `.never` | Fail if missing (CI mode) |
+| `.failed` | Re-record only failed snapshots |
+
+**XCTest:** `withSnapshotTesting(record: .missing) { super.invokeTest() }`
+**Swift Testing:** `@Suite(.snapshots(record: .missing))`
+
+---
+
+## STRATEGIES
+
+```swift
+// Basic
+assertSnapshot(of: vc, as: .image)
+
+// With precision
+assertSnapshot(of: vc, as: .image(precision: 0.99, perceptualPrecision: 0.98))
+
+// Device-specific
+assertSnapshot(of: vc, as: .image(on: .iPhone13Pro))
+```
+
+| Device | Constant |
+|--------|----------|
+| iPhone SE | `.iPhoneSe` |
+| iPhone 13 Pro | `.iPhone13Pro` |
+| iPhone 13 Pro Max | `.iPhone13ProMax` |
+| iPad Pro 12.9" | `.iPadPro12_9` |
+| iPad Mini | `.iPadMini` |
+
+---
+
+## SNAPSHOT STORAGE
+
+```
+Tests/<Module>Tests/
+├── __Snapshots__/
+│   └── MyComponentTests/
+│       ├── testDefaultState.1.png
+│       └── testDisabledState.1.png
+└── MyComponentTests.swift
+```
+
+---
+
+## VARIANT AND THEME TESTING
+
+```swift
+// All variants
+for variant in MyComponent.Variant.allCases {
+    let vc = UIHostingController(rootView: MyComponent(variant: variant))
+    vc.view.frame = CGRect(x: 0, y: 0, width: 375, height: 100)
+    assertSnapshot(of: vc, as: .image, named: variant.rawValue)
+}
+
+// Dark mode
+vc.overrideUserInterfaceStyle = .dark
+assertSnapshot(of: vc, as: .image, named: "dark")
+```
+
+---
+
+## FAILURE OUTPUT
+
+| File | Content |
+|------|---------|
+| `testName.1.png` | Reference (expected) |
+| `testName.1.failed.png` | Actual (current) |
+| `testName.1.diff.png` | Difference highlighted |
+
+---
+
+## DI REGISTRATION FOR TESTS
+
+Snapshot tests run in SPM package context — no AppDelegate, no DI registration. Use `TestDependencies` helper to register providers before tests.
+
+```swift
+override class func setUp() {
+    super.setUp()
+    TestDependencies.registerAll()  // registers LocalizedStringProvider + CurrencyFormatProvider + AppLanguageCodeProvider
+}
+```
+
+`TestDependencies` is at `Tests/UIComponentsTests/TestDependencies.swift`.
+
+---
+
+## RTL TESTING WITH ARABIC LOCALIZATION
+
+For RTL snapshot tests, override the app language to Arabic so localized labels render in Arabic (not system language):
+
+```swift
+func test_snapshot_rtl_light_default() {
+    TestDependencies.setLanguage("ar")
+    let sut = makeSUT()
+    assertSnapshotRTL(sut, named: "rtl_light_default")
+    TestDependencies.resetLanguage()
+}
+```
+
+**CRITICAL:** `String(localized:bundle:locale:)` does NOT select translation language — the `locale` parameter only affects interpolated value formatting. The `DevelopmentLocalizedStringProvider` uses `Bundle.localizedString(forKey:value:table:)` with a language-specific `.lproj` sub-bundle to correctly resolve translations by language.
+
+**RTL snapshot helper pattern:**
+
+```swift
+private func assertSnapshotRTL(_ view: some View, named name: String) {
+    let rtlView = view.environment(\.layoutDirection, .rightToLeft)
+    let vc = UIHostingController(rootView: rtlView)
+    vc.view.frame = CGRect(x: 0, y: 0, width: 375, height: 0)
+    vc.view.semanticContentAttribute = .forceRightToLeft
+    vc.view.sizeToFit()
+    vc.view.layoutIfNeeded()
+    SnapshotTesting.assertSnapshot(of: vc, as: .image(precision: 0.99, perceptualPrecision: 0.98), named: name)
+}
+```
+
+---
+
+## COMMON ISSUES
+
+| Issue | Solution |
+|-------|----------|
+| Font rendering differs on CI | Use `perceptualPrecision: 0.98` |
+| Snapshot not found | Run with `record: .missing` first |
+| Size mismatch | Set explicit frame on UIHostingController |
+| Dark mode not applied | Set `overrideUserInterfaceStyle` |