@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-validate/SKILL.md

@@ -0,0 +1,633 @@
+---
+name: figma-validate
+description: "Pre-implementation validation for Figma components. Checks 7 criteria: (1) Registry presence, (2) Code Connect strategy, (3) Design token compliance, (4) Dependency readiness, (5) Atomic scope, (6) iOS applicability, (7) Already-implemented check. Plus Implementation Intel: complexity score, text node count, image detection, discarded version, wiki status, sibling progress. Target: ≤10s."
+user-invocable: true
+argument-hint: <figma-url> | <github-issue> | batch [--verbose]
+allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-validate
+---
+
+# /figma-validate — Pre-Implementation Component Validation
+
+## Purpose
+
+Validates whether a Figma component is ready for the figma-to-swiftui implementation pipeline.
+Runs 6 criteria checks and returns a verdict: **VALID**, **CONDITIONAL**, or **INVALID**.
+
+This is a **read-only diagnostic skill** — it does NOT modify any files.
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Figma URL | Yes (single mode) | `https://www.figma.com/design/{fileKey}/...?node-id={nodeId}` |
+| GitHub Issue | Yes (single mode) | Issue number from uicomponents repo (e.g., `#260`, `260`) |
+| `batch` | No | Validate all unimplemented components in registry |
+| `--verbose` | No | Show detailed property analysis per criterion |
+
+```
+/figma-validate https://www.figma.com/design/ps4xrJzhn7WNbfkZs895Bi/?node-id=11400-406
+/figma-validate #260
+/figma-validate 260
+/figma-validate batch
+/figma-validate batch --verbose
+```
+
+---
+
+## Constants
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+COMMON_PATH="${REPO_ROOT}/{repos.common.path}"
+UICOMPONENTS_PATH="${REPO_ROOT}/{repos.components.path}"
+REGISTRY="${COMMON_PATH}/Shared/Figma/Generated/component-registry.json"
+REGISTRY_CONFIG="${COMMON_PATH}/Shared/Figma/figma-components-registry-config.json"
+GH_REPO="{github.componentsRepo}"
+```
+
+---
+
+## Parse Arguments
+
+| Input Pattern | Mode | Action |
+|---------------|------|--------|
+| `https://www.figma.com/...` | **Single (URL)** | Extract fileKey + nodeId from URL |
+| `#N` or bare number | **Single (Issue)** | Fetch Figma URL from GitHub issue body |
+| `batch` | **Batch** | Validate all unimplemented registry components |
+| `batch --verbose` | **Batch Verbose** | Batch with full per-criterion details |
+
+### Input Detection
+
+```
+if input matches /^https:\/\/www\.figma\.com/   → URL mode
+if input matches /^#?\d+$/                       → GitHub Issue mode
+if input == "batch"                              → Batch mode
+```
+
+### URL Parsing (URL mode)
+
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `11400-406` → `11400:406`).
+
+### GitHub Issue Resolution (Issue mode)
+
+```bash
+gh issue view <N> --repo ${GH_REPO} --json number,title,body
+```
+
+Extract from the issue body:
+- **Figma URL** — from the line after `### Figma URL` heading
+- **Component Name** — from `### Component Name (PascalCase)` section (informational)
+
+```python
+import json, re
+body = issue_data['body']
+# Extract Figma URL
+figma_match = re.search(r'### Figma URL\s+\n(https://www\.figma\.com/design/[^\s]+)', body)
+if figma_match:
+    figma_url = figma_match.group(1)
+    # Parse fileKey and nodeId from URL
+    url_match = re.match(r'https://www\.figma\.com/design/([^/]+)/.*\?node-id=([^&\s]+)', figma_url)
+    file_key = url_match.group(1)
+    node_id = url_match.group(2).replace('-', ':')
+```
+
+If Figma URL is not found or is `_No response_` → ask user for URL via AskUserQuestion.
+
+Print resolved info before proceeding to validation:
+```
+───────────────────────────────────────────
+  Source:     GitHub Issue #<N>
+  Title:      <issue_title>
+  Figma URL:  <extracted_url>
+  File Key:   <fileKey>
+  Node ID:    <nodeId>
+───────────────────────────────────────────
+```
+
+---
+
+## Validation Criteria
+
+Seven criteria are checked. Each returns ✅ (pass) or ❌ (fail) with a reason.
+
+---
+
+### Criterion 1 — Component Registry Presence
+
+**Question:** Component registry'de (`component-registry.json`) yer alıyor mu?
+
+**Check:**
+
+1. Read `$REGISTRY` and search for an entry whose `nodeId` matches the parsed node ID.
+2. If found → ✅ PASS. Record `name`, `fileName`, `pageName`, `parentPage`, `basePath`.
+3. If not found → ❌ FAIL. Reason: "Component not found in registry. Run `FigmaRegistryUtility update` or verify the Figma URL."
+
+Also check `excludePatterns` in `$REGISTRY_CONFIG`:
+- If the component's `pageName` or `sectionName` matches an exclude pattern → ❌ FAIL. Reason: "Component is in an excluded page: {pageName}."
+
+**Known valid file keys** (from registry config):
+- `ps4xrJzhn7WNbfkZs895Bi` — Design System Core
+- `9ipBvrtsq9HlQ175B9k0wx` — Mobile App Components
+- `YSs4g0EeGAW53haB0zz5sa` — Visual Assets
+
+If the URL's `fileKey` does not match any of these → ❌ FAIL. Reason: "Unknown Figma file. Only Design System Core, Mobile App Components, and Visual Assets are supported."
+
+**Pass Condition:** Component exists in registry, is NOT in an excluded page, and belongs to a known Figma file.
+
+---
+
+### Criterion 2 — Figma Property Structure & Code Connect Strategy
+
+**Question:** Uygulanabilir bir Code Connect stratejisi var mı?
+
+**Check:**
+
+1. Fetch component data via Figma REST API:
+   ```python
+   # Use python3 urllib.request — curl may be blocked by policy
+   import subprocess, urllib.request, json
+   token = subprocess.check_output(
+       ["security", "find-generic-password", "-s", "FIGMA_ACCESS_TOKEN", "-w"],
+       text=True
+   ).strip()
+   req = urllib.request.Request(
+       f"https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}",
+       headers={"X-Figma-Token": token}
+   )
+   data = json.loads(urllib.request.urlopen(req).read())
+   ```
+2. Determine the component type from the response:
+   - **`COMPONENT_SET`** → has variants → classify properties:
+     - Variant properties → `@FigmaEnum`
+     - Text properties → `@FigmaString`
+     - Boolean properties → `@FigmaBoolean`
+     - Instance swap properties → `@FigmaInstance`
+   - **`COMPONENT`** (plain, no variants) → uses **STATIC_VALUES** strategy
+3. Determine Code Connect strategy:
+
+| Figma Type | Properties | Strategy | C2 Result |
+|------------|-----------|----------|-----------|
+| `COMPONENT_SET` | ≥1 property | Property Mapping | ✅ PASS |
+| `COMPONENT_SET` | 0 properties | Unexpected | ❌ FAIL |
+| `COMPONENT` | 0 properties | STATIC_VALUES | ✅ PASS |
+| `COMPONENT` | N/A | STATIC_VALUES | ✅ PASS |
+
+**Pass Condition:** Component has a valid Code Connect strategy — either property mapping (for COMPONENT_SET with ≥1 property) or STATIC_VALUES (for plain COMPONENT).
+
+**Output:** Always report the detected strategy in the result:
+- `✅ STATIC_VALUES — plain COMPONENT, no variant properties (uses static preview in .figma.swift)`
+- `✅ Property Mapping — 3 enum, 1 string, 2 bool`
+- `❌ COMPONENT_SET with 0 properties — unexpected, needs design review`
+
+**Warning Flags** (informational, not failures):
+- Property named `"Property 1"` → flag as `UNNAMED_PROPERTY`: "Unnamed property detected — design team should rename."
+- Property values with likely typos (e.g., `"Standart"`, `"Clasic Plus"`) → flag as `TYPO_DETECTED`.
+
+**Fallback:** If Figma API is unreachable, mark criterion as ⚠️ SKIPPED. Do NOT fail the entire validation.
+
+---
+
+### Criterion 3 — Design Token Compliance
+
+**Question:** Renkler/spacing/typography design token kullanıyor mu?
+
+**Check:**
+
+1. From Figma node data, extract:
+   - **Fill colors** — check if they correspond to known design token hex values
+   - **Text styles** — check if they match `UIAssetTokens` typography styles
+   - **Spacing values** — check if padding/gap values are standard multiples: 2, 4, 8, 12, 16, 24, 32, 48
+   - **Corner radius** — check if values match known radius tokens: 4, 8, 12, 16, 24
+2. Optionally cross-reference with the token index:
+   ```bash
+   cd "${COMMON_PATH}" && .build/debug/FigmaRegistryUtility uitoken-index 2>/dev/null
+   ```
+
+**Pass Condition:** No hardcoded hex colors outside the design token palette. Spacing uses standard increments.
+
+**Soft Pass:** If token verification is not possible from the API response, mark as ⚠️ ASSUMED PASS with note: "Token compliance could not be fully verified from API — manual visual check recommended."
+
+---
+
+### Criterion 4 — Nested Dependency Readiness
+
+**Question:** Bağımlı olduğu alt bileşenler zaten implemente mi?
+
+**Check:**
+
+1. From Figma node data, inspect child nodes for component instances (type `INSTANCE`).
+2. For each child instance, extract its `componentId`.
+3. **Resolve the componentId** to a searchable ID using the `components` metadata from the API response.
+4. **Search for implementation** using the decision tree below.
+
+#### Step 3 — ComponentId Resolution (CRITICAL)
+
+Figma INSTANCE nodes reference a **variant's node ID** (`componentId`), NOT the COMPONENT_SET's node ID. The API response includes a `components` metadata map at `data.nodes[nodeId].components` that provides the `componentSetId` for each variant.
+
+```python
+# API response structure
+api_components = data['nodes'][node_id].get('components', {})
+
+for component_id, name in unique_instances.items():
+    meta = api_components.get(component_id, {})
+    component_set_id = meta.get('componentSetId', '')
+    
+    # Resolution order:
+    # 1. Try componentId directly in registry
+    # 2. If not found AND componentSetId exists → try componentSetId in registry
+    # 3. If still not found → try componentId in COMMON Components/{id}.json
+    # 4. If still not found → search by component name in registry and COMMON
+    # 5. If still not found → search Regroup/ by name
+    
+    search_ids = [component_id]
+    if component_set_id:
+        search_ids.append(component_set_id)
+```
+
+**Why this matters:** A Logo component set registered as `nodeId=14:619` in the registry may be referenced via its variant `componentId=1338:1632` (e.g., `Color=White`). Without resolving through `componentSetId`, the lookup fails with a false "unknown" result.
+
+#### Dependency Resolution Decision Tree
+
+For each child `componentId`, look it up in the component registry (`component-registry.json`) by `nodeId`. Then apply this decision tree:
+
+```
+                    ┌──────────────────────┐
+                    │  Found in registry?  │
+                    └──────┬───────────────┘
+                     yes   │          no
+              ┌────────────┴──┐    ┌──────────────────────────────┐
+              │  Check fileKey │    │ Check Components/{nodeId}.json│
+              └──┬────────────┘    │ in COMMON_PATH               │
+                 │                 └──────────┬───────────────────┘
+    ┌────────────┼────────────┐          found │         not found
+    │            │            │               │              │
+  VA (Y…sa)  DSC (p…Bi)  MAC (9…wx)    ┌─────┴──────┐   UNKNOWN
+    │            │            │         │status.ios. │   (warn)
+    ▼            ▼            ▼         │implemented │
+  COMMON     UICOMP       UICOMP        │.value=true?│
+                                        └──┬──────┬──┘
+                                        yes│     no│
+                                       COMMON   UICOMP
+```
+
+**File key mapping:**
+
+| File Key | File Name | Primary Location | Content Type |
+|----------|-----------|-----------------|--------------|
+| `YSs4g0EeGAW53haB0zz5sa` | Visual Assets | **COMMON** | Icons, Logos, Other Visual Assets |
+| `ps4xrJzhn7WNbfkZs895Bi` | Design System Core | **UICOMP** | Core UI components |
+| `9ipBvrtsq9HlQ175B9k0wx` | Mobile App Components | **UICOMP** | Flow-based / app-specific components |
+
+**Registry-based shortcuts** (parentPage check — no filesystem search needed):
+
+| `parentPage` value | Location | Verification |
+|--------------------|----------|-------------|
+| `"Icons"` | COMMON | ✅ Auto-pass (registered icon) |
+| `"Logos"` | COMMON | Check `Components/{nodeId}.json` or `Regroup/` |
+| `"Other Visual Assets"` | COMMON | Check `Components/{nodeId}.json` |
+| `"Components"`, `"-"`, `""` | UICOMP | Search `.figma.swift` on `iteration/develop` |
+| `"Flow Based Components"` | UICOMP | Search `.figma.swift` on `iteration/develop` |
+
+#### Verification per location
+
+**COMMON path** (`${COMMON_PATH}/Shared/Figma/`):
+```bash
+# IMPORTANT: Search on iteration/develop, not current HEAD
+cd "${COMMON_PATH}"
+NODE_DASH="${nodeId//:/-}"
+# 1. Check Components/{nodeId}.json — new status.ios.implemented.value (architecture-update)
+#    with legacy codeConnect.ios fallback for pre-backfill entries
+git show iteration/develop:Shared/Figma/Components/${NODE_DASH}.json 2>/dev/null | \
+  python3 -c "
+import json,sys
+d = json.load(sys.stdin)
+# preferred: new status block
+ios = (d.get('status') or {}).get('ios') or {}
+impl = (ios.get('implemented') or {}).get('value')
+# fallback: legacy codeConnect.ios flag (kept in sync by registry_writer)
+if impl is None:
+    impl = (d.get('codeConnect') or {}).get('ios', False)
+print('implemented:', bool(impl), 'skip:', d.get('skip', False))
+"
+# 2. Also search registry and component-catalog on iteration/develop
+git grep -l "${nodeId}" iteration/develop -- 'Shared/Figma/Generated/*.json' 2>/dev/null
+```
+
+**UICOMP path** (`${UICOMPONENTS_PATH}/Sources/`):
+```bash
+# IMPORTANT: Search on iteration/develop, not current HEAD
+cd "${UICOMPONENTS_PATH}"
+# 1. Search .figma.swift files for nodeId on iteration/develop
+git grep -l "${nodeId}" iteration/develop -- '*.figma.swift' 2>/dev/null
+# 2. Also check Regroup/ folder (logos that live in uicomponents)
+git ls-tree -r --name-only iteration/develop -- Sources/UIComponents/Regroup/ 2>/dev/null
+```
+
+**Name-based fallback** (when ID lookups fail):
+```bash
+# Use the component name from API metadata to search
+# Convert name: "Logo - Miles and Smiles" → "MilesAndSmilesLogo" or similar
+cd "${COMMON_PATH}"
+git grep -rl "${component_name}" iteration/develop -- 'Shared/Figma/Components/*.json' 2>/dev/null
+cd "${UICOMPONENTS_PATH}"
+git grep -rl "${component_name}" iteration/develop -- 'Sources/UIComponents/Regroup/' 2>/dev/null
+```
+
+> **⚠️ IMPORTANT:** Both submodule pointers in the main repo's `develop` may lag behind their respective `iteration/develop` branches. Always search on `iteration/develop` using `git grep` / `git show` to avoid false negatives. This applies to **both** `{project.slug}-common` and `{project.slug}-components`.
+
+**Pass Condition:** ALL child component instances are either:
+- Already implemented (have a matching `.figma.swift` on `iteration/develop`), OR
+- Have `status.ios.implemented.value = true` in individual `Components/{nodeId}.json` (architecture-update model — with legacy `codeConnect.ios = true` as fallback for pre-backfill entries), OR
+- Listed under `parentPage: "Icons"` or `"Logos"` in the component registry, OR
+- Found in `Regroup/` folder (cross-file logos like `MilesAndSmilesLogo`), OR
+- Marked as skipped in registry (`skip: true`), OR
+- Built-in SwiftUI primitives (Text, Image, Shape, etc.)
+
+**Fail Condition:** One or more child components are unimplemented AND not skipped.
+List the missing dependencies with their Figma names and node IDs.
+
+---
+
+### Criterion 5 — Atomic Component Scope
+
+**Question:** Atomic (tek başına anlamlı) bir UI parçası mı?
+
+**Check:**
+
+1. From registry data, check `parentPage`:
+   - `"Components"` or empty → likely atomic ✅
+   - `"Flow Based Components"` → check further (could be a section of a screen)
+2. From Figma node data, check dimensions:
+   - Width > 500 AND height > 800 → likely a full screen ❌
+3. Check variant count from component properties:
+   - 2–50 variant combinations → reasonable ✅
+   - 0–1 variants → acceptable for STATIC_VALUES components — ⚠️ warn but pass
+   - 500+ variants → likely needs splitting ❌
+4. Check component name depth:
+   - Name contains `/` separators with 4+ levels (e.g., `A/B/C/D/E`) → ⚠️ warn, may be deeply nested subcomponent
+
+**Pass Condition:** Not a full screen, has reasonable variant count, represents a reusable UI piece.
+
+---
+
+### Criterion 6 — iOS Platform Applicability
+
+**Question:** iOS platformu için geçerli mi (Hover-only değil)?
+
+**Check:**
+
+1. From component properties, check if ALL variant values are hover/desktop-only:
+   - If the ONLY states available are `Hover` → ❌ FAIL (iOS doesn't have hover)
+   - If a `Channel` property exists and has ONLY `Desktop` or `Web` values → ❌ FAIL
+2. Check page mapping:
+   - Component on a page containing `"iOS"` in registry `pageIdMappings` → ✅ platform-specific, OK
+   - No platform indicator → ✅ assumed cross-platform
+3. Check for web-only component patterns in the name:
+   - `"Breadcrumb"`, `"Sidebar"`, `"Tooltip/Hover"` → ⚠️ flag for review but don't auto-fail
+
+**Pass Condition:** Component is usable on iOS — has non-hover states and is not desktop-only.
+
+---
+
+### Criterion 7 — Already Implemented Check
+
+**Question:** Bu component zaten implemente edilmiş mi?
+
+**Check:**
+
+1. During the `os.walk` in C4, also search for files matching the component name or nodeId in `${UICOMPONENTS_PATH}/Sources/` (excluding `Discarded/`).
+2. Match criteria:
+   - A `.figma.swift` file containing the component's `nodeId`
+   - A `.swift` file whose name matches the component's last path segment (e.g., `MilesDestination.swift` for `Explore/ProgramWorld/MilesDestination`)
+3. If found → ❌ FAIL. Reason: "Component is already implemented at {path}. Use `/figma-mend` to re-implement or skip."
+4. If not found → ✅ PASS.
+
+**Pass Condition:** No existing Swift implementation found for this component (excluding `Discarded/`).
+
+**Note:** This criterion prevents double-implementation. If the component exists in `Discarded/`, C7 still passes but an `MEND_CANDIDATE` info flag is raised in Implementation Intel.
+
+---
+
+## Implementation Intel (Non-Blocking Info Section)
+
+These are computed from data already in memory (registry, API response, filesystem walk) with **zero additional cost**. They appear below the verdict box as `📊 Implementation Intel`.
+
+### Complexity Score
+
+Recursive node count + max depth from the API node tree:
+```python
+def complexity(n, depth=0):
+    children = n.get('children', [])
+    count = len(children)
+    max_d = depth
+    for c in children:
+        cc, cd = complexity(c, depth + 1)
+        count += cc
+        max_d = max(max_d, cd)
+    return count, max_d
+
+total_nodes, max_depth = complexity(node)
+# S: <15 nodes | M: 15-40 | L: 40-100 | XL: >100
+```
+
+### Text Node Count (Localization Estimate)
+
+Count nodes with `type == 'TEXT'` in the tree → approximate localization key count.
+
+### Image/Asset Detection
+
+Check for `IMAGE` fill types or image-related children → signals need for `AsyncImage`/Kingfisher.
+
+### Discarded Version Check
+
+During C4/C7 filesystem walk, if a match is found under `Discarded/` → flag as `MEND_CANDIDATE` with the path. Signals `/figma-mend` should be used instead of `/figma-to-swiftui`.
+
+### Wiki Documentation Status
+
+Check if a wiki markdown file exists at:
+```
+${REPO_ROOT}/{repos.wiki.path}/FigmaComponents/
+```
+Matching the component name pattern.
+
+### Sibling Page Progress
+
+From registry, count how many components on the same `pageName` are implemented vs total. Useful for batch planning.
+
+---
+
+## Scoring & Verdict
+
+| Score | Verdict | Meaning |
+|-------|---------|---------|
+| 7/7 ✅ | **VALID** | Ready for `/figma-to-swiftui` implementation pipeline |
+| 6/7 ✅ | **CONDITIONAL** | One criterion failed — may be resolvable |
+| 5/7 or below | **INVALID** | Not ready — requires design-side changes or scope adjustment |
+
+**Note on ⚠️ SKIPPED criteria:** A skipped criterion (e.g., Figma API unreachable) counts as a pass for scoring purposes but is noted in the output.
+
+---
+
+## Output Format
+
+### Single Mode
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  FIGMA COMPONENT VALIDATION                                 ║
+╠══════════════════════════════════════════════════════════════╣
+║  Component: {componentName}                                 ║
+║  Node ID:   {nodeId}                                        ║
+║  File:      {fileName}                                      ║
+║  Page:      {pageName}                                      ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  1. Registry Presence          ✅ Found in Design System Core║
+║  2. Code Connect Strategy      ✅ Property Mapping (3e,1s,2b)║
+║  3. Design Token Compliance    ⚠️ Assumed (API limit)        ║
+║  4. Dependency Readiness       ✅ All 2 deps implemented     ║
+║  5. Atomic Scope               ✅ 12 variants, 354×265       ║
+║  6. iOS Applicability          ✅ Has mobile states           ║
+║  7. Already Implemented        ✅ No existing implementation  ║
+║                                                              ║
+║  ──────────────────────────────────────────────────────────  ║
+║  VERDICT: ✅ VALID (7/7)                                     ║
+║  Ready for /figma-to-swiftui                                 ║
+╚══════════════════════════════════════════════════════════════╝
+
+📊 Implementation Intel:
+  - Complexity: M (28 nodes, depth 4)
+  - Text nodes: 5 → ~5 localization keys
+  - Images: 1 image fill → needs AsyncImage
+  - Discarded: No previous version
+  - Wiki: ✅ Documentation exists
+  - Page progress: Explore 12/18 (67%)
+
+⚠️ Warnings:
+  - UNNAMED_PROPERTY: "Property 1" detected — design team should rename
+```
+
+If `--verbose`, expand each criterion with detailed findings.
+
+### Batch Mode
+
+```
+## Batch Validation Results
+
+| # | Component | File | C1 | C2 | C3 | C4 | C5 | C6 | C7 | Score | Verdict |
+|---|-----------|------|----|----|----|----|----|----|----|-------|---------|
+| 1 | TextBadge | DSC  | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 7/7   | VALID   |
+| 2 | FooBar    | MAC  | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | 6/7   | COND.   |
+...
+
+### Summary
+- VALID: X components
+- CONDITIONAL: Y components  
+- INVALID: Z components
+```
+
+---
+
+## Warning Flags (Informational, Non-Blocking)
+
+These are logged but do NOT affect the VALID/INVALID verdict:
+
+| Flag | Description |
+|------|-------------|
+| `UNNAMED_PROPERTY` | Figma property named "Property 1" — tasarımcı rename etmeli |
+| `TYPO_DETECTED` | Variant value appears misspelled (e.g., "Standart", "Clasic Plus") |
+| `DESKTOP_CHANNEL` | Component has Desktop/Web channel mapping — iOS'ta kullanılmaz |
+| `MEND_CANDIDATE` | A previous implementation exists in `Discarded/` — use `/figma-mend` instead |
+| `URL_FORMAT_INCONSISTENT` | Node URL uses non-standard format (www vs non-www, `:` vs `-`) |
+| `LOW_VARIANT_COUNT` | 0–1 variants — uses STATIC_VALUES Code Connect strategy |
+| `DEEP_NESTING` | Component name has 4+ path levels — may be a deeply nested subcomponent |
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Figma API unreachable | Skip Criteria 2, 3, 4, 6 — mark as ⚠️ SKIPPED, continue with Criteria 1, 5, 7 |
+| Registry file not found | Show command: `cd ${COMMON_PATH} && swift build --product FigmaRegistryUtility && .build/debug/FigmaRegistryUtility update` |
+| FigmaRegistryUtility not built | Show: `cd ${COMMON_PATH} && swift build --product FigmaRegistryUtility` |
+| Invalid URL format | Ask user for correct URL via AskUserQuestion |
+| Figma token not found | Show: `security add-generic-password -s "FIGMA_ACCESS_TOKEN" -w "<YOUR_TOKEN>"` |
+
+---
+
+## Execution Sequence
+
+```
+1. PARSE_URL        → Extract fileKey, nodeId from arguments
+2. RUN_SCRIPT       → python3 ${REPO_ROOT}/.instructions/figma/figma-validate/figma_validate.py <fileKey> <nodeId>
+3. PARSE_JSON       → Read JSON output from script
+4. FORMAT_OUTPUT    → Display formatted verdict box with intel + warnings
+```
+
+## Performance Requirements
+
+**Target:** ≤ 10 seconds for single-component validation.
+
+A permanent Python script at `.instructions/figma/figma-validate/figma_validate.py` handles all criteria + intel in one invocation.
+
+**How to run:**
+
+```bash
+python3 "${REPO_ROOT}/.instructions/figma/figma-validate/figma_validate.py" <fileKey> <nodeId>
+```
+
+Example:
+```bash
+python3 .instructions/figma/figma-validate/figma_validate.py 9ipBvrtsq9HlQ175B9k0wx 11797:6100
+```
+
+The script:
+- Auto-detects `REPO_ROOT` via `git rev-parse --show-toplevel`
+- Reads the Figma token from macOS Keychain (`FIGMA_ACCESS_TOKEN`)
+- Outputs a single JSON object with `results`, `intel`, `warnings`, `score`, `total`, `elapsed_ms`
+- Agent parses the JSON and formats the verdict box
+
+**IMPORTANT — Do NOT create temporary `.py` or `.json` files.** Always use the permanent script above. If for any reason temporary files were created during execution, clean them up before returning the result:
+
+```bash
+rm -f /tmp/figma_validate*.py /tmp/figma_validate*.json /tmp/figma_qr*.py /tmp/figma_analyze*.py /tmp/figma_lookup*.py
+```
+
+**No-temp-file principle:** This skill is read-only and must leave zero artifacts. All computation must happen either:
+1. Via the permanent `figma_validate.py` script, OR
+2. Via inline `python3 -c "..."` one-liners piped through shell, OR
+3. Via `git grep` / `git show` commands
+
+Never write intermediate results to disk.
+
+**Key rules for speed:**
+- ONE terminal command total (the python3 script) — no sequential shell calls
+- Use `urllib.request` — never `curl` (may be blocked by auto-approval policy)
+- Use `os.walk` / `glob.glob` for file searches — never shell `grep`/`find`
+- Never put `#` comments in shell compound commands — causes `zsh` parse errors
+
+---
+
+## Future Extensibility
+
+Each criterion is self-contained with:
+- A **question** (what it checks — displayed in Turkish for team context)
+- A **check** procedure (how to verify)
+- A **pass condition** (what constitutes success)
+
+To add a new criterion:
+1. Add a new `### Criterion N` section following the same structure
+2. Update the scoring thresholds in the "Scoring & Verdict" table
+3. Update the output format to include the new column
+4. Update the description in both SKILL.md files (entry point + instructions)
+
+To remove a criterion:
+1. Delete the `### Criterion N` section
+2. Adjust scoring thresholds accordingly
+3. Update descriptions