update skill ba

.claude/skills/ba-design/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: ba-design
+description: Vai trò Design trong quy trình BA — chạy song song GĐ3 khi PRODUCT = screen, sau khi ba-3 đã có SRS + WF + UICONV. Sinh design system cấp project (DS - token chuẩn W3C DTCG, tokens.css, component sheet đủ trạng thái hover/focus/disabled/error), mockup hi-fi tự chứa cho từng US (HIFI - mọi màn hình × trạng thái × breakpoint, có chế độ prototype bấm được), gói nhập Figma (FIGMA - SVG mỗi màn hình, token DTCG, PNG chụp bằng Chrome headless, hướng dẫn nhập; không sinh được .fig) và đặc tả thiết kế/redline bàn giao Dev FE (DSPEC). Mọi thứ truy vết về SRS/WF/UICONV và được kiểm bằng máy - C-id hai chiều, text nguyên văn theo SRS §4.2, chỉ dùng token, tương phản WCAG AA. Kích hoạt khi người dùng nói "thiết kế giao diện", "mockup", "hi-fi", "design system", "token", "chọn màu/font/khoảng cách", "prototype bấm được", "xuất Figma", "file Figma", "redline", "bàn giao dev FE", "component sheet", "kiểm tra tương phản", "dự án không có Designer". Output vào ba-output/<PROJECT>/00-index/ds/ và 03-specification/design/; ký cùng Gate G3 bởi Designer, hoặc PO + DEC khi dự án không có Designer.
+---
+
+# ⊕ DESIGN — Vai trò Design trong bộ BA
+
+Mục tiêu: **biến SRS + WF + UICONV thành thiết kế giao diện hoàn chỉnh mà Dev FE dựng được không phải
+đoán, Designer sửa được trong Figma, và máy kiểm được là không lệch đặc tả.**
+
+Skill này **đóng vai Designer khi dự án không có Designer**, và **làm phần chuẩn bị cho Designer**
+khi có. Nó không thay đổi ranh giới của `ba-3`: `WF` vẫn là low-fi và dừng ở bố cục; phần "Designer
+còn phải làm" ở `WF` §6 chính là việc của skill này.
+
+Output — chỉ khi `PRODUCT = screen`; loại khác trả "N/A theo PRODUCT", không ghi file:
+
+| Mã | Ở đâu | Tần suất |
+|---|---|---|
+| `DS` | `00-index/DS_<PROJECT>_v1.0.md` + `00-index/ds/{tokens.json, tokens.css, components.html}` | Một lần / project, bồi đắp dần |
+| `HIFI` | `03-specification/design/HIFI_<US>_v1.0.html` | Mỗi US, sau `wf` |
+| `FIGMA` | `03-specification/design/FIGMA_<US>_v1.0/` (`*.svg`, `tokens.dtcg.json`, `png/`, `README-import.md`) | Mỗi US |
+| `DSPEC` | `03-specification/design/DSPEC_<US>_v1.0.md` | Mỗi US |
+
+## Bốn nguyên tắc bất di bất dịch
+
+1. **Không bịa yêu cầu** — ở đây là *không bịa visual*: thiếu brand guideline ⇒ dùng token trung tính
+   của template, ghi độ tin cậy 🔴 ở `DS` §0 và `OQ`, không viết như thể đã có nhận diện.
+2. **Không quyết định thay PO** — và **không quyết hành vi thay SRS**: HIFI *chép* thành phần, trạng
+   thái, text từ SRS. Muốn thêm nút, đổi nhãn ⇒ ghi lệch ở `DSPEC` §6 / `WF` §5, PO quyết.
+3. **Mọi phát biểu truy vết được** — mỗi `data-c`/`data-f` về SRS §2.3, mỗi `data-key` về SRS §4.2,
+   mỗi màu về một token, mỗi token về brand/prototype/`OQ`.
+4. **Không ghi đè tài liệu đã qua gate** — `DS` đã Baselined chỉ sửa qua `CR`; đổi token là đổi mọi HIFI.
+
+🔴 **Nguyên tắc riêng: skill này không tự duyệt.** Mọi artifact sinh ra là `🟡 Draft` chờ **Designer**
+ký; dự án không có Designer ⇒ PO ký thay và tham chiếu `DEC-nn` (theo `../ba-lifecycle/references/workflow.md` §3).
+
+Nạp bắt buộc trước khi làm: `../ba-lifecycle/references/{domain-profiles,workflow,artifact-map,writing-rules}.md`
+· `templates/` của skill này · `scripts/design-check.mjs` (đọc phần đầu để biết phép kiểm nào sẽ chạy).
+
+## Bước 0 — Chốt input rồi dừng lại
+
+**Chưa được ghi file.** Làm bảy việc rồi **dừng chờ trả lời**:
+
+1. **Profile** — `PRODUCT` phải là `screen`. Không phải ⇒ nói "N/A theo PRODUCT" và dừng.
+2. **Input từ ba-3 đã có chưa** — bảng `File | Version | Status` cho `UICONV_<PROJECT>`, `SRS_<US>`,
+   `WF_<US>` (md + html). Thiếu `WF` ⇒ HIFI không có nguồn bố cục ⇒ đề nghị chạy `/ba-3-specification`
+   activity `wf` trước; người dùng vẫn muốn ⇒ làm, ghi `OQ` và độ tin cậy 🔴.
+3. **`DS` đã có chưa** — có ⇒ chỉ đọc và bồi đắp §3 (badge ↔ trạng thái BR), §8 (ngoại lệ); chưa có ⇒
+   lần chạy này phải sinh `DS` trước (activity `ds`).
+4. **Nguồn visual**, tìm theo thứ tự và trình bảng `Nguồn | Định dạng | Phủ gì | Độ tin cậy`:
+   tham số `--brand` · thư mục `design/`, `brand/`, `prototype/` · link Figma người dùng đưa · `UICONV` §0
+   (design system đã chọn) · `SAD` §7 · `DEC-nn` của Tech Lead về design system. **Không có ⇒ token trung
+   tính của template, độ tin cậy 🔴, nói rõ điều đó.**
+5. **Dự án có Designer không** — có ⇒ Designer ký `DS`, `HIFI`, `DSPEC`; không ⇒ tìm `DEC-nn` "không có
+   Designer" (ví dụ `DEC-01` của e-commerce); chưa có ⇒ đề xuất ghi, PO ký thay.
+6. **Phạm vi lần chạy** — đích danh `US` (≤ 3) và activity: `ds` · `hifi` · `proto` · `figma` · `dspec`.
+7. **Công cụ** — `node` để chạy `scripts/design-check.mjs`; Chrome/Edge để chạy `scripts/render-figma.sh`.
+   Không có Chrome ⇒ `FIGMA/png/` bỏ trống và ghi hướng dẫn chụp tay trong `README-import.md`.
+
+Rồi **hỏi xác nhận** bảy điểm trên. Bỏ qua khi lệnh có `go`.
+
+## Thực hiện — 5 activity
+
+Thứ tự bắt buộc trong một US: `ds` (nếu chưa có) → `hifi` → `proto` (tuỳ chọn) → `figma` → `dspec`.
+`figma` và `dspec` đọc HIFI, nên HIFI đổi ⇒ chạy lại cả hai.
+
+### Activity `ds` — Design system cấp project
+
+Dùng `templates/design-system.md` → `00-index/DS_<PROJECT>_v1.0.md`, và ba tệp kèm trong `00-index/ds/`:
+
+1. **`tokens.json`** — chép `templates/tokens.json`, điền theo nguồn ở Bước 0. Giữ đúng cấu trúc và tên
+   token (HIFI/CSS phụ thuộc tên). Ba thứ **phải khớp `UICONV`**: `breakpoint.*` với §1, `size.content-max`
+   với §1, `size.control.touch ≥ 44px`. Điền `$extensions.ba.contrastPairs` cho **mọi** cặp chữ/nền dùng
+   trong components.html. Thiếu brand ⇒ giữ giá trị placeholder, ghi `"source": "… — OQ-nnn"`.
+2. **`tokens.css`** — sinh từ json theo quy tắc `--ds-<đường dẫn nối bằng '-'>`. Có Bash ⇒
+   `node scripts/design-check.mjs --tokens tokens.json --emit-css > tokens.css`; không có ⇒ viết tay
+   đúng quy tắc, phép kiểm T1 sẽ bắt sai lệch.
+3. **`components.html`** — chép `templates/components.html`, **thay khối `:root`** bằng tokens.css, **giữ
+   nguyên khối `ds-components … BEGIN/END`**. Chỉ sửa CSS component khi có dòng `DS` §8 và sửa đồng thời
+   ở mọi HIFI. Bổ sung component nếu `UICONV` §11 có kiểu trình bày chưa có lớp `.ds-*`.
+4. **`DS_<PROJECT>.md`** — §3 ánh xạ ba chiều *(UICONV §11 · lớp DS · component design system tham chiếu)*
+   phải phủ **mọi** kiểu trình bày xuất hiện trong các `WF` hiện có; §4 trạng thái đủ default/hover/focus/
+   disabled, component nhập liệu thêm error; §6 chép kết quả T2 nguyên văn.
+
+🔴 **Không chọn màu brand thay khách.** Placeholder xanh trung tính trong template là để HIFI *chạy được*,
+không phải đề xuất nhận diện. `DS` §0 phải ghi độ tin cậy và ai sẽ chốt.
+
+### Activity `hifi` — Mockup hi-fi từng US
+
+Dùng `templates/hifi.html` → `03-specification/design/HIFI_<US>_v1.0.html`. Làm **sau** `wf` của ba-3.
+
+1. **`<style>`** = khối `:root` của `ds/tokens.css` + khối `ds-components` của `ds/components.html`
+   **nguyên văn** + phần "Khung xem HIFI" của template giữ nguyên. Phép kiểm H1 so từng ký tự.
+2. **Mỗi `SCR` của SRS §2.1** một `<section class="hf-frame" id="SCR-xx">` — kể cả modal và trang trạng
+   thái. Bố cục theo bảng vùng `WF` §3.x.1: mỗi vùng `data-zone="Zn" data-name`. Thứ tự DOM = thứ tự focus
+   `WF` §3.x.6.
+3. **Mỗi thành phần** SRS §2.3.1 → `data-c`; mỗi field §2.3.3 → `data-f`; kiểu trình bày → lớp `.ds-*`
+   theo `DS` §3. Tập ID **khớp hai chiều** với SRS (H3). Thành phần chỉ có ở prototype ⇒
+   `<span class="hf-proto-only" data-ref="WF §5 #n">`, **không** gán `data-c`.
+4. **Mọi chuỗi hiển thị** → `data-key` + text **nguyên văn** SRS §4.2 (W5, phép kiểm H4). Message lỗi
+   dùng `data-key="E-<DOMAIN>-nnnn"`. Không "làm gọn" câu chữ — text là của BA, không phải của Design.
+5. **Trạng thái** SRS §2.3.6 / `WF` §3.x.3 → khối `data-state` trong cùng vùng: `default · loading ·
+   empty-none · empty-filter · error · submitting · invalid`. Hai trạng thái rỗng **trông khác nhau**
+   (`.ds-empty` có minh hoạ + nút chính · `.ds-empty--filter` không minh hoạ + nút phụ).
+6. **Ẩn/khoá/read-only** (W7) → `data-vis`, disabled **bắt buộc `title`** nêu lý do.
+7. **Responsive** — mọi SCR phải xem được ở `desktop` và `mobile` (bảng → card qua `.ds-table-wrap`/
+   `.ds-cards`; `.ds-hide-m`/`.ds-hide-d`); `tablet` nếu `UICONV` §1 có.
+8. **Cấm** mã màu/px thô trong markup (trừ độ rộng cột theo SRS §2.3.2), emoji thay icon, font ngoài token.
+
+Sau khi ghi: chạy `design-check.mjs --tokens … --components … --html HIFI --srs SRS --wf WF`; H1–H5 phải
+`✅`. Không có Bash ⇒ tự kiểm bằng grep tập `[CF][0-9]{2}` hai phía và báo trong kết quả.
+
+### Activity `proto` — Prototype bấm được *(tuỳ chọn)*
+
+Không tạo file mới. Trên HIFI: mỗi cạnh của sơ đồ điều hướng SRS §2.2 → `data-nav="SCR-yy"` trên đúng
+thành phần gây điều hướng, **kể cả cạnh quay lại** (Huỷ, Đóng, Back). Mở `?mode=proto` để thử. Ghi bảng
+luồng vào `DSPEC` §4; cạnh có trong HIFI mà SRS không có ⇒ `DSPEC` §6.
+
+### Activity `figma` — Gói nhập Figma
+
+Tạo `03-specification/design/FIGMA_<US>_v1.0/`:
+
+1. **SVG** — từ `templates/figma-package/SCR-xx.desktop.svg`, một file mỗi `SCR × {desktop, mobile}`
+   (+ `tablet` nếu UICONV có; + trạng thái `empty-none`/`error` là hậu tố). Layer `<g id="Zn">` theo WF,
+   `<g id="Cnn">` theo SRS. **Màu là mã nguyên văn từ tokens.json** kèm `data-token` — Figma không đọc
+   biến CSS. Text nguyên văn SRS §4.2.
+2. **`tokens.dtcg.json`** — bản sao `00-index/ds/tokens.json`.
+3. **`README-import.md`** — từ template, điền tên US/project, font brand, danh sách file.
+4. **`png/`** — người điều phối (có Bash) chạy `scripts/render-figma.sh HIFI… FIGMA…/png`; runner không
+   có Bash ⇒ để trống thư mục và ghi việc này vào `humanInputNeeded`.
+
+🔴 **Nói thẳng với người dùng:** không có file `.fig`; gói này là những định dạng Figma **nhập được** và
+giữ được layer/token. Designer sửa trong Figma ⇒ link Figma quay lại làm `--proto` cho vòng sau.
+
+### Activity `dspec` — Đặc tả thiết kế & bàn giao
+
+Dùng `templates/design-spec.md` → `03-specification/design/DSPEC_<US>_v1.0.md`. Điền §1 bản đồ tệp cho
+**mọi** SCR, §2 redline (token, kích thước — không viết "xem hình"), §3 ánh xạ trạng thái BR → badge,
+§5 khả năng truy cập, **§6 lệch** (bắt buộc kể cả rỗng), §7 bàn giao. Chép kết quả `design-check.mjs`
+vào §6 nguyên văn.
+
+## Trước khi kết thúc
+
+In bốn thứ:
+
+**① Kết quả `design-check.mjs`** nguyên văn (T1, T2, H1–H5, S1). Còn 🔴 ⇒ nói thẳng G3 phần design
+chưa đạt, liệt kê ID/khoá/mã màu lệch. Không chạy được ⇒ nói rõ phép kiểm nào chưa chạy.
+
+**② Bảng tự chấm G3 — phần design** (`../ba-lifecycle/references/workflow.md` §2, các dòng *(screen · design)*)
+dạng ☐/✅.
+
+**③ Độ tin cậy visual** (🟢/🟡/🔴 theo `DS` §0) và **`OQ` mở** — cái nào chặn G3 đánh 🔴.
+
+**④ Chữ ký cần** — Designer cho `DS`, `HIFI`, `DSPEC`; không có Designer ⇒ PO + `DEC-nn`. `RIGOR = light`
+⇒ `HIFI` không bắt buộc (xem workflow.md); `strict` ⇒ thêm tương phản AA cho **mọi** cặp và đủ tablet.
+
+## Bẫy thường gặp
+
+**Chép prototype vào HIFI.** Prototype có nút mà SRS không có ⇒ `hf-proto-only`, không `data-c`. Thêm
+thẳng vào là scope creep bằng hình ảnh (W11).
+
+**Sửa text cho "đẹp".** "Tạo mới" thành "Tạo" là vi phạm W5 và H4 sẽ bắt. Text là của BA; muốn đổi ⇒ `OQ`.
+
+**Chọn màu brand rồi coi là chốt.** Placeholder trung tính không phải đề xuất nhận diện; `DS` §0 phải ghi
+🔴 và ai chốt.
+
+**Mã màu thô trong markup.** `style="color:#333"` là chỗ HIFI lệch DS im lặng. H2 bắt; sửa bằng biến.
+
+**Chỉ vẽ desktop.** Bảng → card ở mobile là quyết định thiết kế thật (cột nào ưu tiên — `UICONV` §3), không
+phải "responsive tự lo".
+
+**Quên trạng thái rỗng thứ hai, hoặc vẽ giống nhau.** Đây là lỗi kinh điển kế thừa từ ba-3.
+
+**Disabled không có tooltip.** Nút mờ mà không nói vì sao khiến người dùng tưởng mất quyền (W7).
+
+**Emoji thay icon.** Không scale, không đổi màu được, mỗi hệ điều hành một hình.
+
+**Tưởng xuất được `.fig`.** Không có API tạo file Figma; hãy nói rõ ngay từ Bước 0.
+
+**HIFI lệch WF về vị trí mà không ghi.** Đổi bố cục là quyền của Designer, nhưng phải có dòng ở `DSPEC` §6
+để BA cập nhật WF — không thì hai tài liệu kể hai câu chuyện.