@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/commands/generate-design-spec.tmpl

@@ -1,40 +1,40 @@
-# /generate-design-spec — Generate Design Specification (FE / App)
+# /generate-design-spec — Sinh Design Specification (FE / App)
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target file is a Business PRD (`prd.md`) under `{paths.specs_dir}/{domain}/{prd-slug}/`. Resolve from `$ARGUMENTS` or list the directory and ask. Only FE and mobile PRDs are supported — BE PRDs will be rejected at the Platform Check step.*
+*Lưu ý: Với lệnh này, target file là một Business PRD (`{TICKET-ID}-{prd-slug}.md` — file `.md` ở gốc feature folder) dưới `{paths.specs_dir}/{domain}/{prd-slug}/`. Phân giải từ `$ARGUMENTS` hoặc liệt kê thư mục và hỏi. Chỉ hỗ trợ PRD của FE và mobile — PRD của BE sẽ bị từ chối ở bước Platform Check.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
-*Additional context for this command: Read the full target PRD. Extract: **TICKET-ID**, **domain**, **feature name**, **Service** and **Module** from PRD metadata (rows `| **Service** |` and `| **Module** |`), User Flow (Section 4a), and Wireframe screen names (Section 4b).*
+*Context bổ sung cho lệnh này: Đọc toàn bộ PRD target. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, **Service** và **Module** từ metadata PRD (row `| **Service** |` và `| **Module** |`), User Flow (Section 4a), và tên màn hình Wireframe (Section 4b).*
 
-*Service extraction rules (same as /generate-prd):*
-- *If PRD metadata has `| **Service** |` → use as `active_service` and `| **Module** |` as `active_module`.*
-- *If absent AND `services` defined in `project-context.yaml` → ask: "Which service is this Design Spec for?" (list FE/App services only, wait for selection).*
-- *If single-service project → `active_service = "default"`, `active_module = tech_stack.module`.*
+*Quy tắc trích xuất Service (giống /generate-prd):*
+- *Nếu metadata PRD có `| **Service** |` → dùng làm `active_service` và `| **Module** |` làm `active_module`.*
+- *Nếu vắng VÀ `services` được định nghĩa trong `project-context.yaml` → hỏi: "Design Spec này dành cho service nào?" (chỉ liệt kê service FE/App, chờ chọn).*
+- *Nếu dự án single-service → `active_service = "default"`, `active_module = tech_stack.module`.*
 
 ---
 
 ## Platform Check
 
-Using `active_module` and `platform_type` derived from context loading:
+Dùng `active_module` và `platform_type` suy ra từ context loading:
 
-1. If `platform_type = "backend"` → **STOP**. Output:
+1. Nếu `platform_type = "backend"` → **STOP**. Xuất:
    ```
-   ❌ Design Spec is only for FE and mobile platforms.
-   For BE services, API contracts belong in the Business PRD (Use Case → Business Logic section).
+   ❌ Design Spec chỉ dành cho platform FE và mobile.
+   Với service BE, API contract thuộc về Business PRD (Use Case → section Business Logic).
    ```
 
-2. If `platform_type = "web-frontend"` → set `active_platform = "web"`.
+2. Nếu `platform_type = "web-frontend"` → set `active_platform = "web"`.
 
-3. If `platform_type = "mobile"`:
-   - `flutter` or `react-native` → set `active_platform = "app"`
+3. Nếu `platform_type = "mobile"`:
+   - `flutter` hoặc `react-native` → set `active_platform = "app"`
    - `ios-swiftui` → set `active_platform = "app-ios"`
    - `android-compose` → set `active_platform = "app-android"`
 
-4. If `platform_type = "unknown"` → ask: "Which platform is this Design Spec for?"
+4. Nếu `platform_type = "unknown"` → hỏi: "Design Spec này dành cho platform nào?"
    ```
    Options:
      1 — web    (React / Next.js / Vue / Angular)
@@ -42,15 +42,15 @@ Using `active_module` and `platform_type` derived from context loading:
      3 — app-ios     (iOS SwiftUI)
      4 — app-android (Android Compose)
    ```
-   Wait for selection. Map choice to `active_platform` and infer `active_module` if possible.
+   Chờ chọn. Map lựa chọn sang `active_platform` và suy ra `active_module` nếu được.
 
 ---
 
 ## Screen Discovery
 
-From the PRD's Section 4 (User Flow + Wireframe), extract all screen / page / modal names mentioned.
+Từ Section 4 của PRD (User Flow + Wireframe), trích xuất mọi tên screen / page / modal được nhắc tới.
 
-Present the list and ask PO to confirm:
+Trình bày danh sách và hỏi PO xác nhận:
 
 ```
 Screens detected from PRD:
@@ -58,59 +58,59 @@ Screens detected from PRD:
   2. {Screen name 2}
   ...
 
-Are these all the screens for the {active_platform} platform?
-Add any missing, remove any that don't apply, or confirm with Y.
+Đây đã đủ các màn cho platform {active_platform} chưa?
+Thêm màn còn thiếu, bỏ màn không áp dụng, hoặc xác nhận bằng Y.
 ```
 
-Wait for confirmation. Store the confirmed list as `screen_list`.
+Chờ xác nhận. Lưu danh sách đã xác nhận là `screen_list`.
 
 ---
 
-## Figma Frame Links *(mandatory — one readable node-level link per screen)*
+## Figma Frame Links *(bắt buộc — một link node-level đọc được cho mỗi màn)*
 
-A Design Spec is only as good as the design it points to. The AI **cannot read a plain
-file link** (`figma.com/design/{fileKey}/...` with no `node-id`) — it needs a
-**node-level link to each specific frame** so it can fetch that frame's real layout,
-components, and tokens via the Figma MCP. So collect one link **per screen**, not one
-link for the whole feature.
+Một Design Spec chỉ tốt ngang với design mà nó trỏ tới. AI **không đọc được link file
+trần** (`figma.com/design/{fileKey}/...` không có `node-id`) — nó cần một
+**link node-level tới từng frame cụ thể** để fetch layout, component, và token thật của
+frame đó qua Figma MCP. Vậy nên thu thập một link **mỗi màn**, không phải một
+link cho cả feature.
 
-**Ask the PO, listing every screen in `screen_list`:**
+**Hỏi PO, liệt kê mọi màn trong `screen_list`:**
 
 ```
-Paste the Figma frame link for each screen below.
+Dán link Figma frame cho từng màn bên dưới.
 
-  In Figma: select the frame → right-click → "Copy link to selection"
-  (the URL must contain  ?node-id=...  — that is the per-frame link the AI can read)
+  Trong Figma: chọn frame → chuột phải → "Copy link to selection"
+  (URL phải chứa  ?node-id=...  — đó là link per-frame mà AI đọc được)
 
   1. {Screen 1} : ____
   2. {Screen 2} : ____
   ...
 
-If a screen has no design yet, type  none  for that screen.
+Nếu một màn chưa có design, gõ  none  cho màn đó.
 ```
 
-**For each answer:**
+**Với mỗi câu trả lời:**
 
-1. **Validate format** — the URL must match `figma.com/design/{fileKey}/...?node-id={nodeId}`.
-   - Valid → store as `figma_frames[{screen}] = {url}`, parse out `fileKey` + `nodeId`.
-   - A file link with **no `node-id`** → reject it: "This link points to the whole file, not a frame. Re-copy via right-click → Copy link to selection." Re-ask for that screen.
-   - `none` → `figma_frames[{screen}] = "TBD"`, mark that screen ❌ Missing.
+1. **Validate format** — URL phải khớp `figma.com/design/{fileKey}/...?node-id={nodeId}`.
+   - Hợp lệ → lưu thành `figma_frames[{screen}] = {url}`, parse ra `fileKey` + `nodeId`.
+   - Link file **không có `node-id`** → từ chối: "Link này trỏ tới cả file, không phải một frame. Copy lại qua chuột phải → Copy link to selection." Hỏi lại màn đó.
+   - `none` → `figma_frames[{screen}] = "TBD"`, đánh dấu màn đó ❌ Missing.
 
-2. **Fetch the frame via Figma MCP** (only for valid links) — call `get_design_context`
-   (and `get_screenshot` when useful) with the parsed `fileKey` + `nodeId` to read the
-   real layout, component names, and design tokens. Ground every Screen Spec in this
-   fetched data; do **not** invent layout the frame does not show. If a fetch fails
-   (permission / not found) → treat that screen as ❌ Missing and note the fetch error.
+2. **Fetch frame qua Figma MCP** (chỉ với link hợp lệ) — gọi `get_design_context`
+   (và `get_screenshot` khi hữu ích) với `fileKey` + `nodeId` đã parse để đọc
+   layout, tên component, và design token thật. Đặt mọi Screen Spec dựa trên dữ liệu
+   đã fetch này; **đừng** bịa layout mà frame không thể hiện. Nếu fetch thất bại
+   (permission / not found) → coi màn đó là ❌ Missing và ghi chú lỗi fetch.
 
-3. Derive the feature-level `figma_url` = the file link (without `node-id`) shared by the
-   frames, for the Metadata row. If frames span multiple files, list each.
+3. Suy ra `figma_url` mức feature = link file (không có `node-id`) chung của các
+   frame, cho row Metadata. Nếu các frame trải nhiều file, liệt kê từng cái.
 
-**Mandatory gate (does not abort — produces a draft):**
-- If **any** screen is ❌ Missing → the spec is generated as a **draft** with those screens
-  flagged, but `Status` stays `draft` and **sign-off / `/generate-bdd` is blocked** until
-  every screen has a readable, fetched frame link. Record `missing_frames = [screens]`.
-- Add one AI Assumption per missing screen: "No readable Figma frame for {screen} — spec
-  for this screen is text-only and must not be signed off until a `node-id` link is added."
+**Gate bắt buộc (không abort — sinh ra draft):**
+- Nếu **bất kỳ** màn nào ❌ Missing → spec được sinh dưới dạng **draft** với các màn đó
+  được gắn cờ, nhưng `Status` vẫn là `draft` và **sign-off / `/generate-bdd` bị chặn** cho tới khi
+  mọi màn có link frame đọc được, đã fetch. Ghi `missing_frames = [screens]`.
+- Thêm một AI Assumption cho mỗi màn thiếu: "Không có Figma frame đọc được cho {screen} — spec
+  của màn này chỉ là text và không được sign off cho tới khi thêm link `node-id`."
 
 ---
 
@@ -124,58 +124,58 @@ Platform    : {active_platform}
 Module      : {active_module}
 Service     : {active_service}
 Domain      : {domain}
-Screens     : {N} — {comma-separated screen_list}
-Figma       : {linked}/{N} screens have readable frame links{; missing: comma-separated missing_frames}
+Screens     : {N} — {screen_list ngăn cách bởi dấu phẩy}
+Figma       : {linked}/{N} màn có link frame đọc được{; missing: missing_frames ngăn cách bởi dấu phẩy}
 Output path : {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md
 
-{If missing_frames non-empty}:
-⚠️  {count} screen(s) without a readable Figma frame link — these will be generated as
-   text-only drafts and the spec cannot be signed off until their node-id links are added.
+{Nếu missing_frames khác rỗng}:
+⚠️  {count} màn không có link Figma frame đọc được — các màn này sẽ được sinh dưới dạng
+   draft chỉ-text và spec không thể sign off cho tới khi thêm link node-id.
 
 Generate? (Y/N)
 ```
 
-Wait for explicit Y before proceeding.
+Chờ Y rõ ràng trước khi tiếp tục.
 
 ---
 
 ## Generation Rules
 
-Apply these rules consistently when generating all sections:
-
-**Component mapping (C.M — mandatory):**
-- For each component referenced, check `figma-components/{active_module}.md` (loaded in context).
-- ✅ Matched → use the exact `Code Component` and `Import Path` from the catalog.
-- ⚠️ Matched but `[TODO]` → mark the component cell as `[TODO — implementation pending]`.
-- ❌ Not in catalog → mark as `[NEW — confirm with designer before generating code]`.
-- Never invent component names or import paths.
-
-**Platform-adaptive sections:**
-- Section 3 (Interaction Patterns) and Section 4 (Platform Considerations) adapt to `active_platform`:
-  - `web` → include responsive breakpoints, hover/focus states, keyboard navigation, accessibility.
-  - `app` / `app-ios` / `app-android` → include gestures, safe area, minimum touch targets, navigation pattern, deep links, permissions, offline behavior.
-  - Only generate the section relevant to `active_platform`. Omit the other platform's section entirely.
-
-**Figma grounding (mandatory):**
-- For every screen with a fetched frame (`figma_frames[screen]` is a valid link), base the
-  Layout, Component Inventory, and Screen States on the **fetched Figma data** — real
-  component names, real tokens, real frame structure. Do not contradict or invent layout.
-- Use the exact per-screen `figma_frames[screen]` URL in the Screen Inventory, each Screen
-  Spec header, and the Figma Summary — never a synthetic `{figma_url}#screen1` fragment.
-- For ❌ Missing screens: generate a text-only draft from the PRD, prefix the Screen Spec
-  with `> [DRAFT — no Figma frame; do not sign off]`, and leave the Figma cell as ❌ Missing.
-
-**Screen states (mandatory per screen):**
-- Every screen must document at minimum: `default`, `loading`, `error`.
-- Add `empty` when the screen can display zero-data state.
-- Add `success` when a completed action produces a distinct confirmation state.
-- If a state does not apply → mark `N/A` with a short reason.
+Áp dụng các quy tắc này nhất quán khi sinh mọi section:
+
+**Component mapping (C.M — bắt buộc):**
+- Với mỗi component được tham chiếu, kiểm tra `figma-components/{active_module}.md` (đã nạp trong context).
+- ✅ Matched → dùng đúng `Code Component` và `Import Path` từ catalog.
+- ⚠️ Matched nhưng `[TODO]` → đánh dấu ô component là `[TODO — implementation pending]`.
+- ❌ Không có trong catalog → đánh dấu `[NEW — confirm with designer before generating code]`.
+- Không bao giờ bịa tên component hay import path.
+
+**Section thích ứng theo platform:**
+- Section 3 (Interaction Patterns) và Section 4 (Platform Considerations) thích ứng theo `active_platform`:
+  - `web` → gồm responsive breakpoint, trạng thái hover/focus, keyboard navigation, accessibility.
+  - `app` / `app-ios` / `app-android` → gồm gesture, safe area, touch target tối thiểu, navigation pattern, deep link, permission, hành vi offline.
+  - Chỉ sinh section liên quan tới `active_platform`. Bỏ hẳn section của platform kia.
+
+**Figma grounding (bắt buộc):**
+- Với mỗi màn có frame đã fetch (`figma_frames[screen]` là link hợp lệ), dựa Layout,
+  Component Inventory, và Screen States trên **dữ liệu Figma đã fetch** — tên component thật,
+  token thật, cấu trúc frame thật. Đừng mâu thuẫn hay bịa layout.
+- Dùng đúng URL `figma_frames[screen]` từng-màn trong Screen Inventory, header mỗi Screen
+  Spec, và Figma Summary — không bao giờ dùng fragment giả `{figma_url}#screen1`.
+- Với màn ❌ Missing: sinh draft chỉ-text từ PRD, thêm tiền tố vào Screen Spec
+  `> [DRAFT — no Figma frame; do not sign off]`, và để ô Figma là ❌ Missing.
+
+**Screen states (bắt buộc mỗi màn):**
+- Mỗi màn phải mô tả tối thiểu: `default`, `loading`, `error`.
+- Thêm `empty` khi màn có thể hiển thị trạng thái không dữ liệu.
+- Thêm `success` khi một action hoàn tất tạo ra trạng thái xác nhận riêng biệt.
+- Nếu một state không áp dụng → đánh dấu `N/A` kèm lý do ngắn.
 
 ---
 
 ## Generate
 
-Write `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`:
+Ghi `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`:
 
 ````markdown
 # {TICKET-ID} {Feature Name} — Design Spec [{active_platform}]
@@ -193,42 +193,42 @@ Write `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec
 | **Module**         | {active_module}                                               |
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
-| **Business PRD**   | [{TICKET-ID}]({relative-path-to-prd.md})                      |
-| **Figma**          | {figma_url — feature file link} ({linked}/{N} frames linked)  |
-| **Author**         | {PO name or "AI-assisted"}                                    |
+| **Business PRD**   | [{TICKET-ID}](../{TICKET-ID}-{prd-slug}.md)                   |
+| **Figma**          | {figma_url — link file feature} ({linked}/{N} frame đã link)  |
+| **Author**         | {tên PO hoặc "AI-assisted"}                                   |
 | **Created**        | {YYYY-MM-DD}                                                  |
 | **Updated**        | {YYYY-MM-DD}                                                  |
 
 ---
 
-# 1. Screen Inventory
+# 1. Danh mục màn hình (Screen Inventory)
 
-| # | Screen Name | Entry Point | Figma Frame | Notes |
+| # | Tên màn hình | Điểm vào | Figma Frame | Ghi chú |
 |---|-------------|-------------|-------------|-------|
-| 1 | {Screen 1}  | {how user arrives — e.g., tap CTA on Home} | [Frame]({figma_frames[Screen 1]}) | |
-| 2 | {Screen 2}  | {entry point} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | |
+| 1 | {Màn hình 1}  | {người dùng đến từ đâu — vd: tap CTA ở Home} | [Frame]({figma_frames[Screen 1]}) | |
+| 2 | {Màn hình 2}  | {điểm vào} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | |
 
 ---
 
-# 2. Screen Specs
+# 2. Đặc tả màn hình (Screen Specs)
 
 <!--
-  Repeat this block for every screen in the Screen Inventory.
-  Each screen must have: Layout, Component Inventory, Screen States, Actions & Navigation.
+  Lặp lại block này cho mỗi màn trong Screen Inventory.
+  Mỗi màn phải có: Layout, Component Inventory, Screen States, Actions & Navigation.
 -->
 
-## Screen 1: {Screen Name}
+## Màn hình 1: {Tên màn hình}
 
-**Figma**: [{Frame name}]({figma_frames[Screen 1]})   <!-- ❌ Missing → prefix this screen with `> [DRAFT — no Figma frame; do not sign off]` -->
+**Figma**: [{Tên frame}]({figma_frames[Screen 1]})   <!-- ❌ Missing → thêm tiền tố cho màn này `> [DRAFT — no Figma frame; do not sign off]` -->
 
 ### Layout
 
-{Describe the layout: grid columns, max-width container, section order, padding, key spacing values.
- Reference design tokens where applicable (e.g., `spacing.md = 16px`, `color.surface`).}
+{Mô tả layout: số cột grid, container max-width, thứ tự section, padding, giá trị spacing chính.
+ Tham chiếu design token nếu áp dụng được (vd: `spacing.md = 16px`, `color.surface`).}
 
 ### Component Inventory
 
-| Component (Figma)   | Code Component  | Import Path            | States                          | Notes              |
+| Component (Figma)   | Code Component  | Import Path            | States                          | Ghi chú            |
 |---------------------|-----------------|------------------------|---------------------------------|--------------------|
 | {Figma/Button/Primary} | Button       | @/components/ui/Button | default, loading, disabled      |                    |
 | {Figma/Input/Text}  | TextInput       | @/components/ui/Input  | default, focus, error, disabled |                    |
@@ -236,171 +236,171 @@ Write `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec
 
 ### Screen States
 
-| State     | Trigger                             | UI Behavior                                                  |
+| State     | Trigger                             | Hành vi UI                                                  |
 |-----------|-------------------------------------|--------------------------------------------------------------|
-| default   | Screen loaded, data available       | {Describe full rendered appearance}                          |
-| loading   | API call in flight                  | {Skeleton layout / spinner position — reference component}   |
-| error     | API failure or validation error     | {Toast / inline message / error screen — exact copy TBD}     |
-| empty     | API returns empty list / no data    | {Empty state illustration + CTA text — e.g., "No orders yet. Start shopping →"} |
-| success   | Action completed (if applicable)    | {Confirmation message / navigation / state change}           |
+| default   | Màn đã load, có dữ liệu              | {Mô tả toàn bộ giao diện đã render}                          |
+| loading   | API đang gọi                        | {Layout skeleton / vị trí spinner — tham chiếu component}    |
+| error     | API thất bại hoặc lỗi validation    | {Toast / message inline / màn lỗi — copy chính xác TBD}      |
+| empty     | API trả về list rỗng / không dữ liệu | {Illustration empty state + text CTA — vd: "Chưa có order. Bắt đầu mua sắm →"} |
+| success   | Action hoàn tất (nếu áp dụng)       | {Message xác nhận / điều hướng / thay đổi trạng thái}        |
 
 ### Actions & Navigation
 
-| Action          | Trigger                        | Result                                          |
+| Action          | Trigger                        | Kết quả                                         |
 |-----------------|--------------------------------|-------------------------------------------------|
-| {Action name}   | Tap/click {element name}       | Navigate to {Screen N} / Open {Modal name}      |
-| {Action name}   | Swipe left on {list item}      | Show delete confirmation                        |
-| {Back / Cancel} | Back gesture / Cancel button   | Return to {previous screen} without saving      |
+| {Tên action}    | Tap/click {tên phần tử}        | Điều hướng tới {Màn hình N} / Mở {Tên modal}    |
+| {Tên action}    | Swipe trái trên {list item}    | Hiện xác nhận xoá                               |
+| {Back / Cancel} | Cử chỉ back / nút Cancel       | Quay lại {màn trước} mà không lưu               |
 
 ---
 
-<!--  Repeat ## Screen N block for each additional screen  -->
+<!--  Lặp lại block ## Màn hình N cho mỗi màn bổ sung  -->
 
 ---
 
-# 3. Interaction Patterns
+# 3. Pattern tương tác (Interaction Patterns)
 
 <!--
-  Web platform: include sections A + B. Remove section C.
-  App platform: include section C. Remove sections A + B.
+  Platform web: gồm section A + B. Bỏ section C.
+  Platform app: gồm section C. Bỏ section A + B.
 -->
 
-<!-- ═══════════════════════════ WEB ONLY ═══════════════════════════ -->
+<!-- ═══════════════════════════ CHỈ WEB ═══════════════════════════ -->
 
-## A. Responsive Behavior  *(web only)*
+## A. Hành vi Responsive  *(chỉ web)*
 
-| Breakpoint | Width      | Layout Changes                                     |
+| Breakpoint | Width      | Thay đổi layout                                    |
 |------------|------------|----------------------------------------------------|
-| Mobile     | < 768px    | {Single column, bottom navigation bar, CTA full-width} |
-| Tablet     | 768–1279px | {2-column grid, sidebar collapsed, tab navigation} |
-| Desktop    | ≥ 1280px   | {Full layout, sidebar visible, max-width 1440px}   |
+| Mobile     | < 768px    | {1 cột, bottom navigation bar, CTA full-width}     |
+| Tablet     | 768–1279px | {grid 2 cột, sidebar thu gọn, tab navigation}      |
+| Desktop    | ≥ 1280px   | {layout đầy đủ, sidebar hiển thị, max-width 1440px}|
 
-## B. Hover / Focus / Keyboard  *(web only)*
+## B. Hover / Focus / Keyboard  *(chỉ web)*
 
-| Element        | Hover state                   | Focus state                     | Keyboard shortcut |
+| Phần tử        | Trạng thái Hover              | Trạng thái Focus                | Phím tắt          |
 |----------------|-------------------------------|---------------------------------|-------------------|
 | Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space     |
-| Text input     | Border → {color.border.hover} | Border → {color.primary}, label floats | Tab to focus |
-| Dropdown       | Background highlight          | Same as hover + ring            | Arrow keys to navigate |
+| Text input     | Border → {color.border.hover} | Border → {color.primary}, label nổi | Tab to focus |
+| Dropdown       | Highlight nền                 | Giống hover + ring              | Phím mũi tên điều hướng |
 
-<!-- ═══════════════════════════ APP ONLY ═══════════════════════════ -->
+<!-- ═══════════════════════════ CHỈ APP ═══════════════════════════ -->
 
-## C. Gestures & Navigation  *(app only)*
+## C. Cử chỉ & Điều hướng  *(chỉ app)*
 
-| Gesture           | Screen / Element          | Behavior                                              |
+| Cử chỉ            | Màn / Phần tử             | Hành vi                                               |
 |-------------------|---------------------------|-------------------------------------------------------|
-| Back gesture (iOS swipe-right / Android back) | All screens | {Return to previous screen / Show "Discard changes?" dialog} |
-| Pull-to-refresh   | {Screen names}            | Refresh data, spinner at top                          |
-| Swipe left on row | {List item name}          | Reveal {Delete / Archive} action                      |
-| Long press        | {Element name}            | {Context menu / selection mode}                       |
-| Pinch / zoom      | {Image viewer}            | Scale image, double-tap to reset                      |
+| Cử chỉ back (iOS swipe-right / Android back) | Mọi màn | {Quay lại màn trước / Hiện dialog "Discard changes?"} |
+| Pull-to-refresh   | {Tên màn}                 | Refresh dữ liệu, spinner ở trên cùng                  |
+| Swipe trái trên row | {Tên list item}         | Hiện action {Delete / Archive}                        |
+| Long press        | {Tên phần tử}             | {Context menu / chế độ chọn}                          |
+| Pinch / zoom      | {Image viewer}            | Scale ảnh, double-tap để reset                        |
 
-### Navigation Pattern  *(app only)*
+### Navigation Pattern  *(chỉ app)*
 
 ```
-{Draw the navigation stack for this feature, e.g.:
+{Vẽ navigation stack cho feature này, vd:
   BottomTab(Home) → FeatureListPage → FeatureDetailPage → EditPage
   BottomTab(Home) → FeatureListPage ↘ (modal) CreatePage
 }
 ```
 
-Entry: {how the user enters this feature — tab / deeplink / push from another screen}
-Exit: {how the user leaves — back stack / tab switch / deeplink out}
+Entry: {người dùng vào feature này thế nào — tab / deeplink / push từ màn khác}
+Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink out}
 
-### Platform Conventions  *(app only)*
+### Platform Conventions  *(chỉ app)*
 
-| Aspect                   | iOS behavior                            | Android behavior                        |
+| Khía cạnh                | Hành vi iOS                             | Hành vi Android                         |
 |--------------------------|-----------------------------------------|-----------------------------------------|
-| Navigation bar           | {Back button top-left, title centered}  | {Up arrow top-left, title left-aligned} |
-| Sheet / bottom modal     | {UISheetPresentation, grabber visible}  | {BottomSheet, drag handle}              |
-| Alert / confirm dialog   | {UIAlertController, actions right-aligned} | {Material AlertDialog, actions left-aligned} |
+| Navigation bar           | {Nút back trên-trái, title canh giữa}   | {Mũi tên Up trên-trái, title canh trái} |
+| Sheet / bottom modal     | {UISheetPresentation, hiện grabber}     | {BottomSheet, drag handle}              |
+| Alert / confirm dialog   | {UIAlertController, action canh phải}   | {Material AlertDialog, action canh trái}|
 | Loading indicator        | {UIActivityIndicatorView, center}       | {CircularProgressIndicator}             |
 | Toast / snackbar         | {Custom toast, bottom center}           | {Material Snackbar, bottom}             |
 
 ---
 
-# 4. Platform Considerations
+# 4. Cân nhắc theo Platform (Platform Considerations)
 
 <!--
-  Web: include section A. App: include section B. Remove the non-applicable section.
+  Web: gồm section A. App: gồm section B. Bỏ section không áp dụng.
 -->
 
-<!-- ═══════════════════════════ WEB ONLY ═══════════════════════════ -->
+<!-- ═══════════════════════════ CHỈ WEB ═══════════════════════════ -->
 
-## A. Accessibility  *(web only)*
+## A. Accessibility  *(chỉ web)*
 
-- [ ] All interactive elements reachable via Tab key — no keyboard traps
-- [ ] Focus trap inside modal dialogs (Tab cycles within modal only)
-- [ ] Icon-only buttons have `aria-label` describing the action
-- [ ] Dynamic content updates (loading → loaded) announce via `aria-live`
-- [ ] Color contrast meets WCAG AA: text ≥ 4.5:1, large text ≥ 3:1
-- [ ] Form inputs have visible labels (not placeholder-only)
-- [ ] Error messages linked to inputs via `aria-describedby`
+- [ ] Mọi phần tử tương tác tới được bằng phím Tab — không có keyboard trap
+- [ ] Focus trap bên trong modal dialog (Tab chỉ chạy vòng trong modal)
+- [ ] Nút chỉ-icon có `aria-label` mô tả hành động
+- [ ] Cập nhật nội dung động (loading → loaded) thông báo qua `aria-live`
+- [ ] Tương phản màu đạt WCAG AA: text ≥ 4.5:1, text lớn ≥ 3:1
+- [ ] Input form có label hiển thị (không chỉ placeholder)
+- [ ] Message lỗi liên kết với input qua `aria-describedby`
 
-<!-- ═══════════════════════════ APP ONLY ═══════════════════════════ -->
+<!-- ═══════════════════════════ CHỉ APP ═══════════════════════════ -->
 
-## B. Device & OS  *(app only)*
+## B. Thiết bị & OS  *(chỉ app)*
 
-- [ ] Safe area insets applied on all screens — top (status bar) and bottom (home indicator)
-- [ ] Minimum touch target: 44×44pt (iOS) / 48×48dp (Android)
-- [ ] Tested on small screen: 375pt wide (iPhone SE) / 360dp wide (common Android)
-- [ ] Deep link entry: `{scheme}://{host}/{path}` → lands on {screen name} with {param} pre-filled
-- [ ] Permission gates: {list permissions needed — Camera / Location / Notification}
-  - {Permission}: requested on {screen name} with rationale copy: "{copy TBD}"
-- [ ] Offline / no-network behavior:
-  - {Screen name}: show cached data + offline banner
-  - {Action name}: disable button, show tooltip "Requires connection"
-- [ ] Dark mode: all screens tested in dark mode — no hardcoded colors
+- [ ] Áp dụng safe area insets ở mọi màn — trên (status bar) và dưới (home indicator)
+- [ ] Touch target tối thiểu: 44×44pt (iOS) / 48×48dp (Android)
+- [ ] Đã test trên màn nhỏ: rộng 375pt (iPhone SE) / rộng 360dp (Android phổ biến)
+- [ ] Deep link entry: `{scheme}://{host}/{path}` → vào {tên màn} với {param} đã điền sẵn
+- [ ] Permission gate: {liệt kê permission cần — Camera / Location / Notification}
+  - {Permission}: yêu cầu ở {tên màn} với copy lý do: "{copy TBD}"
+- [ ] Hành vi offline / không mạng:
+  - {Tên màn}: hiện dữ liệu cache + banner offline
+  - {Tên action}: disable nút, hiện tooltip "Requires connection"
+- [ ] Dark mode: mọi màn đã test dark mode — không có màu hardcode
 
 ---
 
-# 5. AC-UI — Design Acceptance Criteria
+# 5. AC-UI — Tiêu chí chấp nhận về Design
 
-> Reviewed and signed off by **PO + Designer** together before BDD generation.
-> These complement (not replace) the business-level AC in the [Business PRD]({prd-path}).
+> Được **PO + Designer** cùng review và sign off trước khi sinh BDD.
+> Bổ sung cho (không thay thế) AC mức nghiệp vụ trong [Business PRD]({prd-path}).
 
-| ID     | Acceptance Criterion                                                           | Verified by     |
+| ID     | Tiêu chí chấp nhận                                                             | Verified by     |
 |--------|--------------------------------------------------------------------------------|-----------------|
-| AC-UI1 | All screens match approved Figma frames within design-system tolerances        | Designer        |
-| AC-UI2 | Loading skeleton/spinner appears within 200ms of initiating any API call       | QA              |
-| AC-UI3 | All error messages are visible, descriptive, and include a recovery action     | PO              |
-| AC-UI4 | Empty states include an illustration and a clear call-to-action                | PO + Designer   |
-| AC-UI5 | {Platform-specific — e.g., web: "All screens pass WCAG AA contrast check"}    | QA              |
-| AC-UI6 | {Platform-specific — e.g., app: "Back gesture on all screens returns to correct previous screen"} | QA |
-| AC-UI7 | {Feature-specific UI criterion from Business PRD wireframe section}             | PO              |
+| AC-UI1 | Mọi màn khớp frame Figma đã duyệt trong dung sai design-system                  | Designer        |
+| AC-UI2 | Skeleton/spinner loading xuất hiện trong 200ms kể từ khi gọi API               | QA              |
+| AC-UI3 | Mọi message lỗi đều hiển thị, rõ ràng, và kèm action khôi phục                  | PO              |
+| AC-UI4 | Empty state có illustration và call-to-action rõ ràng                          | PO + Designer   |
+| AC-UI5 | {Riêng platform — vd web: "Mọi màn pass kiểm tra tương phản WCAG AA"}         | QA              |
+| AC-UI6 | {Riêng platform — vd app: "Cử chỉ back ở mọi màn quay về đúng màn trước"}     | QA              |
+| AC-UI7 | {Tiêu chí UI riêng của feature từ section wireframe của Business PRD}           | PO              |
 
 ---
 
 # Appendix
 
-## Figma Summary
+## Tóm tắt Figma
 
-| Screen          | Figma Frame                          | Link / Fetch Status                  |
+| Màn hình        | Figma Frame                          | Trạng thái Link / Fetch              |
 |-----------------|--------------------------------------|--------------------------------------|
-| {Screen 1}      | [Link]({figma_frames[Screen 1]})     | ✅ Linked & fetched                  |
-| {Screen 2}      | —                                    | ❌ Missing — no node-id link provided |
+| {Màn hình 1}    | [Link]({figma_frames[Screen 1]})     | ✅ Đã link & fetch                   |
+| {Màn hình 2}    | —                                    | ❌ Missing — không có link node-id   |
 
-## Design Tokens Referenced
+## Design Token đã tham chiếu
 
-| Token                 | Value         | Used in                         |
+| Token                 | Value         | Dùng ở                          |
 |-----------------------|---------------|---------------------------------|
-| `color.primary`       | {#hex}        | Primary buttons, links, active states |
-| `color.surface`       | {#hex}        | Card backgrounds                |
-| `spacing.md`          | {16px / 4}    | Standard vertical gap           |
-| `typography.heading2` | {font/size}   | Screen titles                   |
+| `color.primary`       | {#hex}        | Primary button, link, active state |
+| `color.surface`       | {#hex}        | Nền card                        |
+| `spacing.md`          | {16px / 4}    | Khoảng cách dọc tiêu chuẩn      |
+| `typography.heading2` | {font/size}   | Title màn hình                  |
 
-## References
+## Tài liệu tham khảo
 
-- [{TICKET-ID}]({prd-path}) — Business PRD (source of AC, UC, BR)
-- {[Other Design Spec](./other-ds.md) — if this feature shares screens}
+- [{TICKET-ID}]({prd-path}) — Business PRD (nguồn của AC, UC, BR)
+- {[Design Spec khác](./other-ds.md) — nếu feature này dùng chung màn}
 
-## AI Assumptions
+## Giả định AI
 
-> Each assumption below was made because PO input was incomplete.
-> PO must review and confirm before sign-off.
+> Mỗi giả định dưới đây được đưa ra vì input PO chưa đầy đủ.
+> PO phải review và confirm trước khi sign-off.
 
-- {Assumption 1 — [AI DRAFT]}
-- {One per ❌ Missing screen: "No readable Figma frame for {screen} — text-only draft; blocks sign-off until a node-id link is added."}
+- {Giả định 1 — [AI DRAFT]}
+- {Một dòng cho mỗi màn ❌ Missing: "Không có Figma frame đọc được cho {screen} — draft chỉ-text; chặn sign-off cho tới khi thêm link node-id."}
 
 ---
 
@@ -412,27 +412,27 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 <!--
   NEXT STEPS:
-  1. Fill any ❌ Missing Figma frame links (node-id links) — re-run to fetch & ground them.
-  2. Share with Designer — verify Figma links, update component inventory.
-  3. PO + Designer sign off: change Status → "approved" (only allowed when 0 screens are ❌ Missing).
-  4. Run /generate-bdd "{prd-file}" — BDD uses AC-UI from this spec for FE scenarios.
+  1. Điền các link Figma frame còn ❌ Missing (link node-id) — chạy lại để fetch & ground chúng.
+  2. Chia sẻ với Designer — xác minh link Figma, cập nhật component inventory.
+  3. PO + Designer sign off: đổi Status → "approved" (chỉ cho phép khi 0 màn ❌ Missing).
+  4. Chạy /generate-bdd "{prd-file}" — BDD dùng AC-UI từ spec này cho FE scenario.
 -->
 ````
 
 ---
 
-## Quality Checklist *(verify before writing)*
+## Quality Checklist *(kiểm tra trước khi ghi)*
 
-- [ ] Every screen in Screen Inventory has a complete Screen Spec in Section 2
-- [ ] Every screen has at minimum: default, loading, error states defined
-- [ ] All Figma components mapped in Component Inventory — unmapped flagged as `[NEW]` or `[TODO]`
-- [ ] Only the platform-relevant section generated in Section 3 (no web section in app docs, and vice versa)
-- [ ] Only the platform-relevant section generated in Section 4
-- [ ] AC-UI items are testable (clear pass/fail, not "looks good")
-- [ ] Business PRD cross-reference link is valid relative path
-- [ ] Every screen has a node-level Figma frame link (`?node-id=`) — and screens with a link were fetched via Figma MCP and used to ground the spec
-- [ ] Each ❌ Missing screen is flagged in-spec (`> [DRAFT — no Figma frame...]`), listed in Figma Summary, and has an AI Assumption
-- [ ] If any screen is ❌ Missing → Status stays `draft` and the Output below blocks `/generate-bdd`
+- [ ] Mọi màn trong Screen Inventory có Screen Spec đầy đủ ở Section 2
+- [ ] Mọi màn có tối thiểu các state: default, loading, error
+- [ ] Mọi component Figma đã map trong Component Inventory — chưa map thì gắn cờ `[NEW]` hoặc `[TODO]`
+- [ ] Chỉ sinh section liên quan platform ở Section 3 (không có section web trong doc app, và ngược lại)
+- [ ] Chỉ sinh section liên quan platform ở Section 4
+- [ ] Các mục AC-UI testable (pass/fail rõ ràng, không phải "looks good")
+- [ ] Link cross-reference Business PRD là relative path hợp lệ
+- [ ] Mọi màn có link Figma frame node-level (`?node-id=`) — và các màn có link đã được fetch qua Figma MCP và dùng để ground spec
+- [ ] Mỗi màn ❌ Missing được gắn cờ trong spec (`> [DRAFT — no Figma frame...]`), liệt kê trong Figma Summary, và có một AI Assumption
+- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` và Output bên dưới chặn `/generate-bdd`
 
 ---
 
@@ -440,25 +440,25 @@ Exit: {how the user leaves — back stack / tab switch / deeplink out}
 
 {{include:steps/report-footer.md}}
 
-{If missing_frames is empty}:
+{Nếu missing_frames rỗng}:
 ```
-/generate-design-spec Complete — {TICKET-ID} [{active_platform}]
+/generate-design-spec Hoàn tất — {TICKET-ID} [{active_platform}]
 ---
-Status : ✅ Complete — all {N} screens linked & fetched from Figma
+Status : ✅ Complete — cả {N} màn đã link & fetch từ Figma
 Output Artifacts:
   created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0)
-Next   : Share with Designer → PO + Designer sign-off (Status: approved)
-         → /generate-bdd {prd-file}  (generates BDD per service; reads AC-UI from Design Spec)
+Next   : Chia sẻ với Designer → PO + Designer sign-off (Status: approved)
+         → /generate-bdd {prd-file}  (sinh BDD theo service; đọc AC-UI từ Design Spec)
 ```
 
-{If missing_frames is non-empty}:
+{Nếu missing_frames khác rỗng}:
 ```
-/generate-design-spec Complete (DRAFT) — {TICKET-ID} [{active_platform}]
+/generate-design-spec Hoàn tất (DRAFT) — {TICKET-ID} [{active_platform}]
 ---
-Status : ⚠️ Warnings — {count} screen(s) without a readable Figma frame: {comma-separated missing_frames}
+Status : ⚠️ Warnings — {count} màn không có link Figma frame đọc được: {missing_frames ngăn cách bởi dấu phẩy}
 Output Artifacts:
   created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
-Next   : 🔒 Sign-off & /generate-bdd are BLOCKED until every screen has a node-id Figma link.
-         1. In Figma: select each missing frame → right-click → Copy link to selection
-         2. Re-run /generate-design-spec {prd-file} → AI fetches & grounds the new frames
+Next   : 🔒 Sign-off & /generate-bdd bị CHẶN cho tới khi mọi màn có link Figma node-id.
+         1. Trong Figma: chọn mỗi frame còn thiếu → chuột phải → Copy link to selection
+         2. Chạy lại /generate-design-spec {prd-file} → AI fetch & ground các frame mới
 ```