@mmerterden/multi-agent-pipeline 11.2.0 → 11.3.1

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

@@ -1,633 +0,0 @@
----
-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: `"$HOME/.claude/lib/credential-store.sh" set FIGMA_ACCESS_TOKEN "<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