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

package/core/steps/spawn-agent.md

@@ -1,27 +1,27 @@
-# Sub-Agent Orchestration Pattern
+# Pattern điều phối Sub-Agent
 
-Used by heavy commands when the target exceeds the complexity threshold.
-The main session becomes a **lightweight orchestrator** — it only coordinates.
-Each unit of work runs in its own sub-agent with a fresh context window.
+Dùng bởi các lệnh nặng khi target vượt ngưỡng phức tạp.
+Session chính trở thành một **orchestrator nhẹ** — chỉ điều phối.
+Mỗi đơn vị công việc chạy trong sub-agent riêng với context window mới.
 
 ---
 
-## Complexity Thresholds
+## Ngưỡng phức tạp
 
-| Signal | Threshold | Action |
+| Tín hiệu | Ngưỡng | Hành động |
 |--------|-----------|--------|
-| UC count in PRD | > 3 UCs | spawn 1 agent per UC |
-| PRD length | > 300 lines | spawn agents regardless of UC count |
+| Số UC trong PRD | > 3 UC | spawn 1 agent cho mỗi UC |
+| Độ dài PRD | > 300 dòng | spawn agent bất kể số UC |
 
-If **either** threshold is exceeded → switch to orchestration mode.
+Nếu vượt **một trong hai** ngưỡng → chuyển sang chế độ orchestration.
 
 ---
 
-## Orchestrator Steps (main session)
+## Các bước của Orchestrator (session chính)
 
-### Step A — Build slim context
+### Bước A — Dựng context gọn
 
-Extract only what sub-agents need — do NOT pass full CLAUDE.md or full business-dictionary:
+Chỉ trích xuất những gì sub-agent cần — KHÔNG truyền nguyên CLAUDE.md hay nguyên business-dictionary:
 
 ```json
 {
@@ -43,49 +43,49 @@ Extract only what sub-agents need — do NOT pass full CLAUDE.md or full busines
     "trace_dir":     "{paths.trace_dir}",
     "tech_docs_dir": "{paths.tech_docs_dir}"
   },
-  "architecture_summary": "<3-5 bullet points: layer order + key rules only>",
+  "architecture_summary": "<3-5 gạch đầu dòng: thứ tự layer + quy tắc chính>",
   "domains": ["{domain1}", "{domain2}"],
   "banned_terms": ["{term1}", "{term2}"]
 }
 ```
 
-### Step B — Extract UC list
+### Bước B — Trích danh sách UC
 
-Scan the target PRD for `#### {TICKET-ID}-UC{N}:` headings.
-Build list: `[ { uc_id, uc_name, line_start, line_end } ]`
+Quét PRD target tìm các heading `#### {TICKET-ID}-UC{N}:`.
+Dựng list: `[ { uc_id, uc_name, line_start, line_end } ]`
 
-### Step C — Announce plan
+### Bước C — Công bố kế hoạch
 
 ```
-High complexity detected — {N} UCs / {L} lines in {prd_file}
-Spawning {N} sub-agents (1 per UC)...
-  Agent 1 → {TICKET-ID}-UC1: {UC name}
-  Agent 2 → {TICKET-ID}-UC2: {UC name}
+Phát hiện độ phức tạp cao — {N} UC / {L} dòng trong {prd_file}
+Đang spawn {N} sub-agent (1 cho mỗi UC)...
+  Agent 1 → {TICKET-ID}-UC1: {tên UC}
+  Agent 2 → {TICKET-ID}-UC2: {tên UC}
   ...
 ```
 
-### Step D — Spawn one sub-agent per UC
+### Bước D — Spawn một sub-agent cho mỗi UC
 
-Build payload and invoke Agent tool for each UC:
+Dựng payload và gọi Agent tool cho từng UC:
 
 ```json
 {
   "_agent_mode": true,
   "command":      "generate-bdd",
   "uc_id":        "{TICKET-ID}-UC{N}",
-  "target_file":  "{absolute path to PRD or feature file}",
+  "target_file":  "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
   "uc_section":   { "line_start": {N}, "line_end": {N} },
-  "context":      { "<slim context from Step A>" }
+  "context":      { "<context gọn từ Bước A>" }
 }
 ```
 
-> **Command scope**: Only `/generate-bdd` initiates orchestration mode. `/generate-code` and `/dev-gen-test` can run as sub-agents (they respect `_agent_mode: true` from Gate Step 0), but they do not spawn further sub-agents — their scope is already a single UC.
+> **Phạm vi lệnh**: Chỉ `/generate-bdd` khởi động chế độ orchestration. `/generate-code` và `/dev-gen-test` có thể chạy như sub-agent (chúng tôn trọng `_agent_mode: true` từ Gate Bước 0), nhưng không spawn thêm sub-agent — phạm vi của chúng vốn đã là một UC duy nhất.
 
-Serialize this JSON and pass as `$ARGUMENTS` when invoking the sub-agent command.
+Serialize JSON này và truyền làm `$ARGUMENTS` khi gọi lệnh sub-agent.
 
-### Step E — Collect and merge results
+### Bước E — Thu thập và merge kết quả
 
-Each sub-agent returns:
+Mỗi sub-agent trả về:
 ```json
 {
   "uc_id":         "{TICKET-ID}-UC{N}",
@@ -95,30 +95,30 @@ Each sub-agent returns:
 }
 ```
 
-Merge into a single report (follow report-footer.md format).
-If any sub-agent errors → list them clearly and suggest re-run for that UC only.
+Merge vào một report duy nhất (theo định dạng report-footer.md).
+Nếu có sub-agent lỗi → liệt kê rõ ràng và đề xuất chạy lại riêng UC đó.
 
 ---
 
-## Sub-Agent Entry Point (called commands)
+## Điểm vào của Sub-Agent (các lệnh được gọi)
 
-When `gate.md Step 0` detects `_agent_mode: true`:
+Khi `gate.md Bước 0` phát hiện `_agent_mode: true`:
 
-1. Parse full payload from `$ARGUMENTS`
-2. **Skip context-loader.md** — use `payload.context` directly
-3. **Scope to `payload.uc_id` only** — do not process other UCs in the file
-4. Read only the PRD section between `payload.uc_section.line_start` and `line_end`
-5. Execute the command's normal logic for this single UC
-6. Return structured result JSON (Step E format above)
+1. Parse toàn bộ payload từ `$ARGUMENTS`
+2. **Bỏ qua context-loader.md** — dùng trực tiếp `payload.context`
+3. **Chỉ giới hạn ở `payload.uc_id`** — không xử lý các UC khác trong file
+4. Chỉ đọc section PRD giữa `payload.uc_section.line_start` và `line_end`
+5. Thực thi logic thường của lệnh cho riêng UC này
+6. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
 
 ---
 
-## Context Window Savings
+## Tiết kiệm Context Window
 
-| Mode | What loads per session |
+| Chế độ | Nạp gì mỗi session |
 |------|------------------------|
-| Single session (≤ 3 UC) | Full context + full PRD + all UCs |
-| Orchestrator | Slim context + UC headings only |
-| Each sub-agent | Slim context + **1 UC section only** |
+| Single session (≤ 3 UC) | Full context + full PRD + tất cả UC |
+| Orchestrator | Context gọn + chỉ các heading UC |
+| Mỗi sub-agent | Context gọn + **chỉ 1 section UC** |
 
-The larger the PRD, the bigger the saving per sub-agent.
+PRD càng lớn, mức tiết kiệm trên mỗi sub-agent càng nhiều.

package/core/steps/trace-mirror.md

@@ -1,26 +1,26 @@
-# Refresh Living Docs panel mirror *(local, umbrella mode)*
+# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
 
-*Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
-the repo's own `.trace/` IS the panel location, so nothing to mirror.*
+*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
+`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
 
-After updating the authoritative TSV(s) at `{paths.trace_dir}`:
+Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 
-**When `setup.spec_source` is set (consolidated trace — the common case):**
-`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
-This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
-commit/push the spec submodule for the trace update (same as `feedback/`).
-1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
-2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
-   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
-   No per-service namespacing — there is one trace set; the owning service is carried in each
-   row's `@trace.service`.
+**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
+`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
+Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
+commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
+1. Phân giải `panel_mirror = ./.trace` tại **gốc workspace hiện tại**.
+2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+   `{UC-ID}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}.tsv` (tạo thư mục; ghi đè).
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang trong
+   `@trace.service` của từng row.
 
-**Legacy (no `spec_source` — per-service trace):**
-Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
-(namespaced by `active_service`).
+**Legacy (không có `spec_source` — trace theo service):**
+Copy mỗi `{UC-ID}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespace theo `active_service`).
 
-This keeps the open workspace's Living Docs panel current **between syncs** — it is a
-**local convenience mirror only**. The merged `trace-report.json` (canonical, in
-`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
-commands, do this once in the orchestrator after all sub-agents return — not inside each
-sub-agent.
+Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
+một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
+`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
+được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
+bên trong từng sub-agent.

package/core/templates/architecture.template.md

@@ -1,56 +1,56 @@
 # §1. Project Overview
 
 Project    : {{PROJECT_NAME}}
-Language   : {{LANGUAGE}}          # e.g., Java 17 / TypeScript / C# / Go
-Framework  : {{FRAMEWORK}}         # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
-Build      : {{BUILD_COMMAND}}     # e.g., mvn clean install -DskipTests / dotnet build / ng build
-Test       : {{TEST_COMMAND}}      # e.g., mvn test / dotnet test / ng test
+Language   : {{LANGUAGE}}          # vd: Java 17 / TypeScript / C# / Go
+Framework  : {{FRAMEWORK}}         # vd: Spring Boot 3.2 / Angular 17 / .NET 8
+Build      : {{BUILD_COMMAND}}     # vd: mvn clean install -DskipTests / dotnet build / ng build
+Test       : {{TEST_COMMAND}}      # vd: mvn test / dotnet test / ng test
 Domains    : {{COMMA_SEPARATED_DOMAINS}}
 
 # §2. Architecture
 
-style: "{{ARCH_STYLE}}"  # e.g., Layered / Clean / Hexagonal / Component-based
+style: "{{ARCH_STYLE}}"  # vd: Layered / Clean / Hexagonal / Component-based
 
 layers: "{{LAYER_STACK}}"
-# Examples:
+# Ví dụ:
 #   Java/Spring:  Controller → Facade → Service → Repository
 #   .NET Clean:   Presentation → Application → Domain → Infrastructure
 #   Angular:      Component → Service → HTTP Client → Backend API
 #   Go:           Handler → UseCase → Repository → Domain
 
 rules:
-  - "{{ARCH_RULE_1}}"  # e.g., Controllers must not contain business logic
-  - "{{ARCH_RULE_2}}"  # e.g., Services own transaction boundaries
-  - "{{ARCH_RULE_3}}"  # e.g., Repositories must not call services
+  - "{{ARCH_RULE_1}}"  # vd: Controller không được chứa business logic
+  - "{{ARCH_RULE_2}}"  # vd: Service sở hữu ranh giới transaction
+  - "{{ARCH_RULE_3}}"  # vd: Repository không được gọi service
 
-# Layer dependency direction (inner layers must not depend on outer):
+# Chiều phụ thuộc giữa các layer (layer trong không được phụ thuộc layer ngoài):
 # {{OUTER_LAYER}} → {{MIDDLE_LAYER}} → {{INNER_LAYER}}
 
 # §3. Coding Standards
 
 naming:
-  classes: "{{CLASS_NAMING}}"        # e.g., PascalCase / PascalCase+Suffix
-  methods: "{{METHOD_NAMING}}"       # e.g., camelCase / PascalCase
-  packages: "{{PACKAGE_NAMING}}"     # e.g., lowercase / lowercase.snake_case
-  files: "{{FILE_NAMING}}"           # e.g., PascalCase.java / kebab-case.ts
+  classes: "{{CLASS_NAMING}}"        # vd: PascalCase / PascalCase+Suffix
+  methods: "{{METHOD_NAMING}}"       # vd: camelCase / PascalCase
+  packages: "{{PACKAGE_NAMING}}"     # vd: lowercase / lowercase.snake_case
+  files: "{{FILE_NAMING}}"           # vd: PascalCase.java / kebab-case.ts
 
 patterns:
-  response_wrapper: "{{RESPONSE_WRAPPER}}"  # e.g., ApiResponse<T> / Result<T> / IActionResult
-  mapping: "{{MAPPING_LIBRARY}}"            # e.g., MapStruct / AutoMapper / manual
-  exception_base: "{{BASE_EXCEPTION}}"      # e.g., ResourceNotFoundException / DomainException
+  response_wrapper: "{{RESPONSE_WRAPPER}}"  # vd: ApiResponse<T> / Result<T> / IActionResult
+  mapping: "{{MAPPING_LIBRARY}}"            # vd: MapStruct / AutoMapper / manual
+  exception_base: "{{BASE_EXCEPTION}}"      # vd: ResourceNotFoundException / DomainException
 
 forbidden:
-  - "Magic numbers — use named constants"
-  - "Debug print statements in production code"
+  - "Magic number — dùng hằng số có tên"
+  - "Lệnh debug print trong code production"
   - "{{PROJECT_SPECIFIC_FORBIDDEN_PATTERN}}"
 
 # §4. API Conventions
 
-versioning: "{{API_VERSIONING}}"     # e.g., /v1/ prefix / header-based / query param
-auth: "{{AUTH_MECHANISM}}"           # e.g., JWT Bearer / OAuth2 / API Key
+versioning: "{{API_VERSIONING}}"     # vd: tiền tố /v1/ / theo header / query param
+auth: "{{AUTH_MECHANISM}}"           # vd: JWT Bearer / OAuth2 / API Key
 
 http_status:
-  get_list:    200   # paginated or full list
+  get_list:    200   # danh sách phân trang hoặc đầy đủ
   get_single:  200
   create:      201
   update:      200
@@ -70,32 +70,32 @@ error_response_format: |
 
 # §5. Error Handling
 
-not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # e.g., ResourceNotFoundException
-validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # e.g., ValidationException
-domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # e.g., DomainException / BusinessRuleViolationException
+not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # vd: ResourceNotFoundException
+validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # vd: ValidationException
+domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # vd: DomainException / BusinessRuleViolationException
 
-global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # e.g., @ControllerAdvice / ExceptionHandlerMiddleware
+global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # vd: @ControllerAdvice / ExceptionHandlerMiddleware
 
 rules:
-  - "Never swallow exceptions silently"
-  - "Log at error level with full stack trace for 5xx"
+  - "Không bao giờ nuốt exception âm thầm"
+  - "Log ở mức error kèm full stack trace cho lỗi 5xx"
   - "{{PROJECT_SPECIFIC_ERROR_RULE}}"
 
 # §6. Testing Standards
 
-unit_test_framework: "{{UNIT_TEST_FW}}"        # e.g., JUnit 5 + Mockito / xUnit + Moq / Jest
-integration_test_framework: "{{IT_TEST_FW}}"   # e.g., Spring Boot Test / WebApplicationFactory
+unit_test_framework: "{{UNIT_TEST_FW}}"        # vd: JUnit 5 + Mockito / xUnit + Moq / Jest
+integration_test_framework: "{{IT_TEST_FW}}"   # vd: Spring Boot Test / WebApplicationFactory
 
 coverage_targets:
-  unit: "{{UNIT_COVERAGE_PCT}}%"          # e.g., 80%
-  integration: "{{IT_COVERAGE_PCT}}%"     # e.g., key flows covered
+  unit: "{{UNIT_COVERAGE_PCT}}%"          # vd: 80%
+  integration: "{{IT_COVERAGE_PCT}}%"     # vd: phủ các flow chính
 
-naming_pattern: "{{TEST_METHOD_NAMING}}"  # e.g., methodName_whenCondition_shouldExpectation
+naming_pattern: "{{TEST_METHOD_NAMING}}"  # vd: methodName_whenCondition_shouldExpectation
 
 rules:
-  - "Unit tests mock direct dependencies only"
-  - "Integration tests cover happy path + main error paths"
-  - "Every scenario in .feature must have a corresponding test"
+  - "Unit test chỉ mock các dependency trực tiếp"
+  - "Integration test phủ happy path + các luồng lỗi chính"
+  - "Mọi scenario trong .feature phải có test tương ứng"
 
 # §7. Git Conventions
 
@@ -110,4 +110,4 @@ commit_docs:    "docs: {description}"
 
 pr_title: "{{TICKET_PREFIX}}-{N}: {feature name}"
 pr_requires_review: true
-pr_branch_protection: "{{BASE_BRANCH}}"  # e.g., main / develop
+pr_branch_protection: "{{BASE_BRANCH}}"  # vd: main / develop

package/core/templates/design-spec.template.md

@@ -41,172 +41,172 @@
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}](./{TICKET-ID}-slug.md)                          |
-| **Figma**          | {feature file link} ({linked}/{N} frames linked)             |
-| **Author**         | {PO name or "AI-assisted"}                                    |
+| **Figma**          | {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 (node-level link) | Notes |
+| # | Tên màn hình | Điểm vào | Figma Frame (link node-level) | Ghi chú |
 |---|-------------|-------------|-------------------------------|-------|
-| 1 | {Screen 1}  | {how user arrives} | [Frame]({node-level url}) | |
-| 2 | {Screen 2}  | {entry point} | ❌ Missing — add node-id link | |
+| 1 | {Màn hình 1}  | {người dùng đến từ đâu} | [Frame]({node-level url}) | |
+| 2 | {Màn hình 2}  | {điểm vào} | ❌ Missing — thêm link node-id | |
 
 ---
 
-# 2. Screen Specs
+# 2. Đặc tả màn hình (Screen Specs)
 
-## Screen 1: {Screen Name}
+## Màn hình 1: {Tên màn hình}
 
-**Figma**: [{Frame name}]({figma_frame_url})
+**Figma**: [{Tên frame}]({figma_frame_url})
 
 ### Layout
 
-{Grid / max-width / padding / spacing — reference design tokens where applicable}
+{Grid / max-width / padding / spacing — tham chiếu design token nếu áp dụng được}
 
 ### 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 |         |
 
 ### 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 / spinner position and style}                  |
-| error     | API failure / validation error   | {Toast / inline error / error screen + recovery CTA}     |
-| empty     | No data returned                 | {Illustration + CTA — e.g., "No items yet. Add one →"}   |
-| success   | Action completed (if applicable) | {Confirmation toast / navigation / visual change}        |
+| default   | Màn đã load, có dữ liệu           | {Mô tả toàn bộ giao diện đã render}                      |
+| loading   | API đang gọi                      | {Vị trí và kiểu skeleton / spinner}                      |
+| error     | API thất bại / lỗi validation     | {Toast / lỗi inline / màn lỗi + CTA khôi phục}           |
+| empty     | Không có dữ liệu trả về            | {Illustration + CTA — vd: "Chưa có mục nào. Thêm mới →"} |
+| success   | Action hoàn tất (nếu có)          | {Toast xác nhận / điều hướng / thay đổi giao diện}       |
 
 ### Actions & Navigation
 
-| Action          | Trigger                   | Result                                            |
+| Action          | Trigger                   | Kết quả                                           |
 |-----------------|---------------------------|---------------------------------------------------|
-| {Action name}   | Tap/click {element}       | Navigate to {Screen N} / Open {Modal name}        |
-| {Back/Cancel}   | Back gesture / button     | Return to {previous screen} without saving        |
+| {Tên action}    | Tap/click {phần tử}       | Điều hướng tới {Màn hình N} / Mở {Tên modal}      |
+| {Back/Cancel}   | Cử chỉ back / nút          | Quay lại {màn trước} mà không lưu                  |
 
 ---
 
-<!--  Repeat ## Screen N for each additional screen  -->
+<!--  Lặp lại ## Màn hình N cho mỗi màn bổ sung  -->
 
 ---
 
-# 3. Interaction Patterns
+# 3. Pattern tương tác (Interaction Patterns)
 
-<!-- === WEB ONLY — delete this section for app === -->
+<!-- === CHỈ WEB — xóa section này cho app === -->
 
-## A. Responsive Behavior  *(web)*
+## A. Hành vi Responsive  *(web)*
 
-| Breakpoint | Width      | Layout Changes                              |
+| Breakpoint | Width      | Thay đổi layout                             |
 |------------|------------|---------------------------------------------|
-| Mobile     | < 768px    | {Single column, bottom nav, full-width CTA} |
-| Tablet     | 768–1279px | {2-col grid, sidebar collapsed}             |
-| Desktop    | ≥ 1280px   | {Full layout, max-width 1440px}             |
+| Mobile     | < 768px    | {1 cột, bottom nav, CTA full-width}         |
+| Tablet     | 768–1279px | {grid 2 cột, sidebar thu gọn}               |
+| Desktop    | ≥ 1280px   | {layout đầy đủ, max-width 1440px}           |
 
 ## B. Hover / Focus / Keyboard  *(web)*
 
-| Element        | Hover                         | Focus                           | Keyboard      |
+| Phần tử        | Hover                         | Focus                           | Keyboard      |
 |----------------|-------------------------------|---------------------------------|---------------|
 | Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space |
 | Text input     | Border → {color.border.hover} | Border → {color.primary}        | Tab to focus  |
 
-<!-- === APP ONLY — delete sections A+B for app === -->
+<!-- === CHỈ APP — xóa section A+B cho app === -->
 
-## C. Gestures & Navigation  *(app)*
+## C. Cử chỉ & Điều hướng  *(app)*
 
-| Gesture              | Screen / Element    | Behavior                                    |
+| Cử chỉ               | Màn / Phần tử       | Hành vi                                     |
 |----------------------|---------------------|---------------------------------------------|
-| Back gesture         | All screens         | {Return / show "Discard changes?" dialog}   |
-| Pull-to-refresh      | {Screen names}      | Refresh data, spinner at top                |
-| Swipe left on row    | {List item}         | Reveal {Delete / Archive} action            |
+| Cử chỉ back          | Mọi màn             | {Quay lại / 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  | {List item}         | Hiện action {Delete / Archive}              |
 
 ### Navigation Stack  *(app)*
 
 ```
-{e.g., BottomTab(Home) → ListPage → DetailPage → EditPage}
+{vd: BottomTab(Home) → ListPage → DetailPage → EditPage}
 ```
 
 ### Platform Conventions  *(app)*
 
-| Aspect           | iOS                                       | Android                             |
+| Khía cạnh        | iOS                                       | Android                             |
 |------------------|-------------------------------------------|-------------------------------------|
-| Navigation bar   | Back button top-left, title centered      | Up arrow, title left-aligned        |
-| Bottom sheet     | UISheetPresentation, grabber visible      | BottomSheet, drag handle            |
-| Dialog           | Actions right-aligned                     | Actions left-aligned                |
+| Navigation bar   | Nút back trên-trái, title canh giữa        | Mũi tên Up, title canh trái         |
+| Bottom sheet     | UISheetPresentation, hiện grabber          | BottomSheet, drag handle            |
+| Dialog           | Action canh phải                          | Action canh trái                    |
 
 ---
 
-# 4. Platform Considerations
+# 4. Cân nhắc theo Platform (Platform Considerations)
 
-<!-- === WEB ONLY === -->
+<!-- === CHỈ WEB === -->
 
 ## A. Accessibility  *(web)*
 
-- [ ] All interactive elements reachable by Tab key — no keyboard traps
-- [ ] Focus trap inside modals
-- [ ] Icon-only buttons have `aria-label`
-- [ ] Dynamic content announces via `aria-live`
-- [ ] WCAG AA contrast: text ≥ 4.5:1, large text ≥ 3:1
-- [ ] Form inputs have visible labels (not placeholder-only)
+- [ ] Mọi phần tử tương tác đều tới được bằng phím Tab — không có keyboard trap
+- [ ] Focus trap bên trong modal
+- [ ] Nút chỉ có icon phải có `aria-label`
+- [ ] Nội dung động thông báo qua `aria-live`
+- [ ] Tương phản WCAG AA: text ≥ 4.5:1, text lớn ≥ 3:1
+- [ ] Input form có label hiển thị (không chỉ dùng placeholder)
 
-<!-- === APP ONLY === -->
+<!-- === CHỈ APP === -->
 
-## B. Device & OS  *(app)*
+## B. Thiết bị & OS  *(app)*
 
-- [ ] Safe area insets applied (top + bottom) on all screens
-- [ ] Minimum touch target: 44×44pt (iOS) / 48×48dp (Android)
-- [ ] Tested on 375pt (iPhone SE) and 360dp (small Android)
-- [ ] Deep link: `{scheme}://{host}/{path}` → {screen name}
-- [ ] Permissions: {Camera / Location / Notification} — rationale copy TBD
-- [ ] Offline: {screen name} shows cached data + banner; {action} disabled with tooltip
-- [ ] Dark mode tested — no hardcoded colors
+- [ ] Áp dụng safe area insets (trên + dưới) ở mọi màn
+- [ ] Touch target tối thiểu: 44×44pt (iOS) / 48×48dp (Android)
+- [ ] Đã test trên 375pt (iPhone SE) và 360dp (Android nhỏ)
+- [ ] Deep link: `{scheme}://{host}/{path}` → {tên màn}
+- [ ] Permission: {Camera / Location / Notification} — nội dung lý do TBD
+- [ ] Offline: {tên màn} hiện dữ liệu cache + banner; {action} bị disable kèm tooltip
+- [ ] Đã 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** before BDD generation.
-> Complements business-level AC in [Business PRD](./{TICKET-ID}-slug.md).
+> Được **PO + Designer** review và sign off trước khi sinh BDD.
+> Bổ sung cho AC mức nghiệp vụ trong [Business PRD](./{TICKET-ID}-slug.md).
 
-| 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 state appears within 200ms of any API call initiation            | QA              |
-| AC-UI3 | All error messages are visible, descriptive, and include a recovery CTA  | PO              |
-| AC-UI4 | Empty states include illustration and call-to-action                     | PO + Designer   |
-| AC-UI5 | {Platform-specific criterion}                                            | QA              |
+| AC-UI1 | Mọi màn khớp với frame Figma đã duyệt trong dung sai design-system        | Designer        |
+| AC-UI2 | Trạng thái loading xuất hiện trong vòng 200ms kể từ khi gọi API           | QA              |
+| AC-UI3 | Mọi thông báo lỗi đều hiển thị, rõ ràng, và kèm CTA khôi phục             | PO              |
+| AC-UI4 | Empty state có illustration và call-to-action                            | PO + Designer   |
+| AC-UI5 | {Tiêu chí riêng theo platform}                                           | QA              |
 
 ---
 
 # Appendix
 
-## Figma Summary
+## Tóm tắt Figma
 
-| Screen     | Figma Frame (node-level) | Link / Fetch Status            |
+| Màn hình   | Figma Frame (node-level) | Trạng thái Link / Fetch         |
 |------------|--------------------------|--------------------------------|
-| {Screen 1} | [Link]({node-level url}) | ✅ Linked & fetched            |
-| {Screen 2} | —                        | ❌ Missing — no node-id link    |
+| {Màn hình 1} | [Link]({node-level url}) | ✅ Đã 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}   | Buttons, links             |
-| `spacing.md`      | {16px}   | Standard vertical gap      |
+| `color.primary`   | {#hex}   | Button, link               |
+| `spacing.md`      | {16px}   | Khoảng cách dọc tiêu chuẩn |
 
-## References
+## Tài liệu tham khảo
 
 - [{TICKET-ID}](./{TICKET-ID}-slug.md) — Business PRD
 
-## AI Assumptions
+## Giả định AI
 
-- {Assumption — [AI DRAFT]}
+- {Giả định — [AI DRAFT]}
 
 ---