@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/steps/step-03-unit-mapping.md

@@ -0,0 +1,139 @@
+# Step 3: Unit Mapping ⛔ HITL GATE
+
+> **Acting as:** [frame-mapper](../agents/frame-mapper.md) — đọc persona đầy đủ trước khi thực thi.
+
+## GOAL
+
+Chốt bảng **`WBS unit ↔ Figma frame`** và emit `figma-manifest.yaml`. Đây là **trái tim skill** và là input người thật duy nhất không automate được: không có tín hiệu nào trong hệ thống nói frame *"Đăng nhập v3 (final)"* là `SCR-LOGIN`.
+
+## 1. Persona
+
+Adopt [frame-mapper](../agents/frame-mapper.md). Persona declare: role + tín hiệu mapping + thang confidence + 4 case lệch + constraints. Thủ tục orchestration ở file này.
+
+## 2. Inputs
+
+- `frames_raw.json` (step-02).
+- `project_wbs.md` — **SSoT của danh sách unit**. Lấy mọi ID prefix `SCR-*` / `WGT-*` (cột đầu markdown table). BE (`MPF-*`, `HUB-*`, ...) **không** tham gia mapping.
+- (Optional) `ux_design.md` §4 Journey Screen Table — thứ tự màn trong journey, làm tín hiệu 2.
+- `{family_root}/registry.yaml` (nếu multi-DS) — resolve DS root per unit.
+- Manifest cũ `figma-manifest.yaml` (nếu re-ingest) — giữ mapping đã ký, không hỏi lại.
+
+## 3. Pipeline
+
+### Stage 3.1: Load universe 2 chiều
+
+- **Chiều Figma:** `candidates[]` đã gom theo `variant_group` (step-02) — map ở mức **base**, không map từng state. Scope phía này **chỉ** do `scope_pages`/`node_ids` quyết (đã lọc ở step-02).
+- **Chiều WBS:** mọi `SCR-*`/`WGT-*` trong `project_wbs.md`, kèm cột mô tả để làm tín hiệu semantic. **Đây là chiều bị `--feature` cắt ngắn** (Stage 3.1b).
+
+### Stage 3.1b: Xác định feature scope (cắt ngắn CHIỀU WBS)
+
+| Trường hợp | Xử lý |
+|---|---|
+| `scope.feature` có giá trị (step-01) | Lọc chiều WBS còn unit của feature đó. Nguồn danh sách unit, theo thứ tự: slice manifest `NTAPP-output/Stage_2_Architecture/slices/*.md` (units[] của slice thuộc feature) → cluster/epic tương ứng trong `project_wbs.md` → `ux_design.md` §4 journey screen table. Không nguồn nào khớp tên feature → **WARN + coi như không truyền** (đi nhánh dưới), KHÔNG STOP |
+| `scope.feature` = null | **Tự suy:** chạy Stage 3.2 trước trên full WBS → lấy các unit match `confidence: HIGH`/`MEDIUM` → tra ngược feature/cluster chứa chúng trong WBS/slice manifest → nếu ≥2 unit cùng 1 feature thì đó là feature suy đoán. Đưa vào bảng HITL để xác nhận (Stage 3.5), **KHÔNG hỏi thành vòng riêng** |
+| Suy không ra (0-1 unit match, hoặc match rải rác nhiều feature) | Giữ full WBS. Bảng dài hơn nhưng **không sai** — luật merge (Stage 3.3b) đã chặn việc ghi đè nhầm unit ngoài scope |
+
+⛔ **Bất biến:** `--feature` (dù truyền tay hay suy đoán) **KHÔNG bao giờ** lọc bớt `candidates[]` phía Figma. Frame nằm ngoài feature nhưng trong scope Figma vẫn phải hiện ở danh sách "Frame chưa dùng" để người thấy — biết đâu designer để lẫn màn của feature này ở page khác.
+
+### Stage 3.2: Propose mapping (per persona §3 tín hiệu)
+
+Áp tín hiệu theo thứ tự, dừng ở tín hiệu đầu cho kết quả DUY NHẤT — ghi `matched_by` + `confidence`:
+
+| # | Tín hiệu | Confidence khi khớp |
+|---|---|---|
+| 1 | `base_name` **chứa đúng ID unit** (`SCR-LOGIN`, case-insensitive, bỏ dấu phân cách) | **HIGH** |
+| 2 | Normalized name similarity ≥ 0.85 với mô tả unit trong WBS (bỏ dấu tiếng Việt, lowercase, bỏ số version `v2`/`final`/`copy`) | **MEDIUM** |
+| 3 | Thứ tự frame trong page khớp thứ tự màn trong `ux_design.md` §4 journey **và** similarity ≥ 0.6 | **MEDIUM** |
+| 4 | Không tín hiệu nào | **LOW** → bắt buộc người map tay |
+
+**Re-ingest:** unit đã có mapping đã ký trong manifest cũ **và** `base_name` không đổi → carry over, `matched_by: previous-manifest`, `confidence: HIGH`, KHÔNG hỏi lại.
+
+### Stage 3.3: Phân loại 4 case lệch (persona §4)
+
+| Case | Điều kiện | Xử lý |
+|---|---|---|
+| **A. Frame không map unit nào** | Frame còn lại sau khi mọi unit đã có frame | Hỏi người: nháp/bỏ (`ignore: true`) **hay** màn thật? Trả lời "màn thật" → **STOP**: *"Frame `{name}` là màn thật nhưng không có unit tương ứng trong WBS. WBS là SSoT — thêm unit bằng `/ntapp-architecture-design --append` rồi chạy lại. KHÔNG để Figma thành inventory thứ hai."* |
+| **B. Unit không có frame** | Unit **in-scope** (Stage 3.3b) không match frame nào | `figma_status: missing` → unit đó **fallback author mode** ở Stage 4a. **KHÔNG block** (feature có thể ingest từng phần). ⚠️ Chỉ áp cho unit in-scope — unit out-of-scope đi luật merge, KHÔNG được gán `missing` |
+| **C. 1 unit ↔ nhiều frame** | Nhiều `variant_group` cùng trỏ 1 unit, hoặc 1 group có nhiều state | State đã nhận diện → `states[]`. Nhiều group khác nhau cùng unit → hỏi người chọn group nào là canonical, còn lại `ignore: true` |
+| **D. 1 frame ↔ nhiều unit** | Frame chứa cả screen và widget nhúng | `contains[]`: mỗi widget khai `unit_id` + `node_id` con. Người chỉ định node con (hoặc để trống → widget đó `figma_status: missing`) |
+
+### Stage 3.3b: Phân loại in-scope / out-of-scope (BẮT BUỘC — chống ghi đè)
+
+Ingest hầu như luôn hẹp scope (feature mới → 1 page Figma). Không có bước này, unit của feature cũ sẽ bị hạ xuống `missing` và Stage 4a im lặng rơi về author mode dù Figma vẫn còn frame — Hook 3 **không bắt được** vì nó chỉ so checksum khi status là `mapped`.
+
+Áp **luật in-scope** ở `references/figma-manifest-schema.md` §Merge semantics (6 điều kiện, xét theo thứ tự) cho **mọi** unit `SCR-*`/`WGT-*` trong WBS — kể cả unit đã bị Stage 3.1b cắt khỏi bảng HITL.
+
+Kết quả 3 nhóm:
+
+| Nhóm | Xử lý ở step này | Ghi vào manifest (step-07) |
+|---|---|---|
+| **in-scope** | Chạy Stage 3.2 + 3.3 đầy đủ, đưa vào bảng HITL | `mapped` / `missing` / `ignored` + `last_evaluated_at` = giờ hiện tại |
+| **out-of-scope, CÓ entry cũ** | KHÔNG xét, KHÔNG đưa vào bảng HITL | **giữ nguyên entry cũ verbatim** — không đổi status/checksum/`last_evaluated_at` |
+| **out-of-scope, KHÔNG có entry cũ** | KHÔNG xét | `figma_status: not_in_scope` + `reason` nêu scope đã loại nó |
+
+`missing` = "đã xét, Figma thật sự không có frame". `not_in_scope` = "chưa xét, không biết". Trộn hai cái này là gốc của bug ghi đè.
+
+### Stage 3.4: Resolve DS root per unit (multi-DS)
+
+Theo `_shared/ds-resolution.md` **nhánh B.4** cho từng unit đã map: thẻ `repo:` ở Cluster Header WBS (primary) → `id_prefixes` → `modules` → `default_ds`. Conflict giữa thẻ WBS và registry hints → **STOP báo mismatch** (không chọn im lặng theo bên nào). Không tín hiệu nào khớp → đưa vào bảng HITL cùng Stage 3.5 (hỏi 1 lần, không hỏi 2 vòng).
+
+Single-DS (không có `registry.yaml`) → mọi unit dùng family root, bỏ qua stage này.
+
+### Stage 3.5: ⛔ HITL — trình bảng, chờ người ký
+
+Trình **một** bảng duy nhất (gộp cả state chưa nhận diện ở step-02 Stage 3.3 và DS chưa resolve ở 3.4 — người trả lời 1 lượt):
+
+```markdown
+## Mapping đề xuất — feature `Thanh toán` (suy đoán) — {N} unit in-scope / {M} frame
+
+| WBS unit | Mô tả (WBS) | Frame đề xuất | States | DS | Tín hiệu | Confidence |
+|---|---|---|---|---|---|---|
+| SCR-PAY-01 | Chọn phương thức | `SCR-PAY-01` | default, error | web-admin | exact-id | HIGH |
+| SCR-PAY-02 | Xác nhận GD | `Thanh toán B2 v3` | default, empty | web-admin | name-similarity 0.88 | MEDIUM |
+| SCR-PAY-03 | Kết quả | — | — | — | — | LOW → cần map tay |
+
+**Coverage:** feature `Thanh toán` có 6 unit → mapped 5, thiếu 1 (`SCR-PAY-03`)
+**Frame chưa dùng:** `Sandbox`, `Note cho dev` → đề xuất `ignore: true`
+**Unit in-scope chưa có frame:** `SCR-PAY-06` → `figma_status: missing` (Stage 4a author mode)
+**Giữ nguyên, KHÔNG xét lần này (out-of-scope):** 34 unit — `SCR-LOGIN`, `SCR-DASH`, … *(entry cũ giữ verbatim)*
+**Cần bạn xác nhận:**
+  (1) Feature đang ingest là `Thanh toán` — đúng không? (suy từ 5 unit đã match; sai thì cho tôi tên đúng)
+  (2) State `mobile` của `SCR-PAY-02` — giữ hay bỏ?
+  (3) `SCR-PAY-03` thuộc frame nào?
+```
+
+Dòng **Coverage** chỉ in khi có feature (truyền tay hoặc suy đoán được) — nó trả lời *"designer vẽ đủ màn cho feature này chưa?"*, thứ bảng full-WBS không nói được.
+
+Dòng **out-of-scope** chỉ liệt kê tên, **không** đưa vào bảng chính — mục đích là để người thấy chúng được **bảo toàn**, không phải để duyệt lại.
+
+Chờ người trả lời `approved` (hoặc sửa từng dòng). **KHÔNG tự tiếp tục** khi còn dòng `confidence: LOW` chưa được người quyết (U5). Người bác feature suy đoán → dùng tên họ đưa, quay lại Stage 3.1b lọc lại (1 vòng, không lặp vô hạn).
+
+### Stage 3.6: Emit `figma-manifest.yaml` (atomic, U1 — MERGE, không replace)
+
+Schema đầy đủ: [references/figma-manifest-schema.md](../references/figma-manifest-schema.md). Ghi **per DS root** — mỗi manifest chỉ chứa unit thuộc DS đó (multi-DS: N file; single-DS: 1 file). Copy `figma-source.json` từ family root sang từng DS root kèm theo (mỗi bản self-contained, audit được độc lập).
+
+Thủ tục ghi:
+1. Load manifest cũ (nếu có). `schema_version: "1.0"` (không có `last_scope`) → coi như lần trước scope toàn file.
+2. Với unit **in-scope** → thay entry bằng kết quả mới. Với unit **out-of-scope có entry cũ** → copy entry cũ **nguyên xi**. Với unit **out-of-scope không có entry** → tạo entry `not_in_scope`.
+3. Ghi `last_scope` = `{pages, node_ids, feature, units_in_scope[]}` của lần này.
+4. `units[]` sort theo `unit_id` alphabetical (U4) — merge không được làm đảo thứ tự gây diff giả.
+
+`checksum` để **trống** cho unit in-scope ở step này — step-07 tính sau khi có specs + frames. Unit out-of-scope giữ checksum cũ.
+
+## 4. Decision Points
+
+- **WBS không có `SCR-*`/`WGT-*` nào** → STOP: *"WBS chưa có unit FE. Chạy Stage 2 (`/NTAPP-vsaf-reproduce-architecture`) hoặc kiểm prefix ID — mapping chỉ nhận `SCR-*`/`WGT-*`."*
+- **Case A + người xác nhận "màn thật"** → STOP như bảng §3.3.
+- **DS resolve conflict** → STOP báo mismatch (nhánh B.4).
+- **Người trả lời không rõ / chỉ nói "ok" khi còn dòng LOW** → hỏi lại đúng dòng còn thiếu, KHÔNG suy diễn (U5).
+- **100% unit in-scope là `missing`** → STOP: *"Không unit nào map được frame. Ingest sẽ không tạo giá trị gì. Kiểm scope harvest hoặc naming convention frame."* (Chỉ tính unit **in-scope** — unit out-of-scope đang được bảo toàn, không phải bằng chứng ingest thất bại.)
+- **`--feature` không khớp nguồn nào** (slice manifest / WBS cluster / journey) → WARN: *"Không tìm thấy feature `{name}` trong slice manifest hay WBS cluster. Bỏ lọc, dùng full WBS — bảng sẽ dài hơn nhưng không sai."* KHÔNG STOP.
+- **Người bác feature suy đoán** → nhận tên họ đưa, lọc lại Stage 3.1b, trình lại bảng **một** lần. Vẫn không khớp → bỏ lọc, full WBS.
+
+## 5. Output
+
+- `{ds_root}/_reference/figma/figma-manifest.yaml` (per DS, `checksum` chưa điền).
+- `{ds_root}/_reference/figma/figma-source.json` (copy từ family root).
+- `report_sections[]` += `[MAPPING]` (bảng đã ký nguyên văn + feature scope đã chốt + coverage + số mapped/missing/not_in_scope/ignored/preserved + ai ký + thời điểm).
+
+**Next:** Read fully and follow `./step-04-spec-extract.md`

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/steps/step-04-spec-extract.md

@@ -0,0 +1,276 @@
+# Step 4: Spec Extract
+
+## GOAL
+
+Với mỗi unit đã mapped, sinh `specs/{unit_id}.json` — hierarchy **đã prune** + `layout_groups_hint[]` + `surface[]` + `geometry[]` + `copy[]` + `icon_candidates[]` + `control_hint[]`.
+
+Đây là step tạo ra giá trị lớn nhất của cả skill: **Figma Auto Layout ↔ Layout Groups table gần như 1-1**, nên F3 ở Stage 4a không phải đoán bố cục.
+
+**Nguyên tắc phạm vi extract:** thứ gì **không** được emit ra ngoài khoá `raw` thì Stage 4a không có cách hợp pháp nào để biết, và sẽ im lặng rơi về giá trị mặc định của DS.
+
+| Lớp | Bỏ thì Stage 4a mất gì | Stage 4.x |
+|---|---|---|
+| Surface treatment (radius/border/elevation) | Vai trò bo góc; có/không viền | **4.2b** |
+| Toạ độ tương đối của container không Auto Layout | Quan hệ trên–dưới vs cùng hàng | **4.2c** |
+| `sizing` của member + tách 2 trục align | Canh giữa suy từ FILL hai bên | **4.3** |
+
+## 1. Persona
+
+Procedural. Tuân thủ **U7** (fetch → file → `jq` prune → chỉ đọc bản prune), **U5** (không suy diễn), **U4** (sorted, deterministic).
+
+## 2. Inputs
+
+- `figma-manifest.yaml` (step-03) — unit nào, `node_id` nào, `states[]` nào.
+- `figma-source.json` — `version` pinned.
+- Config `snap_tolerance` (dùng ở step-05; step này chỉ ghi raw + đánh dấu).
+- (`manual` mode) `inbox/nodes.json`.
+
+## 3. Pipeline
+
+### Stage 4.1: Fetch sâu — chỉ node đã mapped
+
+```bash
+bash <skill_dir>/scripts/figma-fetch.sh nodes \
+  --ids "12:340,12:411,18:22" --depth 12 \
+  --out "{output_root}/.work/nodes-deep.json"
+```
+
+Chỉ truyền `node_id` của unit **mapped** (+ node của từng state). Frame `ignore: true` không fetch. Script tự chunk `ids` để không vượt giới hạn độ dài URL.
+
+### Stage 4.2: Prune (bỏ node vô nghĩa với spec)
+
+Bỏ node khi khớp bất kỳ điều kiện:
+
+| Bỏ | Lý do |
+|---|---|
+| `visible: false` | Không thuộc màn đang đặc tả |
+| `type: VECTOR` mà **không** phải icon candidate (Stage 4.5) | Đồ hoạ trang trí |
+| `type: RECTANGLE` / `ELLIPSE` chỉ có `fills`, không có sibling text/child | Background/divider — sẽ tái tạo bằng token, không cần node |
+| `isMask: true` và mọi descendant | Kỹ thuật render Figma, không có tương đương UI |
+| `GROUP` có đúng 1 child | **Collapse** — nâng child lên thay vì giữ wrapper rỗng |
+| Node ngoài `absoluteBoundingBox` của frame cha | Ghi chú designer để cạnh canvas |
+
+Giữ: `FRAME`, `INSTANCE`, `COMPONENT`, `TEXT`, `VECTOR` (icon), `GROUP` (≥2 child).
+
+### Stage 4.2b: Surface treatment → `surface[]` (NGOÀI `raw`)
+
+`cornerRadius` / `strokes` / `effects` đã có sẵn trong response `/v1/files/{key}/nodes` — không cần fetch thêm. Nhưng **giá trị px thô phải ở trong `raw`** (Stage 4.7), nên tầng ngoài mang **vai trò (role)**, không mang số. Vai trò là thứ F3 được đọc và ghi vào DD; số là thứ step-05 snap sang tên token.
+
+Với mỗi node giữ lại có `cornerRadius != 0` **hoặc** `strokes[] != []` **hoặc** `effects[]` có `DROP_SHADOW`/`INNER_SHADOW` visible → 1 entry:
+
+```json
+{
+  "node_id": "12:340",
+  "figma_name": "Button / Primary / Large / Default",
+  "radius_role": "pill",
+  "radius_source": "descendant",
+  "border": { "style": "solid", "sides": "all" },
+  "elevation": true,
+  "confidence": "HIGH"
+}
+```
+
+**`radius_role` — suy từ tỉ lệ radius / cạnh ngắn, KHÔNG từ giá trị tuyệt đối:**
+
+| Điều kiện (`r` = cornerRadius, `s` = min(w, h)) | `radius_role` | Ghi chú |
+|---|---|---|
+| `r >= s/2 - 1` **và** `w/h` ngoài khoảng 0.9–1.1 | `pill` | Bo hết hai đầu — hộp chữ nhật |
+| `r >= s/2 - 1` **và** `w/h` trong khoảng 0.9–1.1 | `circle` | Avatar / icon tròn |
+| `s/4 <= r < s/2 - 1` | `rounded-lg` | — |
+| `s/8 <= r < s/4` | `rounded-md` | — |
+| `0 < r < s/8` | `rounded-sm` | — |
+| `r == 0` | *(không emit entry vì radius)* | — |
+
+Ngưỡng theo tỉ lệ chứ không theo px: cùng một `r = 24` là **pill** trên nút cao 48 và **rounded-sm** trên thẻ cao 400.
+
+**`radius_source` — bắt buộc, vì INSTANCE thường không mang radius ở node gốc:** `cornerRadius` của component instance nằm ở frame **bên trong** instance (hoặc ở component master), không ở node instance. Thứ tự tra:
+
+1. `cornerRadius` / `rectangleCornerRadii` trên chính node → `radius_source: "self"`.
+2. Không có → **descend** vào con: `FRAME`/`RECTANGLE` đầu tiên có `cornerRadius != 0` **và** kích thước ≥ 90% node cha (tức là nền của instance, không phải chi tiết nhỏ bên trong) → `radius_source: "descendant"`.
+3. Vẫn không có → **không emit** `radius_role` và ghi vào `warnings[]`: *"`{figma_name}` là INSTANCE không tra được radius (node gốc và con đều không có `cornerRadius`) — F3 phải đọc từ ảnh, ghi vào §2.5"*. U5: không bịa.
+
+`rectangleCornerRadii` (4 góc khác nhau) → `radius_role` lấy theo góc **lớn nhất**, thêm `radius_asymmetric: true`; F3 đọc ảnh để biết góc nào.
+
+**`border` — phân biệt viền với đổ bóng:**
+
+| Tín hiệu Figma | `border` |
+|---|---|
+| `strokes[]` có ≥1 paint visible, `strokeDashes` rỗng | `{ style: "solid", sides: <xem dưới> }` |
+| `strokes[]` visible + `strokeDashes[]` không rỗng | `{ style: "dashed", sides: ... }` |
+| `strokes[]` rỗng / toàn `visible: false` | `null` — **không có viền** |
+
+`sides`: `individualStrokeWeights` có ≥1 cạnh = 0 → liệt kê cạnh khác 0 (`"top"`, `"top+bottom"`); đều nhau → `"all"`. Đây là nguồn duy nhất để DD nói được "kẻ ngăn chỉ ở trên" thay vì "khung viền quanh".
+
+`elevation: true` khi có `DROP_SHADOW` visible. **Bắt buộc emit cả khi `border: null`** — vì thẻ trắng bo góc + bóng mềm và thẻ trắng có viền 1px trông rất khác nhau, mà ASCII `┌──┐` biểu diễn cả hai giống nhau. Không có entry surface thì F3 mặc định vẽ viền.
+
+Màu stroke / độ dày px / blur bóng đi vào `raw` như mọi giá trị khác (Stage 4.7); step-05 snap sang token.
+
+### Stage 4.2c: Container không Auto Layout → `geometry[]`
+
+`layoutMode: NONE` (hoặc `GROUP`) mà có ≥2 child → **không có thông tin nào** về quan hệ không gian của các con nếu chỉ nhìn cây. Emit toạ độ **tương đối, đã chuẩn hoá** để F3 suy lại bố cục mà không phải mở ảnh đo bằng mắt:
+
+```json
+{
+  "node_id": "12:411",
+  "figma_name": "Group 42",
+  "inferred_direction": "row",
+  "inferred_align": "center",
+  "confidence": "MEDIUM",
+  "children": [
+    { "node_id": "…:1", "name": "text_amount",   "box": [0.00, 0.42, 0.38, 0.16] },
+    { "node_id": "…:2", "name": "button_submit", "box": [0.44, 0.40, 0.56, 0.20] }
+  ]
+}
+```
+
+`box` = `[x, y, w, h]` **tỉ lệ 0–1 so với `absoluteBoundingBox` của node cha**, làm tròn 2 chữ số. Dùng tỉ lệ chứ không px vì (a) không vướng luật `raw` — đây là quan hệ bố cục, không phải giá trị design token nào để hardcode, (b) so sánh được giữa mobile 375 và desktop 1440.
+
+**Suy `inferred_direction`** (thủ tục cố định, không phán đoán tự do):
+
+- Chiếu các `box` lên trục X và trục Y. Cặp con nào chồng lấn ≥ 60% trên trục Y **và** không chồng lấn trên trục X → cùng hàng.
+- Mọi cặp cùng hàng → `row`. Mọi cặp rời nhau theo Y → `column`. Lẫn cả hai → `mixed` + `confidence: LOW`.
+- `inferred_align`: theo trục vuông góc — tâm các con lệch < 5% bề rộng cha → `center`; sát mép đầu → `start`; sát mép cuối → `end`.
+
+`confidence` ở đây **cao nhất là MEDIUM** — suy từ toạ độ tĩnh không biết được ý định responsive của designer. F3 phải đối chiếu ảnh trước khi dán.
+
+> Không có khối này thì node loại đó chỉ ra `Box` với `props: ""` — F3 không có gì để đọc nên phải đoán, và mặc định sẽ đoán theo thứ tự `children` (tức xếp dọc).
+
+### Stage 4.3: Auto Layout → `layout_groups_hint[]` (giá trị cốt lõi)
+
+Với mỗi node còn lại có `layoutMode != NONE`, map sang **10 canonical primitive** của `_shared/component-metadata-schema.md` §12:
+
+| Tín hiệu Figma | `Type` | Ghi chú |
+|---|---|---|
+| `layoutMode: VERTICAL` | `Stack` + `direction=column` | — |
+| `layoutMode: HORIZONTAL` | `Stack` + `direction=row` | — |
+| `layoutWrap: WRAP` | `Cluster` | Cluster là primitive cho nhóm wrap được |
+| `layoutMode: HORIZONTAL` + `primaryAxisAlignItems: SPACE_BETWEEN` | `Cluster` | Thường là action bar / header |
+| 1 child + `counterAxisAlignItems: CENTER` + `primaryAxisAlignItems: CENTER` | `Center` | — |
+| `VERTICAL` chứa đúng 1 `TEXT` (label) + 1 `INSTANCE` input | `FormField` | `Props: label="<text nguyên văn>"` |
+| ≥2 `FormField` trong `VERTICAL` đều cùng width | `FieldGrid` | `confidence: MEDIUM` |
+| ≥2 hàng con cùng số cột, cột cùng width | `Grid` | `confidence: LOW` — Figma không có Grid thật, đây là suy luận |
+| `layoutMode: NONE` nhưng có ≥2 child | `Box` | Kèm entry `geometry[]` (Stage 4.2c) — `props` mang `inferred_direction`/`inferred_align`, KHÔNG để rỗng |
+
+**Props map — mỗi trục một khoá riêng (BẮT BUỘC):**
+
+| Figma | Props | Trục |
+|---|---|---|
+| `itemSpacing` | `gap=<raw>px` (step-05 snap → tên token) | — |
+| `paddingTop/Right/Bottom/Left` | `padding=<raw>` (gộp nếu đối xứng) | — |
+| `primaryAxisAlignItems: MIN/CENTER/MAX/SPACE_BETWEEN` | `justify=start/center/end/between` | **trục chính** |
+| `counterAxisAlignItems: MIN/CENTER/MAX/BASELINE` | `align=start/center/end/baseline` | **trục vuông góc** |
+| `layoutSizingHorizontal` / `Vertical` | `sizing=<h>×<v>` với `fill`/`hug`/`fixed` | — |
+
+⛔ **CẤM dùng khoá `align=` cho cả hai trục.** Format cũ sinh ra `align=center, align=stretch` — hai giá trị cùng tên khoá, người đọc không thể biết cái nào là trục nào, và `stretch` thật ra là thông tin `sizing` bị gán nhầm nhãn. Đây là nguyên nhân trực tiếp của lớp bug canh lề. Một khoá xuất hiện hai lần trong một `props` string là **lỗi format**, step-07 phải bắt (§Stage 7.3).
+
+**`sizing` của từng member — bắt buộc ghi vào cột `Members`:**
+
+Member nào có `layoutSizingHorizontal: FILL` (trong row) hoặc `Vertical: FILL` (trong column) → hậu tố `(fill)`. `HUG` → `(hug)`. `FIXED` → không hậu tố.
+
+```
+Members: Left(fill), text_title, Right(fill)
+```
+
+**Quy tắc canh giữa suy diễn — `effective_align` (chốt lớp bug nặng nhất):**
+
+Row `HORIZONTAL` có ≥3 member, member **đầu và cuối** `sizing=fill`, member giữa `hug`/`fixed` → phần tử giữa **canh giữa theo toàn bề ngang của hàng**, bất kể `justify=start`. Ghi thêm vào Props:
+
+```
+direction=row, gap=10px, justify=start, align=center, sizing=fill×fixed, effective_align=center-full-width
+```
+
+Lý do phải suy tường minh: đây là idiom "3 cột cân bằng" (phần tử phụ neo hai biên, phần tử chính ở giữa). Figma **không có thuộc tính nào ghi "canh giữa"** — nó là *hệ quả* của việc hai cột biên cùng `FILL`. Bỏ `sizing` đi thì thông tin canh giữa biến mất không dấu vết, và `justify=start` còn lại sẽ được đọc thành canh trái.
+
+Biến thể 2 member (`[hug, fill]` hoặc `[fill, hug]`) → `effective_align=push-end` / `push-start` (một phần tử bị đẩy về cuối/đầu hàng).
+
+Gán `Group ID` theo convention của F3: `R1` = root, `G*` = generic, `F*` = FormField. Sinh **theo thứ tự render** (thứ tự `children` trong Figma = thứ tự Members).
+
+**Surface vào Props, KHÔNG thêm cột:** node có entry `surface[]` (Stage 4.2b) → thêm vào cùng `props` string 3 khoá phẳng, giữ đúng dạng `key=value` mà Stage 4b đang parse:
+
+```
+radius=pill, border=solid-all, elevation=card
+```
+
+`border=none` cũng **phải ghi tường minh** khi node có `elevation: true` — "bóng, không viền" là một quyết định thiết kế, còn khoá vắng mặt là "không biết", và hai thứ đó dẫn tới hai đoạn code khác nhau.
+
+> Output là **hint dán-được**: step-07 render sẵn bảng markdown 4 cột (`Group ID | Type | Members | Props`) trong `figma_ingest_report.md` — vẫn 4 cột như hợp đồng §2.2 của Stage 4a, thông tin mới nằm trong `Members` (hậu tố sizing) và `Props` (khoá mới). F3 verify + điền vào §2.2, KHÔNG tự phát minh lại.
+
+### Stage 4.4: `control_hint[]` — gợi ý §2.3
+
+Mỗi `INSTANCE` + `TEXT` là input/button → 1 dòng:
+- `control_id`: snake_case suy từ (a) tên node nếu đã semantic (`input-merchant-code` → `input_merchant_code`), (b) else `<loại>_<slug(text)>` (`button_tim_kiem`). Tên vô nghĩa (`Frame 427`) → `<TODO: F3 đặt tên>` (U5 — không bịa).
+- `figma_component`: tên component instance nguyên văn (step-05 map sang DS).
+- `variant_props`: `componentProperties` của instance (vd `{size: md, state: default}`).
+- `intent` (button/action only): suy từ variant prop (`Primary` → `primary`, `Danger`/`Destructive` → `destructive`) — không suy được → để trống.
+
+### Stage 4.5: `icon_candidates[]` — gợi ý Icon Legend
+
+Node `VECTOR`/`INSTANCE` là icon khi: tên chứa `icon`/`ic-`/`ic_`, **hoặc** component name bắt đầu bằng `Icon`, **hoặc** kích thước vuông ≤ 32px và không có text con.
+
+Mỗi candidate → `{ node_id, figma_name, icon_name_kebab, size, near_control }`. `icon_name_kebab` là **semantic intent** (`search`, `chevron-down`), không phải tên file Figma. Không suy được intent → `<TODO: F3 đặt tên>`.
+
+Đây là input cho bảng **Icon Legend** bắt buộc ở Stage 4a §2.2 — và là lý do code KHÔNG bao giờ chứa emoji (pre-commit Rule 9).
+
+### Stage 4.6: `copy[]` — text nguyên văn
+
+Mọi `TEXT` còn lại → `{ node_id, text, role, near_control }`. `role` phân loại heuristic:
+
+| role | Tín hiệu |
+|---|---|
+| `label` | Ngay trên/trái input trong cùng FormField |
+| `placeholder` | Nằm trong INSTANCE input, opacity thấp / màu muted |
+| `button` | Nằm trong INSTANCE có variant giống button |
+| `error` | Màu resolve về nhóm danger/error, hoặc mở đầu bằng cụm cảnh báo |
+| `heading` | font-size lớn nhất trong nhánh |
+| `body` | còn lại |
+
+**Text nguyên văn là bắt buộc giữ đúng từng ký tự** — đây là nguồn cho bảng Validation §2.3 (Action → Trường hợp lỗi → Thông báo lỗi nguyên văn) và cho `ux_conventions.md`. Không dịch, không sửa chính tả, không rút gọn.
+
+### Stage 4.7: Raw value — đánh dấu, KHÔNG đưa vào chỗ code đọc
+
+Mọi giá trị px/hex/font đi kèm dưới khoá `raw` **và** cờ `raw_only: true`:
+
+```json
+"raw": { "raw_only": true, "gap": 14, "padding": [16, 24, 16, 24], "fill": "#1F6FEB",
+         "font_size": 13, "radius": 24, "stroke_weight": 1, "stroke_color": "#E5E5E5" }
+```
+
+Ý nghĩa cờ: **step-05 snap sang token; Stage 4a/4b/5 KHÔNG được đọc khoá này**. Nếu để dev copy `#1F6FEB` vào code, pre-commit Rule 4 sẽ block — đây là chốt chặn ở tầng spec, trước khi tới đó.
+
+**Phạm vi của lệnh cấm:**
+
+| Loại thông tin | Ở đâu | 4a đọc được? |
+|---|---|---|
+| Giá trị đo được (px, hex, weight, blur) | `raw` | ❌ |
+| **Vai trò / ý định** (`radius_role: pill`, `border.style: solid`, `elevation: true`) | `surface[]` — tầng ngoài | ✅ |
+| **Quan hệ bố cục** (`sizing`, `justify`, `align`, `effective_align`, `geometry[].box`) | `layout_groups_hint[]` / `geometry[]` — tầng ngoài | ✅ |
+| Tên token đã snap (`radius.lg`, `border.subtle`) | step-05 ghi vào `figma-ds-map.md` | ✅ |
+
+Lệnh cấm nhằm chặn **giá trị hardcode**, không nhằm chặn **ý định thiết kế**. Áp lên cả ý định thì 4a mất luôn radius/border/canh lề — mỗi giá trị đo được phải có một vai trò tương ứng ở tầng ngoài.
+
+### Stage 4.8: Emit `specs/{unit_id}.json` (atomic, sorted)
+
+Một file/unit. State variant nằm trong cùng file, khoá `states.{state}.tree` (không tách file — F3 đọc 1 lần thấy đủ mọi state, khớp L2 mandatory-states audit).
+
+## 4. Decision Points
+
+- **Frame không có Auto Layout nào** (`layoutMode: NONE` toàn bộ) → vẫn emit spec, `layout_groups_hint` = 1 dòng `R1 | Box | ...` **kèm entry `geometry[]` đầy đủ** (Stage 4.2c) + WARN: *"Designer không dùng Auto Layout → composition tree suy từ toạ độ tương đối (`geometry[]`), `confidence` tối đa MEDIUM. F3 đối chiếu ảnh trước khi dán; đề nghị designer bật Auto Layout cho lần sau."* KHÔNG được emit `props: ""` — container rỗng props là thứ đẩy F3 sang đoán mò.
+- **Node có `cornerRadius` nhưng thiếu `absoluteBoundingBox`** (không suy được `s = min(w,h)`) → không emit `radius_role`, ghi `warnings[]`. Suy role bằng px tuyệt đối là sai theo thiết kế (§Stage 4.2b).
+- **Node fetch 404 / thiếu trong response** (frame bị xoá sau khi map) → unit đó `figma_status: stale`, WARN, tiếp tục unit khác. KHÔNG STOP.
+- **Depth 12 vẫn bị cắt** (`children` cuối còn node chưa expand) → WARN liệt kê node bị cắt; tăng `--depth` và fetch lại **chỉ** node đó.
+- **`manual` mode không có structure JSON** → bỏ Stage 4.3-4.7, emit spec tối thiểu `{ states: {...}, source: "png-only" }` + WARN đã nêu ở step-02.
+
+## 5. Output
+
+- `{ds_root}/_reference/figma/specs/{unit_id}.json` (mỗi unit mapped 1 file). Khoá per-state: `tree`, `layout_groups_hint[]`, **`surface[]`**, **`geometry[]`**, `control_hint[]`, `icon_candidates[]`, `copy[]`, `node_count_kept`.
+- `report_sections[]` += `[SPEC EXTRACT]` (per unit: số node giữ/prune, số layout group, **số surface entry, số geometry entry, số node INSTANCE không tra được radius**, số control hint, số icon, số copy, WARN nếu có).
+
+**Self-check trước khi emit (fail-loud — 3 assert):**
+
+1. Mọi `layout_groups_hint[]` entry có `props` **không rỗng**. Rỗng → bug Stage 4.2c/4.3, không phải "frame không có gì".
+2. Không `props` string nào chứa cùng một khoá hai lần (`align=…, align=…`). Có → bug format Stage 4.3.
+3. Mọi node có `cornerRadius != 0` trong `raw` đều có entry `surface[]` tương ứng, **hoặc** có dòng trong `warnings[]` giải thích tại sao không. Lệch → radius đang rơi vào lỗ đen giữa `raw` và tầng ngoài.
+
+Fail bất kỳ assert → STOP với tên node cụ thể. Ba lớp thông tin này mất đi thì **không gate nào phía sau bắt được**: DD vẫn đủ section, code vẫn compile, chỉ giao diện là sai.
+
+**Next:** Read fully and follow `./step-05-ds-reconcile.md`

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/steps/step-05-ds-reconcile.md

@@ -0,0 +1,135 @@
+# Step 5: DS Reconcile
+
+## GOAL
+
+Nối Figma với Master DS ở hai trục và **chỉ report, không apply**:
+1. `figma-ds-map.md` — Figma component instance → DS `component_id`; Figma style/variable → token path.
+2. `token-gap-report.md` — giá trị ngoài tolerance + cặp contrast fail → input cho DSO chạy `ds-bootstrap --external-tokens`.
+
+## 1. Persona
+
+Procedural. **Không** adopt persona của Stage 4b — skill này không quyết reuse. Tuân thủ **U5 (no fabrication)** và **U3 (không ghi `master_token.json`)** nghiêm ngặt.
+
+## 2. Inputs
+
+- `specs/{unit_id}.json` (step-04) — `control_hint[].figma_component`, `raw` values.
+- `{ds_root}/components_metadata.json` — inventory thật (`usage`, `recipes[]`).
+- `{ds_root}/master_token.json` — token canonical.
+- `{family_root}/_shared/pattern-matcher.md` — **SSoT thuật toán matching**. KHÔNG restate công thức ở đây.
+- `{family_root}/_shared/best-practices.md` — **SSoT công thức WCAG contrast**. KHÔNG restate.
+- Config `snap_tolerance`, `token_gap_warn_threshold`.
+
+> **Multi-DS:** chỉ đối chiếu với `components_metadata.json` / `master_token.json` của **DS đã resolve cho unit** (step-03 Stage 3.4). Match chéo sang DS khác là sai — component DS khác không import được (`ds-resolution.md` nhánh B).
+
+## 3. Pipeline
+
+### Stage 5.1: Figma component → DS `component_id`
+
+Với mỗi `figma_component` distinct (dedupe trước — 1 file Figma thường dùng 1 component ở 30 chỗ):
+
+1. Chạy matching **theo thủ tục** `_shared/pattern-matcher.md` §5 trên **toàn bộ** `components_metadata.json` (trừ category `layout-primitive` — đã xử lý qua `layout_groups_hint` ở step-04).
+2. Nguồn cho 4 signal của pattern-matcher, ánh xạ từ dữ liệu Figma:
+
+   | Signal | Lấy từ |
+   |---|---|
+   | intent (0.40) | Tên component Figma + `role` của text con + `intent` ở `control_hint` |
+   | structural (0.25) | Hình dạng child (có icon? có label? có input? mấy slot?) |
+   | tags (0.20) | `componentProperties` (variant prop names/values) |
+   | a11y (0.15) | **Figma không cung cấp** → signal này để trống; ghi rõ trong map là score bị giảm trần. KHÔNG bịa giá trị a11y (U5) |
+
+3. Ghi **top-3 candidate + score** cho mỗi Figma component.
+
+### Stage 5.2: Ngưỡng ghi map (hint — non-binding)
+
+| Top-1 score | Ghi vào `figma-ds-map.md` | Ý nghĩa cho Stage 4b |
+|---|---|---|
+| **≥ 0.95** | `mapped` | Bậc **C-1 Figma-mapped** — 4b reuse trực tiếp, không cần score lại |
+| **0.70 – 0.94** | `likely` | 4b ưu tiên vào shortlist, vẫn score đủ |
+| **< 0.70** | `unmapped` | 4b chạy reuse ladder C0→C3 bình thường như không có Figma |
+
+> **Bất biến:** map này là **hint, non-binding** — hoàn toàn cùng bản chất với cột `DS candidate` ở §2.3. Stage 4b step-01 vẫn là chủ sở hữu duy nhất của quyết định reuse/`[NEW]`. Skill này KHÔNG được ghi `proposed_ds_updates.md`.
+
+### Stage 5.3: Snap raw value → token path
+
+Với mỗi giá trị trong khoá `raw` của specs (`gap`, `padding`, `font_size`, `radius`, `fill`, `stroke`):
+
+1. Tìm token cùng tier trong `master_token.json` có giá trị gần nhất.
+2. |Δ| ≤ `snap_tolerance` (default spacing 2px, radius 2px, font_size 1px; màu: **exact hex** hoặc ΔE ≤ 2) → **snap**: ghi `token_path` vào `figma-ds-map.md` §Token, thêm dòng vào `snap_log` (raw → token → Δ).
+3. |Δ| > tolerance → **gap entry** trong `token-gap-report.md`: raw value, token gần nhất, Δ, số lần xuất hiện, unit nào dùng.
+4. Không có token nào cùng tier → gap entry với `nearest: none`.
+
+`snap_tolerance` là nút xoay quan trọng: chặt quá → report dài vô ích (designer lệch 1px là chuyện thường); lỏng quá → mất ý đồ thật của designer.
+
+**Ngoại lệ BẮT BUỘC — `radius` snap theo VAI TRÒ trước, theo px sau.** Node có `surface[].radius_role` (step-04 Stage 4.2b) thì tra bảng vai trò trước; chỉ khi vai trò không có token tương ứng mới rơi về snap px:
+
+| `radius_role` | Token đích | Nếu DS không có |
+|---|---|---|
+| `pill` | token có value `9999px` (thường `radius.full`) | **gap entry `RADIUS_PILL_MISSING`** — xem dưới |
+| `circle` | token có value `50%` (thường `radius.circle`) | gap entry |
+| `rounded-lg` / `-md` / `-sm` | snap px trong nhóm radius | — |
+
+Snap `pill` bằng px là sai theo thiết kế: cùng vai trò pill là `r=24` trên nút cao 48 và `r=28` trên nút cao 56 — snap px cho ra hai token khác nhau cho một ý định, và nút cao hơn thang token thì luôn thiếu. Bo hết hai đầu là **quan hệ với chiều cao**, không phải một con số.
+
+`RADIUS_PILL_MISSING` là gap entry đặc biệt: ghi rõ *"DS không có token radius nào bằng `9999px`. Token `radius.full` hiện là `{value}` — nếu là `50%` thì nó cho ra hình bầu dục trên hộp chữ nhật, KHÔNG phải pill. Sửa `master_token.json` theo `_shared/best-practices.md` §4.8."* Đây là lỗi mô hình token, không phải lỗi designer — nên nó phải nêu tên nguyên nhân thật thay vì báo lệch px.
+
+**`border` snap 2 vế riêng:** `stroke_weight` → token `border.width.*` (thiếu nhóm này → gap entry `BORDER_WIDTH_TOKENS_MISSING`, ghi 1 lần cho cả DS chứ không mỗi node một dòng); `stroke_color` → token color như mọi màu khác. `surface[].border.style` (`solid`/`dashed`) và `.sides` **không snap** — chúng là vai trò, đi thẳng vào `figma-ds-map.md` §[SURFACE] để 4a đọc.
+
+### Stage 5.4: Contrast pre-scan
+
+Với mọi cặp (text fill, background fill của node cha gần nhất có fill) trong specs:
+
+1. Resolve 2 vế sang hex (raw Figma, hoặc token đã snap ở 5.3).
+2. Tính ratio theo công thức **owned bởi** `_shared/best-practices.md` (accessibility section).
+3. < 4.5:1 (normal text) / < 3:1 (large text + UI component) → entry `FIGMA_CONTRAST_FAIL` trong `token-gap-report.md`: unit, node, cặp màu, ratio đo được, ngưỡng cần, gợi ý token đạt chuẩn gần nhất.
+
+> **Tên warning khác có chủ ý.** `WCAG_CONTRAST_FAIL` do Stage 4b step-01 Stage 3.4 **sở hữu độc quyền** (producer duy nhất ở proposal-time). Ở đây là `FIGMA_CONTRAST_FAIL` — tầng sớm hơn, mục đích khác: bắt designer sửa Figma **trước** khi vào slice, chứ không phải chặn build. Không block gì cả.
+
+### Stage 5.5: Emit
+
+`figma-ds-map.md` — 4 section:
+
+```markdown
+# Figma ↔ DS Map — {ds_id}
+> Nguồn: figma-source.json (file {file_key} @ version {version}). HINT, non-binding.
+
+## [COMPONENT]
+| Figma component | Variant props | DS component_id | Score | Status | Top-3 khác |
+|---|---|---|---|---|---|
+| `Button/Primary` | size, state | `app-button` | 0.97 | mapped | app-icon-button (0.62), app-link (0.41) |
+
+## [TOKEN]
+| Figma value | Token path | Δ | Occurrences | Units |
+|---|---|---|---|---|
+| `gap: 16` | `spacing.md` | 0 | 41 | SCR-LIST, SCR-LOGIN |
+| `gap: 14` | `spacing.md` | 2 (snapped) | 6 | SCR-LIST |
+
+## [SURFACE]
+| Unit | Node / group | radius_role | Token radius | border | elevation |
+|---|---|---|---|---|---|
+| SCR-LIST | `button_submit` | pill | `radius.full` | none | — |
+| SCR-LIST | `G4` content card | rounded-lg | `radius.lg` | none | card |
+
+## [UNMAPPED]
+| Figma component | Top-1 score | Ghi chú cho Stage 4b |
+|---|---|---|
+| `SegmentedTabs` | 0.48 | Chưa có tương đương — 4b sẽ chạy reuse ladder C0→C3 |
+```
+
+§[SURFACE] là section 4a đọc để điền `radius=` / `border=` / `elevation=` vào Props của Layout Groups §2.2 — **tên token, không phải px**. Thiếu section này thì 4a chỉ có `radius_role` dạng chữ và phải tự đoán token tương ứng.
+
+`token-gap-report.md` — 2 section: `[TOKEN GAP]` (từ 5.3) + `[CONTRAST]` (từ 5.4), mỗi entry kèm `occurrences` để DSO ưu tiên.
+
+## 4. Decision Points
+
+- **Số gap > `token_gap_warn_threshold` (default 20)** → **WARN + khuyến nghị mạnh**: *"{N} token gap. Nên chạy `/ntapp-figma-ingest --tokens-only` rồi `/ntapp-ds-bootstrap --external-tokens` để hoà giải token TRƯỚC khi vào slice-loop — nếu không mỗi slice sẽ tự propose `[NEW]` rời rạc và Master DS phân mảnh sau vài slice."* Không STOP (người có thể chấp nhận nợ có chủ ý).
+- **`components_metadata.json` rỗng / 0 component** → bỏ Stage 5.1-5.2, `figma-ds-map.md` chỉ có section `[TOKEN]` + WARN: *"DS chưa có component nào — chạy `/ntapp-ds-bootstrap` trước để map có nghĩa."*
+- **Màu resolve fail** (gradient, image fill, blend mode) → ghi `UNRESOLVED` trong gap report, bỏ khỏi contrast scan. KHÔNG đoán màu đại diện (U5).
+- **Cùng Figma component map 2 DS khác nhau** (multi-DS, 1 Figma file phủ nhiều FE repo) → hợp lệ, không phải lỗi. Ghi riêng ở map của từng DS.
+
+## 5. Output
+
+- `{ds_root}/_reference/figma/figma-ds-map.md`.
+- `{ds_root}/_reference/figma/token-gap-report.md`.
+- `report_sections[]` += `[DS RECONCILE]` (mapped/likely/unmapped count, snap count, gap count, contrast fail count, **số surface entry đã gắn token + `RADIUS_PILL_MISSING`/`BORDER_WIDTH_TOKENS_MISSING` nếu có**).
+
+**Next:** Read fully and follow `./step-06-frame-export.md`

package/skills/NTAPP/.agent/skills/NTAPP-figma-ingest/steps/step-06-frame-export.md

@@ -0,0 +1,77 @@
+# Step 6: Frame Export
+
+## GOAL
+
+Export PNG mỗi unit (+ mỗi state) vào `frames/` — đây là thứ Agent F3 ở Stage 4a **thực sự xem** khi transcribe wireframe.
+
+Step này **graceful**: export fail không STOP run (specs từ step-04 vẫn dùng được).
+
+## 1. Persona
+
+Procedural. Tuân thủ **U6 (URL hygiene)** — signed URL S3 tuyệt đối không được lưu vào artifact.
+
+## 2. Inputs
+
+- `figma-manifest.yaml` — unit mapped + `states[]` + `node_id`.
+- Config `export_scale` (default 2).
+- (`manual` mode) file PNG trong `inbox/frames/`.
+
+## 3. Pipeline
+
+### Stage 6.1: Gom danh sách node cần export
+
+Một entry/`(unit_id, state)`. Unit có `figma_status: missing` hoặc `stale`, frame `ignore: true` → không export.
+
+Tên file đích:
+- `frames/{unit_id}.png` cho state `default`.
+- `frames/{unit_id}__{state}.png` cho state khác (`SCR-LIST__empty.png`).
+
+Dùng `__` (2 gạch dưới) làm separator để phân biệt với dấu `-` trong chính unit id (`SCR-LOGIN`).
+
+### Stage 6.2: Request render + download
+
+Ghi trước file **`name-map.json`** — INPUT của script, map `node_id` → basename đích (không đuôi):
+
+```json
+{ "12:340": "SCR-LOGIN", "12:411": "SCR-LOGIN__error" }
+```
+
+```bash
+bash <skill_dir>/scripts/figma-fetch.sh images \
+  --ids "12:340,12:411" --scale 2 --format png \
+  --dest "{output_root}/frames" \
+  --name-map "{output_root}/.work/name-map.json"
+```
+
+Script ghi thẳng tên file đích (không cần pass rename) và in **TSV** ra stdout — `ok<TAB>node<TAB>path` / `fail<TAB>node<TAB>reason`. Đọc TSV này để điền `frame_exported`. Entry thiếu trong name-map → fallback `node_{id}.png` (không mong muốn — kiểm lại name-map nếu thấy tên này).
+
+Cơ chế 2 pha của Figma (script lo, ghi lại ở đây để hiểu khi debug):
+1. `GET /v1/images/:key?ids=...` → JSON `{"images": {"12:340": "https://s3..."}}` — **signed URL, hết hạn sau ít phút**.
+2. Download từng URL → ghi `.part` → rename (U1).
+
+Script **không** in URL ra stdout và **không** lưu vào bất kỳ artifact nào (U6) — URL rot thì manifest trỏ vào rác.
+
+Kích thước: `scale 2` cho desktop 1440px ra ~2880px. File > 4MB → tự hạ scale về 1 cho node đó + ghi WARN (PNG chỉ để người xem, không cần pixel-perfect).
+
+### Stage 6.3: `manual` mode
+
+Copy từ `inbox/frames/` sang `frames/` theo mapping đã ký ở step-03 (tên file trong inbox thường là tên frame, không phải unit id → rename theo mapping). File thiếu → unit đó ghi WARN, không STOP.
+
+### Stage 6.4: Verify
+
+Mỗi file: tồn tại + kích thước > 0 + magic bytes PNG (`89 50 4E 47`). Fail → xoá file lỗi, WARN, ghi `frame_exported: false` cho unit đó.
+
+## 4. Decision Points
+
+- **`/v1/images` trả `err` non-null** (thường: node quá lớn để render) → WARN, `frame_exported: false`, tiếp tục unit khác. Hint trong report: *"Frame `{name}` quá lớn để Figma render — nhờ designer tách frame nhỏ hơn, hoặc F3 dùng specs JSON thay ảnh."*
+- **429 rate-limit** → script tự backoff (exponential, ≤3 lần). Hết retry → WARN, `frame_exported: false` cho phần còn lại + hint chạy lại step này sau ít phút (re-ingest sẽ skip unit đã export nhờ checksum).
+- **Download timeout / URL hết hạn** → request lại `/v1/images` cho đúng node đó (≤1 lần), rồi WARN nếu vẫn fail.
+- **Toàn bộ export fail** → **KHÔNG STOP**, nhưng WARN nặng: *"0 PNG export được. Stage 4a sẽ chỉ có specs JSON (đủ để dựng Layout Groups, thiếu cảm nhận thị giác). Kiểm quyền file / thử lại sau."*
+
+## 5. Output
+
+- `{ds_root}/_reference/figma/frames/{unit_id}[__{state}].png`.
+- Cập nhật `frame_exported: true|false` per `(unit, state)` — step-07 ghi vào manifest.
+- `report_sections[]` += `[FRAME EXPORT]` (số file, tổng dung lượng, danh sách fail + lý do).
+
+**Next:** Read fully and follow `./step-07-emit.md`