@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-02-executive-summary.md

@@ -0,0 +1,38 @@
+# STEP 02: EXECUTIVE SUMMARY (§1 — slim)
+
+> **Thực hiện bởi:** Agent UX2 (PM Liaison — John)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — emphasize **R3, R4, R10**.
+
+## 1. Mục tiêu
+
+Thiết lập bối cảnh + mục tiêu đo được cho Journey Spec — NGẮN (chi tiết nằm trong PRD, cite thay vì chép lại). Kèm persona references (actor lock: HLD §3.1.1 — bắt buộc; nguồn chi tiết: `ux_sketch.md` nếu có / PRD §User Stories nếu không).
+
+## 2. Đầu vào cần đọc
+
+- PRD: Background, Vision, Success Criteria, User Journeys
+- Briefing từ Step 01 (locked actor list, sketch status)
+- `ux_sketch.md` §Personas (nếu có)
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §1.1 Context & Vision
+
+- ≤2 đoạn: hệ thống/quy trình hiện tại + pain chính (quantified nếu PRD có số — không bịa số) + 1 câu UX vision (metaphor dễ nhớ).
+- KHÔNG lập bảng hiện trạng dài — cite PRD section thay vì chép.
+
+### 3.2. §1.2 Design Goals
+
+Bảng `| Mục tiêu | Đo lường |` — tối thiểu 3, mỗi measurement có CON SỐ, truy ngược PRD success criteria.
+
+### 3.3. §1.3 Personas (reference — KHÔNG viết lại persona table)
+
+- 1 dòng/role: `{Persona name} — {role}: {mục tiêu chính}` → pointer `ux_sketch.md §Personas` (có sketch) hoặc `PRD §User Stories` (không sketch).
+- Chỉ liệt kê actor CÓ trong HLD §3.1.1 lock (R10). Actor PRD nhắc mà HLD không có → escalate R7 #4, không tự thêm.
+
+## 4. Đầu ra yêu cầu
+
+- **Lưu trữ:** `{intermediate_folder}/ux2_executive_summary_part.md`
+- Nội dung: §1.1 + §1.2 + §1.3 theo template v4.0.
+- Báo cáo: "§1 hoàn tất. {X} goals đo được, {Y} personas referenced (actor lock HLD OK)."
+
+**Next:** Read fully and follow `./step-04-ux-principles.md` *(step-03 personas đã retired — §1.3 chỉ reference: actor lock HLD §3.1.1, chi tiết ux-sketch nếu có / PRD nếu không)*

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-04-ux-principles.md

@@ -0,0 +1,53 @@
+# STEP 04: UX PRINCIPLES → `ux_conventions.md` §C1
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — emphasize **R3, R5, R10**. Ghi TRỰC TIẾP vào `ux_conventions.md` (ngoại lệ R1 khai báo).
+
+## 0. Delta-mode check (chạy TRƯỚC)
+
+`conventions_mode: delta` (Step 01) VÀ §C1 hiện có vẫn đúng cho feature mới (không principle mới, không mâu thuẫn) → **SKIP**: log *"§C1 no delta"* + đi Next. Feature đòi principle mới / sửa principle cũ → chỉ **append/patch** mục thay đổi + CHANGE LOG row (không viết lại cả section).
+
+## 1. Mục tiêu
+
+Xác lập "hiến pháp" UX của PROJECT (không phải per-feature): nguyên tắc cốt lõi + nguyên tắc đặc thù domain. Mọi wireframe Stage 4a + screen Stage 5 tuân theo.
+
+## 2. Đầu vào cần đọc
+
+- §1 Executive Summary part (pain, vision, goals)
+- PRD: Business Rules, constraints
+- Briefing Step 01; `ux_conventions.md` hiện có (delta mode)
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §C1 Core Principles
+
+Bảng tối thiểu 7 nguyên tắc — mỗi nguyên tắc PHẢI có cột "Áp dụng trong {{project_name}}" với ví dụ CỤ THỂ (UI element/flow, không chung chung):
+
+| # | Nguyên tắc | Mô tả | Áp dụng trong {{project_name}} |
+|:--|:-----------|:------|:-------------------------------|
+| 1 | **Progressive Disclosure** | Chỉ hiển thị thông tin cần thiết tại thời điểm hiện tại | _element/flow cụ thể_ |
+| 2 | **Consistency** | Cùng hành động → cùng giao diện, vị trí, hành vi | _button/pattern cụ thể_ |
+| 3 | **Error Prevention** | Ngăn lỗi trước khi xảy ra | _disable/validate/auto-save cụ thể_ |
+| 4 | **Recognition over Recall** | Hiển thị ngữ cảnh, không yêu cầu nhớ | _auto-populate, labels, badges_ |
+| 5 | **Feedback & Visibility** | Mọi hành động có phản hồi rõ ràng, kịp thời | _toast, progress, rejection detail_ |
+| 6 | **Flexibility & Efficiency** | Hỗ trợ cả người mới và người thành thạo | _guided flow vs shortcut_ |
+| 7 | **Minimal Input** | Giảm thiểu nhập liệu thủ công | _auto-populate, dropdown, template_ |
+
+> **Enforcement reference (không duplicate):** §C1 được enforce qua rule catalog `{design_system_path}/_shared/layout-best-practices.md` (L1-L11). ux-design owns audit **L5/L6/L9** (journey/IA-level, warn-only — gate R6 sau step 09-10). Composition-level (L1/L2/L7…) owner là `feature-design`. **Chỉ cite rule ID, KHÔNG chép nội dung rule.**
+
+### 3.2. §C1 Domain-Specific Principles
+
+Phân tích mô hình tương tác chính (theo archetype sẽ chốt ở step-08 — dùng preliminary hint từ PRD) → tối thiểu 4 nguyên tắc đặc thù, format `| Nguyên tắc | {{Role A}} nhìn thấy | {{Role B}} nhìn thấy |`, mô tả CONCRETE UI elements.
+
+### 3.3. Kiểm tra chéo
+
+- Mỗi pain point (§1.1) có ≥1 nguyên tắc giải quyết?
+- Mỗi design goal (§1.2) có ≥1 nguyên tắc hỗ trợ?
+- Nguyên tắc xung đột → ghi chú ưu tiên.
+
+## 4. Đầu ra yêu cầu
+
+- **Ghi trực tiếp:** `{planning_artifacts}/ux_conventions.md` §C1 (atomic write) + CHANGE LOG row.
+- Báo cáo: "§C1 {bootstrap hoàn tất | delta: X mục | no delta}."
+
+**Next:** Read fully and follow `./step-06-content-strategy.md` *(step-05 design-system đã retired — DS vocabulary đi qua component_catalog.md digest)*

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-06-content-strategy.md

@@ -0,0 +1,48 @@
+# STEP 06: CONTENT STRATEGY & MICROCOPY → `ux_conventions.md` §C2
+
+> **Thực hiện bởi:** Agent UX4 (Content Strategist — Paige)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5, R8.2 (Module 0 §7 read-only cho status), R10**. Ghi TRỰC TIẾP vào `ux_conventions.md` (ngoại lệ R1).
+
+## 0. Delta-mode check (chạy TRƯỚC)
+
+Delta mode VÀ §C2 hiện có cover đủ feature mới → SKIP (log "§C2 no delta"). Feature mới thêm entity/status enum mới (Module 0 §7 có enum chưa map) hoặc empty/loading state mới → chỉ append rows tương ứng + CHANGE LOG.
+
+## 1. Mục tiêu
+
+"Giọng nói" của product (project-wide): writing rules, microcopy (empty/loading), status labels canonical-mapped Module 0 §7.
+
+**Lưu ý:** Notification copy KHÔNG ở đây — single source of truth là §C4 (step-12).
+
+## 2. Đầu vào cần đọc
+
+- §1 part (bối cảnh + domain terminology) + §C1 (Feedback & Visibility, Error Prevention)
+- Module 0 §7 Global State Registry (nếu có) — state enum cho status labels (R8.2 1-1)
+- `component_catalog.md` — component EmptyState/Skeleton nếu có (R5 — gọi đúng tên; thiếu → `[gap — propose Stage 4b]`)
+- `master_token.json` — verify `semantic.color.status.*` token paths
+- PRD — BR trạng thái workflow
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §C2 UI Content Writing Rules
+
+Bảng `| Quy tắc | Ví dụ đúng | Ví dụ sai |` ≥5 quy tắc bắt buộc (adapt example theo domain THẬT):
+1. **Ngắn gọn, hành động** — verb-first label; 2. **Ngôi thứ 2**; 3. **Nói rõ hệ quả**; 4. **Không mã lỗi kỹ thuật**; 5. **Hướng dẫn sửa, không chỉ báo lỗi**.
+
+### 3.2. §C2 Contextual Microcopy
+
+- **Empty State** (structured spec, KHÔNG ASCII): Icon + Headline + Guidance + CTA; component từ catalog. Minimum 2 (primary view + secondary view nếu có).
+- **Loading State**: skeleton (load data) vs spinner + message (submit — đặt expectation).
+
+### 3.3. §C2 Status Labels
+
+Bảng `| Display Status | Color (token path) | Module 0 §7 enum | User Description |`:
+- Color reference `semantic.color.status.*` — KHÔNG hex.
+- 1-1 mapping với Module 0 §7 enum (R8.2 + R10): mỗi enum đúng 1 row, 1 label không map nhiều enum. Module 0 §7 thiếu → derive từ PRD BR + mark "pending Tech Lead reconcile".
+- Cover lifecycle theo archetype (preliminary — step-08 confirm; lệch → quay lại patch).
+
+## 4. Đầu ra yêu cầu
+
+- **Ghi trực tiếp:** `ux_conventions.md` §C2 + CHANGE LOG row.
+- Báo cáo: "§C2 {bootstrap | delta X rows | no delta}. {Z} status labels 1-1 Module 0 §7."
+
+**Next:** Read fully and follow `./step-07-information-architecture.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-07-information-architecture.md

@@ -0,0 +1,61 @@
+# STEP 07: INFORMATION ARCHITECTURE & NAVIGATION (§3 — delta-aware)
+
+> **Thực hiện bởi:** Agent UX3 (IA & System Architect — Winston)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5, R8.4 (WBS lock), R10**.
+
+## 1. Mục tiêu
+
+Đặt screens MỚI của feature vào kiến trúc điều hướng: nav model + nav tree (DELTA cho brownfield) + shell placement. Journey Spec §3.
+
+## 2. Đầu vào cần đọc
+
+- §1 part: anchor system, personas references (mental model)
+- `project_wbs.md` — **SSoT** `SCR-*`/`WGT-*` list của feature (R8.4)
+- `ux_design.md` cũ §3 (nếu brownfield-per-feature) — nav tree hiện có
+- `ux_conventions.md` §C6 shell blueprint (nếu đã có từ trước)
+- `component_catalog.md` — nav components có sẵn (sidebar/tabs/breadcrumb)
+- PRD FR navigation; HLD §3.2.0 module list
+- PRD primary user story → **preliminary archetype hint** (confirm chính thức ở step-08)
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §3.1 Navigation Principle & Tree
+
+**Bước 1 — nav model** (giữ model đã có nếu brownfield — đổi model là quyết định lớn, escalate):
+
+| Model | Khi nào dùng |
+|:---|:---|
+| **Action-Based** — menu theo business goal | Persona nghĩ theo công việc; anchor tích hợp ≥2 backend |
+| **System-Based** — menu theo module | Persona tech-savvy; mỗi hệ thống một domain |
+| **Entity-Based** — menu theo entity chính | Single primary entity; CONTENT_MGMT / DASHBOARD |
+| **Hybrid** | Mix |
+
+**Bước 2 — ASCII nav tree, chế độ DELTA:**
+- **Brownfield** (`ux_design.md` cũ tồn tại): CHỈ vẽ node mới + node neo (cha/anh em trực tiếp, đánh dấu `(existing)`). KHÔNG vẽ lại toàn tree.
+- **Lần đầu:** vẽ tree đầy đủ.
+
+```
+{{anchor}} Shell
+├── (existing) Quản lý đối tác
+│   ├── (existing) Danh sách merchant
+│   └── [NEW] Đối soát giao dịch          ← SCR-RECON-LIST
+│       └── [NEW] Chi tiết đối soát       ← SCR-RECON-DETAIL
+```
+
+**Quality:**
+- Mỗi leaf node MỚI ↔ đúng 1 `SCR-*` trong WBS (R8.4 — thiếu screen trong WBS → escalate `/ntapp-architecture-design --append`, KHÔNG tự đặt ID).
+- Annotate role-restricted. Label nhất quán nav model.
+
+### 3.2. §3.2 Shell Placement
+
+- Screens mới dùng shell NÀO: reference `ux_conventions.md` §C6 shell blueprint nếu đã có (1 dòng: "đặt trong content area của shell chuẩn, breadcrumb cấp 2"). Chưa có shell doc → chọn region set theo preliminary archetype (decision matrix để step file cũ — emit kết luận + ASCII 1 khung đơn giản, chi tiết shell về §C6 ở step-13).
+- Optional region → kèm justification. Action bar: secondary trái, primary phải (§C1 Consistency).
+- Preliminary archetype đổi ở step-08 → quay lại sửa §3.2.
+
+## 4. Đầu ra yêu cầu
+
+- **Lưu trữ:** `{intermediate_folder}/ux3_ia_part.md`
+- Nội dung: §3.1 (delta tree) + §3.2.
+- Báo cáo: "§3 hoàn tất. Nav model: {giữ nguyên/chọn mới}, {X} node mới ↔ WBS OK, shell: {ref §C6 / mô tả mới}."
+
+**Next:** Read fully and follow `./step-08-information-hierarchy.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-08-information-hierarchy.md

@@ -0,0 +1,59 @@
+# STEP 08: WORKFLOW ARCHETYPE & INFORMATION MODEL (§2)
+
+> **Thực hiện bởi:** Agent UX3 (IA & System Architect — Winston)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5, R8, R10**.
+
+## 1. Mục tiêu
+
+Chốt workflow archetype của feature, mô tả primary entity + composition model, state taxonomy + cross-section data propagation. Journey Spec §2 — nền cho §4 journeys.
+
+## 2. Đầu vào cần đọc
+
+- §3 part (IA — nav tree, shell placement) + §1 part (context, personas)
+- PRD: primary user story (entity + archetype), business rules (composition + lifecycle), data dependency
+- Module 0 §7 Global State Registry (nếu có) — state enum
+- `master_token.json` — verify `semantic.color.status.*` paths
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §2.1 Workflow Archetype
+
+Chọn 1 archetype:
+
+| Archetype | Pattern | Khi nào dùng |
+|:---|:---|:---|
+| MAKER_CHECKER | Creator submit → Reviewer approve/reject | Compliance form, approval workflow |
+| WIZARD | Linear single-actor multi-step | Onboarding, form chia bước |
+| DASHBOARD | Read-heavy + embedded action | Analytics, monitoring, ops console |
+| TRANSACTIONAL | Single-actor single-submission | Simple form, search, lookup, config |
+| CONTENT_MGMT | Create/edit/publish với draft state | CMS, docs, knowledge base |
+| OTHER | Custom — mô tả entry signal → action sequence → terminal state (≤5 dòng) | — |
+
+**Output:** 1 archetype + 1-2 dòng justification cite PRD primary user story.
+
+**Hybrid check:** PRD chứa 2 archetype song song → split 2 spec riêng, KHÔNG mix. Báo user xác nhận scope split (GATE cuối step).
+
+### 3.2. §2.2 Primary Entity & Composition Model
+
+1. Entity theo BUSINESS term (không "record"/"row").
+2. Composition model: SINGLE / SECTIONED / LINEAR_STEPS / REFERENCE.
+3. ASCII diagram sub-section/step + data-flow direction (shape theo composition thực — SINGLE rõ ràng thì skip diagram). Mark Required/Optional + điều kiện kích hoạt.
+
+### 3.3. §2.3 Section Status & Data Propagation
+
+**Skip nếu composition = SINGLE.**
+
+1. **State taxonomy** — universal: Empty / In-progress / Complete / Error; archetype-conditional: Locked + Rejected [MAKER_CHECKER], Blocked [WIZARD], Draft + Published [CONTENT_MGMT]. Mỗi state: icon + color token path + 1 dòng business meaning. KHÔNG bịa state ngoài archetype. *(Indicator pattern hiển thị + transition behavior chi tiết thuộc `ux_conventions.md` §C3 — step-11; ở đây chỉ khoá taxonomy.)*
+2. **Cross-section propagation** (skip nếu sections độc lập data): bảng `| Source | Field | → Target | Field | Type (AUTO_READONLY/AUTO_EDITABLE/DERIVED/REFERENCE_LOOKUP) | Timing | Conflict Policy |` — liệt kê EVERY field cross-section; auto-populated field → journey table Key states ghi badge nguồn.
+
+## 4. Đầu ra yêu cầu
+
+- **Lưu trữ:** `{intermediate_folder}/ux3_modular_part.md`
+- Nội dung: §2.1 + §2.2 + §2.3 (nếu applicable).
+- Báo cáo: "§2 hoàn tất. Archetype: {X}, composition: {Y}, {Z} states, {W} propagation mappings."
+- Preliminary archetype ở §3.2 (step-07) lệch với archetype chốt → quay lại sửa §3.2 shell placement TRƯỚC khi sang step-09.
+
+## [GATE] — ⛔ KIỂM TRA TRƯỚC KHI SANG STEP KẾ
+- **Hybrid archetype (§3.1):** PRD chứa 2 archetype song song → split 2 spec + **báo user xác nhận scope split** TRƯỚC khi đọc step-09. KHÔNG mix.
+
+**Next:** Read fully and follow `./step-09-primary-journey.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-09-primary-journey.md

@@ -0,0 +1,59 @@
+# STEP 09: PRIMARY USER JOURNEY (§4.1 — Mermaid + Journey Screen Table)
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R2 (Journey Screen Table fidelity — KHÔNG per-screen Screen Spec), R5, R8.4, R10**.
+
+## 1. Mục tiêu
+
+Thiết kế luồng primary role hoàn chỉnh: Mermaid flow + **Journey Screen Table** (1 hàng/screen — intent + key states, KHÔNG spec layout per-screen; đó là việc feature-design Stage 4a).
+
+## 2. Đầu vào cần đọc
+
+- **§2 part** (archetype, composition, state taxonomy, propagation) — quyết định verb set + end states + key states
+- §3 part (nav tree — leaf nodes khớp screens) + §1 part (primary persona)
+- `project_wbs.md` — SCR-* ID (R8.4)
+- `ux_conventions.md` — §C-x refs cho cột Conventions refs
+- PRD — primary user story, FR/BR liên quan; HLD §3.2.2 sequence diagrams (reference)
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §4.1 Flow Diagram (Mermaid)
+
+`flowchart TD` cho toàn primary journey. Verb set + end states theo archetype §2.1:
+
+| Archetype | Verb sequence | End states |
+|:---|:---|:---|
+| MAKER_CHECKER | input → validate → submit → await review | submitted/awaiting-review, draft-saved |
+| WIZARD | step → validate → next-step → finalize | completed, abandoned |
+| DASHBOARD | view → filter → drill-down → embedded action | action-executed, navigated-away |
+| TRANSACTIONAL | input → validate → submit → confirm | success-confirmed, failure |
+| CONTENT_MGMT | create → edit → save-draft → publish | published, drafted, archived |
+| OTHER | (custom per §2.1) | — |
+
+Rules: decision node diamond; critical/terminal node color = token reference (không hex); cover happy path + major branches; KHÔNG vẽ branch ngoài archetype; recovery path chỉ khi archetype có draft/long-form.
+
+### 3.2. §4.1 Journey Screen Table (R2 canonical — 5 cột, không thêm không bớt)
+
+Mỗi screen/step trong Mermaid → đúng 1 hàng:
+
+```markdown
+| Screen (SCR-*) | Purpose (1 dòng) | Key states | Entry ← / Exit → | Conventions refs |
+|:---|:---|:---|:---|:---|
+| SCR-RECON-LIST | Duyệt danh sách đối soát cần xử lý | Empty / Loading / Error / Loaded | ← nav §3.1; → SCR-RECON-DETAIL | §C3 transition, §C4 evt `recon-assigned` |
+```
+
+- `SCR-*` từ WBS (R8.4). `Key states` từ taxonomy §2.3 — ràng buộc tối thiểu Stage 4a PHẢI cover; auto-populated field → ghi `auto-badge từ {source}` vào Key states.
+- **Sketch preview link (chỉ khi sketch tồn tại):** screen kế thừa từ frame sketch — tra bảng **Preview Index** cuối §4 `ux_sketch.md` (match theo screen name/purpose; tên 3b thường kế thừa sketch) → append vào CUỐI cell `Purpose`: ` ([sketch]({path}#{screen_slug}))` với path repo-relative resolve từ folder `{ux_sketch_path}` (vd `NTAPP-output/Stage_1_Discovery/ux_sketch/previews/{feature_slug}_ux_sketch_preview.html#compose-message`). Link nằm TRONG cell Purpose — vẫn ĐÚNG 5 cột (R2), KHÔNG thêm cột. Screen không có frame khớp / không có sketch → bỏ qua, không placeholder.
+- **CẤM** thêm cột Regions/Components/wireframe (R2 — leo thang về per-screen spec là tái tạo drift đã cắt). Chi tiết màn = DD Stage 4a.
+- Step count minimum theo archetype: MAKER_CHECKER/WIZARD/CONTENT_MGMT ≥3; DASHBOARD ≥2; TRANSACTIONAL ≥1+confirm.
+
+### 3.3. Layout self-audit (journey/IA-level — L5/L6/L9, warn-only)
+
+Theo catalog `{design_system_path}/_shared/layout-best-practices.md` (ngưỡng/detection lấy nguyên từ catalog): **L5** progressive disclosure (nhóm advanced/hiếm trên journey), **L6** reading order (primary CTA position trong flow), **L9** IA depth (nesting §3.1). Ghi 1 dòng cuối §4.1: `L5/L6/L9: OK` hoặc warning + đề xuất. KHÔNG audit L1-L4/L7-L8/L10-L11 (owner feature-design).
+
+## 4. Đầu ra yêu cầu
+
+- **Lưu trữ:** `{intermediate_folder}/ux0_journeys_part.md` (phần §4.1)
+- Báo cáo: "§4.1 hoàn tất. {X} steps, {Y} screens (WBS OK), {Z} decision points, L5/L6/L9: {OK/warnings}."
+
+**Next:** Read fully and follow `./step-10-secondary-journeys.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-10-secondary-journeys.md

@@ -0,0 +1,43 @@
+# STEP 10: SECONDARY & ADDITIONAL ROLE JOURNEYS (§4.2-4.3)
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R2 (Journey Screen Table fidelity), R5, R8.4, R10**.
+
+## 1. Mục tiêu
+
+Journey cho secondary role (§4.2 — role có responsibility khác primary trên cùng entity) và mỗi additional role (§4.3, nếu ≥3 role). Cùng format step-09: Mermaid + Journey Screen Table (mọi rule §3.2 step-09 áp dụng — kể cả sketch preview link trong cell Purpose khi có) — KHÔNG per-screen Screen Spec.
+
+## 2. Đầu vào cần đọc
+
+- §2 part (archetype) + §4.1 (primary journey — để close loop) + §1.3 (role enumeration)
+- `project_wbs.md` (SCR-* — R8.4); `ux_conventions.md` (§C-x refs)
+- PRD — user story phụ + BR approval/oversight/external boundary
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §4.2 Secondary Role Journey
+
+**Applicability:** ≥2 distinct role non-overlapping trên cùng entity. Pattern: MAKER_CHECKER (reviewer) / COLLABORATIVE (co-author) / ADMIN_OVERSIGHT (auditor). **Single-role app → SKIP §4.2, KHÔNG placeholder.**
+
+1. **Mermaid** — archetype-specific: MAKER_CHECKER `entry → queue → detail → decision → confirmation`; COLLABORATIVE `notification → review → comment/approve → notify back`; ADMIN_OVERSIGHT `dashboard → drill-down → action`. Entry signal cụ thể; end state close-loop với primary nếu archetype yêu cầu (node feedback + hàng tương ứng trong table §4.1 Key states — vd `Rejected (editable + reason)`).
+2. **Journey Screen Table** (R2 — 5 cột): queue/list screen (nếu role xử lý batch), detail/decision screen, feedback-to-primary (thể hiện qua Key states của screen primary bị ảnh hưởng — KHÔNG spec màn mới nếu WBS không có). Key states nắm intent quyết định: vd `per-section Approve/Reject + reason bắt buộc khi reject` — chi tiết control là việc Stage 4a.
+
+### 3.2. §4.3 Additional Role Journeys
+
+**Applicability:** ≥3 distinct role. 1 sub-section per role. Pattern: SELF_SERVICE / ADMIN_CONFIGURATOR / READ_ONLY_AUDITOR / BATCH_OPERATOR / API_CONSUMER / OTHER.
+
+Mỗi role: (1) **Role Context** 1-2 dòng (vì sao tách — access scope / UI simplification / external boundary; không copy-paste primary/secondary); (2) **Mermaid**; (3) **Journey Screen Table**. Skip role không có user story trong PRD — KHÔNG placeholder TBD.
+
+### 3.3. Layout self-audit
+
+Cùng L5/L6/L9 warn-only như step-09 §3.3 — 1 dòng cuối mỗi journey.
+
+## 4. Đầu ra yêu cầu
+
+- **Lưu trữ:** Append `{intermediate_folder}/ux0_journeys_part.md` (§4.2-4.3)
+- Báo cáo: "§4.2-4.3 hoàn tất. Secondary: {X screens}; Additional: {N} role; WBS OK; L5/L6/L9: {…}."
+
+## [GATE R6] — WBS ↔ Journey Sync (sau step 09+10)
+> Mọi `SCR-*` trong §4 tables tồn tại trong `project_wbs.md`? Lệch → sửa journey hoặc escalate WBS amend (R8.4). KHÔNG đọc step-11 khi chưa sync.
+
+**Next:** Read fully and follow `./step-11-interaction-patterns.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-11-interaction-patterns.md

@@ -0,0 +1,47 @@
+# STEP 11: INTERACTION PATTERNS → `ux_conventions.md` §C3
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5, R6**. Ghi TRỰC TIẾP vào `ux_conventions.md` (ngoại lệ R1).
+
+## 0. Delta-mode check (chạy TRƯỚC)
+
+Delta mode VÀ §C3 hiện có cover đủ state taxonomy + action set của feature mới → SKIP (log "§C3 no delta"). Feature thêm state/transition/dialog/shortcut mới → append rows tương ứng + CHANGE LOG.
+
+## 1. Mục tiêu
+
+"Luật chơi" tương tác project-wide: validation, transition, confirmation dialog, keyboard shortcut. Mọi screen (mọi feature) tuân theo.
+
+## 2. Đầu vào cần đọc
+
+- Journey spec §2 (archetype + composition + state taxonomy §2.3) + §4 (flows, decision points)
+- §C1 (Error Prevention, Consistency, Flexibility) + §C2 (error message writing rules)
+- `component_catalog.md` — form/dialog components; `master_token.json` — verify token (vd `semantic.color.border.danger`)
+- PRD — BR validation, FR auto-save
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §C3 Form Validation Rules
+
+**Skip nếu** archetype không có input (DASHBOARD read-only). Timing 3 loại: inline on-blur (simple field) / on-submit (full form) / cross-section (composition ≠ SINGLE). Error surface spec (structured, token refs): inline field error (border `border.danger` + icon + message dưới field) + summary panel on submit (count + jump-link). Message theo §C2 guide-to-fix.
+
+### 3.2. §C3 View / Tab / Section Transition
+
+**Applicability:** composition ≠ SINGLE. Bảng `| Scenario | Behavior |` cover ĐỦ state taxonomy journey-spec §2.3: switch khi valid (auto-save + switch nếu có draft) / switch khi error (dialog keep-save-discard-stay) / click Locked (tooltip dependency cụ thể) / click Blocked (tooltip prerequisite) / click optional / click Rejected (prefill reason ở top). Skip state không tồn tại trong archetype.
+
+### 3.3. §C3 Confirmation Dialogs
+
+Bảng `| Action | Has dialog? | Content principle |`:
+- Universal: Delete (YES — "không hoàn tác"), Cancel-with-unsaved (YES), Save draft (NO — toast silent), field edit (NO).
+- Archetype-conditional: Submit-for-review / Approve-Reject (MAKER_CHECKER, reject cần reason), Finalize (WIZARD), Submit-tác-động-data (TRANSACTIONAL), Publish (CONTENT_MGMT), Execute-embedded-action (DASHBOARD).
+- Nguyên tắc: irreversible → BẮT BUỘC dialog; undo dễ → silent + undo; dialog nói rõ HỆ QUẢ (§C2); destructive → button `danger`. KHÔNG bịa action ngoài archetype.
+
+### 3.4. §C3 Keyboard Shortcuts
+
+Universal FORM-HEAVY: Tab/Shift+Tab, Esc, Ctrl+S (archetype có draft), Ctrl+Enter (final review). Archetype-conditional: Alt+1..N (multi-section), Ctrl+A/Ctrl+R (MAKER_CHECKER reviewer), Ctrl+F / R (DASHBOARD), Ctrl+P (CONTENT_MGMT). Không đè browser default (Ctrl+T/W).
+
+## 4. Đầu ra yêu cầu
+
+- **Ghi trực tiếp:** `ux_conventions.md` §C3 + CHANGE LOG row.
+- Báo cáo: "§C3 {bootstrap | delta | no delta}. {Y} transition scenarios (cover đủ taxonomy §2.3), {W} dialogs, {V} shortcuts."
+
+**Next:** Read fully and follow `./step-12-notification-error.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-12-notification-error.md

@@ -0,0 +1,65 @@
+# STEP 12: NOTIFICATION SYSTEM & ERROR RECOVERY → `ux_conventions.md` §C4-C5
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally) + Agent UX4 (Content Strategist — Paige)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5, R8.3** (notification ↔ error name consistency; severity color token canonical). Ghi TRỰC TIẾP vào `ux_conventions.md` (ngoại lệ R1).
+
+## 0. Delta-mode check (chạy TRƯỚC)
+
+Delta mode VÀ event set + error types của feature mới đã cover → SKIP. Feature thêm event/error type mới (vd entity mới có lifecycle mới) → append rows + CHANGE LOG.
+
+## 1. Mục tiêu
+
+§C4 Notification System (ma trận event×recipient×channel×title×detail — single source of truth) + §C5 Error Handling & Recovery (principles + classification + archetype edge cases). Project-wide.
+
+## 2. Phân công
+
+| Nội dung | Agent |
+|:---|:---|
+| §C4 Event Matrix + Notification Components | UX4 |
+| §C5 Principles + Classification + Edge Cases | UX0 + UX4 |
+
+## 3. Đầu vào cần đọc
+
+- Journey spec §2 (archetype, composition, propagation) + §4 (mọi action cần notification)
+- §C2 (writing rules, status labels) — notification/error copy tuân theo
+- `component_catalog.md` — toast/banner/spinner/skeleton components; `master_token.json` — severity color token
+- PRD — NFR notification SLA, FR auto-save, BR conflict policy
+
+## 4. Chỉ thị thực thi
+
+### 4.1. §C4 Event Notification Matrix — UX4
+
+Bảng `| Event | Recipient | Channel | Timing | Title (≤8 words) | Detail |` — single source of truth (KHÔNG duplicate copy sang section khác). Channels: In-app / Email / Toast (kèm duration) / Banner (kèm dismiss policy) / Badge. Timing cite PRD NFR SLA. Event set theo archetype — CHỈ event tồn tại trong workflow:
+
+| Archetype | Event tối thiểu |
+|:---|:---|
+| MAKER_CHECKER | submit / approve / partial-reject / full-reject / post-sync success / post-sync error / conflict |
+| WIZARD | step-complete / abandon / finalize |
+| DASHBOARD | alert / threshold-breach / data-stale |
+| TRANSACTIONAL | success / failure |
+| CONTENT_MGMT | draft-saved / published / publish-failure / collaborator-comment |
+
+Detail: entity reference + actionable guidance + timestamp (nếu time-sensitive); severity color = token canonical.
+
+### 4.2. §C4 Standard Notification Components — UX4
+
+4 pattern `| Pattern | Component (catalog canonical) | Trigger | Dismiss |`: Loading (skeleton/spinner) / Success (toast + auto-dismiss N giây) / Error (banner + guidance + retry — KHÔNG chỉ mô tả lỗi) / Info (badge + dropdown). Component thiếu trong catalog → `[gap — propose Stage 4b]`.
+
+### 4.3. §C5 Universal Error Principles — UX0 + UX4
+
+≥6 principle: (1) never lose input — auto-save trước khi show error [FORM-HEAVY]; (2) cause + recovery guidance, không raw code; (3) luôn ≥1 action button; (4) localize failure scope [composition ≠ SINGLE]; (5) retry limit (max 2 auto rồi manual + suggest cause); (6) severe error kèm reference code + timestamp.
+
+### 4.4. §C5 Error Classification & Visual Patterns
+
+Bảng `| Error Type | User Sees | Severity | Recovery | Applicable Archetype |`. Universal 4: field validation / network disconnect (3 sub-state: initial, extended ≥5min, recovery) / session expiry (auto-save trước modal nếu FORM-HEAVY) / unexpected (catch-all + reference code). Conditional: save failure [FORM-HEAVY], section load failure [≠SINGLE], data refresh failure [DASHBOARD], post-decision sync failure [MAKER_CHECKER], edit conflict [COLLABORATIVE], publish conflict [CONTENT_MGMT]. Mỗi type: surface (inline/banner/modal theo severity) + region behavior + recovery CTA (structured — KHÔNG per-screen spec).
+
+### 4.5. §C5 Archetype-Specific Edge Cases
+
+Chỉ archetype đã chọn (§2.1): Partial Decision Sync Failure + Duplicate/Conflict Detection [MAKER_CHECKER]; Step Dependency Breakage + Auto-save & Session Recovery [WIZARD/FORM-HEAVY]; Stale Data Warning [DASHBOARD]; Simultaneous Edit Conflict [COLLABORATIVE]; Publish Conflict [CONTENT_MGMT]. OTHER → 2-3 edge case unique. KHÔNG mix archetype.
+
+## 5. Đầu ra yêu cầu
+
+- **Ghi trực tiếp:** `ux_conventions.md` §C4 + §C5 + CHANGE LOG rows.
+- Báo cáo: "§C4-C5 {bootstrap | delta | no delta}. {N} events, {Z} error types, {W} edge cases."
+
+**Next:** Read fully and follow `./step-13-responsive-accessibility.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-13-responsive-accessibility.md

@@ -0,0 +1,48 @@
+# STEP 13: RESPONSIVE, ACCESSIBILITY & AUDIT LOG RULES → `ux_conventions.md` §C6-C7
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R3, R5**. Ghi TRỰC TIẾP vào `ux_conventions.md` (ngoại lệ R1).
+
+## 0. Delta-mode check (chạy TRƯỚC)
+
+Delta mode VÀ §C6/§C7 hiện có vẫn đủ (feature không thêm component pattern responsive mới, không đổi a11y yêu cầu, không entity audit mới) → SKIP (log "§C6-C7 no delta").
+
+## 1. Mục tiêu
+
+§C6 Responsive & Accessibility (breakpoint pointer + adaptation + WCAG AA checklist + shell blueprint chung) + §C7 Audit Log UX rules. Project-wide.
+
+## 2. Đầu vào cần đọc
+
+- `master_token.json` — `tokens.breakpoint.*` canonical (thiếu → STOP, chạy `/ntapp-ds-bootstrap`)
+- Journey spec §2 (composition — indicator adaptation) + §3 (shell placement) + §4 (key screens)
+- PRD — NFR responsive, NFR accessibility, FR audit log
+
+## 3. Chỉ thị thực thi
+
+### 3.1. §C6 Breakpoints (pointer)
+
+KHÔNG embed bảng: pointer `master_token.json → tokens.breakpoint.*`; mọi responsive behavior reference token path (`tokens.breakpoint.md`), KHÔNG hardcode px.
+
+### 3.2. §C6 Responsive Behavior
+
+Per critical component (sidebar / section indicator / form layout / dashboard widget grid / data table) × 3 variants (desktop/tablet/mobile) — adapt theo archetype + composition. Touch target ≥44px (token `tokens.spacing.touch-target`).
+
+### 3.3. §C6 Accessibility Checklist (WCAG AA)
+
+Checkbox list ≥8 mục: explicit labels; tab order logic; screen-reader text cho status icon (`aria-label`); contrast ≥4.5:1 text / ≥3:1 large+UI *(cùng ngưỡng `best-practices.md` mà Stage 4b enforce qua `WCAG_CONTRAST_FAIL` + A5 — cite, không redefine)*; focus indicator; error→field linkage (`aria-describedby`); keyboard nav (Tab/Enter/Esc); ARIA live regions (`role="status"`/`role="alert"`); skip link; alt text; không color-only signal.
+
+### 3.4. §C6 Shell Layout Blueprint (chung)
+
+Nếu project chưa có shell doc: 1 khung ASCII duy nhất (header / nav / breadcrumb / content / action bar / status bar) + region rules theo archetype. Journey specs (§3.2) từ nay chỉ REFERENCE khung này. Đã có từ trước → giữ, chỉ patch khi feature đòi region mới.
+
+### 3.5. §C7 Audit Log UX Rules
+
+**Applicable:** archetype có persistent entity state (skip TRANSACTIONAL lookup / DASHBOARD read-only). RULES ONLY — screen SCR-AUDITLOG chi tiết là việc DD Stage 4a:
+- Immutable (không edit/delete control); chronological most-recent-first, group-by-date; actor = name + role (system → "System"); log cả human + system action (auto-save, sync, notification); pagination load-more (không render full history). Cite PRD FR audit (immutability).
+
+## 4. Đầu ra yêu cầu
+
+- **Ghi trực tiếp:** `ux_conventions.md` §C6 + §C7 + CHANGE LOG rows.
+- Báo cáo: "§C6-C7 {bootstrap | delta | no delta}. {X} responsive components, {Y} a11y items, audit rules {set/skipped}."
+
+**Next:** Read fully and follow `./step-14-traceability-assembly.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/steps/step-14-traceability-assembly.md

@@ -0,0 +1,89 @@
+# STEP 14: PRD TRACEABILITY & FINAL ASSEMBLY (§5 + assembly)
+
+> **Pre-requisite:** WBS đã lock (Step 01 Required). Journey screens đã sync WBS (gate sau step-10).
+
+> **Thực hiện bởi:** Agent UX0 (UX Lead — Sally) + Agent UX2 (PM Liaison — John)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — **R1 (Verbatim Injection — journey spec), R2, R4 (PRD→§5 closure), R6**.
+
+## 1. Mục tiêu
+
+1. §5 PRD → UX mapping (closure check — không requirement nào bỏ sót).
+2. Final assembly 5 part files → `ux_design.md` + verify `ux_conventions.md` state.
+3. Dual-write archive cả 2 artifact.
+
+## 2. Phân công
+
+| Nội dung | Agent |
+|:---|:---|
+| §5 PRD→UX Mapping | UX2 |
+| Assembly + Quantitative Audit + Archive | UX0 |
+
+## 3. Đầu vào cần đọc
+
+- PRD: TOÀN BỘ FR, BR, NFR (đọc lại từ đầu — không dựa memory)
+- 5 part files: ux2_executive_summary, ux3_modular, ux3_ia, ux0_journeys, (file này sinh ux2_traceability)
+- `ux_conventions.md` (current state — mapping NFR/BR pattern chung trỏ §C-x)
+- `project_wbs.md` (cross-check screens)
+
+## 4. Chỉ thị thực thi
+
+### 4.1. §5 PRD → UX Mapping (UX2) — Closure Check
+
+Extract đầy đủ FR/BR/NFR từ PRD. Mỗi requirement 1 hàng:
+
+| PRD Requirement | UX Solution | Section |
+|:---|:---|:---|
+| **FR1:** {req} | {solution cụ thể} | §4.1 / §C3 / DD Stage 4a ({SCR-*}) |
+
+**Quy tắc:** KHÔNG hàng trống; solution CỤ THỂ (không "implemented in UI"); Section trỏ chính xác — journey spec §N, conventions §C-x, hoặc "DD Stage 4a ({SCR-*})" cho chi tiết per-screen (hợp lệ từ v4.0 — per-screen là ownership 4a); requirement chưa có solution → 🔴 GAP + báo cáo.
+
+### 4.2. Final Assembly — UX0 (Verbatim Injection R1)
+
+1. Mở scaffold `{planning_artifacts}/ux_design.md` (Step 01).
+2. Inject 1:1 từng part vào section đích:
+
+| Order | Part file | Target |
+|:---|:---|:---|
+| 1 | `ux2_executive_summary_part.md` | §1 |
+| 2 | `ux3_modular_part.md` | §2 |
+| 3 | `ux3_ia_part.md` | §3 |
+| 4 | `ux0_journeys_part.md` | §4 |
+| 5 | `ux2_traceability_part.md` | §5 |
+
+3. Xóa GENERATION comments; cập nhật frontmatter `stepsCompleted` + Change Log.
+4. `ux_conventions.md` KHÔNG assemble (đã ghi trực tiếp) — chỉ verify CHANGE LOG có row cho mọi section vừa đổi.
+
+### 4.3. Quantitative Audit (R6)
+
+| Hạng mục | Đối soát |
+|:---|:---|
+| Journey spec sections | = 5 (§1-§5)? Không còn Screen Spec block / §17 / persona table chi tiết? |
+| §1.3 personas | Chỉ references + khớp actor HLD §3.1.1? |
+| §2.1 archetype | Đúng 1 archetype (không mix)? |
+| §2.3 state taxonomy | Cover lifecycle archetype (nếu ≠ SINGLE)? |
+| §3.1 nav | Brownfield → chỉ delta? Mỗi leaf mới ↔ WBS `SCR-*`? |
+| §4 journeys | Mỗi journey: Mermaid + Journey Screen Table đủ 5 cột? Screen count ≥ min archetype? |
+| §4 Key states | Mỗi screen có Key states từ taxonomy §2.3? (4a inherit field này) |
+| §4 Conventions refs | Mọi §C-x được trỏ đều tồn tại trong `ux_conventions.md`? (gate Conventions Coverage) |
+| L5/L6/L9 self-audit | Mỗi journey có dòng audit? |
+| §5 mapping | Rows = tổng FR+BR+NFR? 0 hàng trống? |
+| `ux_conventions.md` | C1-C7 đủ (bootstrap) / CHANGE LOG khớp delta (delta mode)? Status labels 1-1 Module 0 §7? |
+
+Mục FAIL → quay lại step tương ứng bổ sung. KHÔNG release khi audit fail.
+
+### 4.4. Dual-Write Archive
+
+1. Auto-detect N: `ls {planning_artifacts}/archive/ux_design_v*.md` (empty → 1; max v3 → 4). `mkdir -p archive`.
+2. Journey spec: canonical `ux_design.md` (overwrite) + `archive/ux_design_v{N}.md`.
+3. Conventions: CHỈ khi run này có đổi §C-x → `archive/ux_conventions_v{M}.md` (đếm riêng).
+
+## 5. Đầu ra yêu cầu
+
+- Part: `{intermediate_folder}/ux2_traceability_part.md` (§5)
+- Canonical: `ux_design.md` (5 sections) + `ux_conventions.md` (C1-C7 state hợp lệ)
+- Archive: `archive/ux_design_v{N}.md` (+ `ux_conventions_v{M}.md` nếu delta)
+- Audit table (§4.3) + Gap list (nếu có)
+
+## 6. Bàn giao
+
+Trình bày user: (1) paths 2 artifact + archive; (2) tóm tắt 1 đoạn (archetype, journeys, screens, conventions mode); (3) audit table; (4) gap list; (5) next: per-slice loop — `/ntapp-feature-design` per unit (Stage 4a inherit journey Key states + conventions §C-x), `/ntapp-ui-generation` (Stage 4b), stakeholder review.