update skill ba

.claude/skills/ba-design/templates/design-spec.md

@@ -0,0 +1,128 @@
+# DSPEC — Đặc tả thiết kế & bàn giao — <US-id>
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Date** | YYYY-MM-DD |
+| **Author** | <BA/Design> (skill ba-design, activity `dspec`) |
+| **Status** | 🟡 Draft |
+| **Approved by** | Designer: — · PO: — |
+| **Source** | SRS_<US> v1.0 · WF_<US> v1.0 · UICONV_<PROJECT> v1.0 · DS_<PROJECT> v1.0 · prototype: <đường dẫn / "không có"> |
+| **Scope** | US-0nn · SCR-01, SCR-02, … |
+| **Tệp kèm** | `HIFI_<US>_v1.0.html` · `FIGMA_<US>_v1.0/` |
+| **Prototype bấm được** | ✅ có (`HIFI…html?mode=proto`) / ❌ không |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi | CR |
+|---|---|---|---|---|
+| 1.0 | | | Bản đầu | — |
+
+> **Quy ước đọc** *(W11)*. `SRS` quyết định phần tử **có tồn tại không** và **hành xử thế nào**; `WF` quyết định
+> **nằm ở đâu**; `DS` quyết định **trông thế nào** (token, component); tài liệu này ghi **con số cụ thể** để Dev FE dựng
+> đúng HIFI mà không phải đo bằng mắt. Mâu thuẫn ⇒ SRS > WF > DS > HIFI, và mâu thuẫn phải ghi ở §6.
+
+---
+
+## 0. Nguồn bố cục và độ tin cậy
+
+| | |
+|---|---|
+| **HIFI dựng từ** | `WF` §3 (bố cục) + `DS` (visual) + `SRS` §2.3 / §4.2 (thành phần, text) |
+| **Prototype tham chiếu** | *(Figma/HTML/SAD §7 · phiên bản · mức phủ n/m màn hình — theo `WF` §0)* |
+| **Độ tin cậy visual** | 🟢 DS có brand thật · 🟡 DS suy từ prototype · 🔴 DS placeholder trung tính (`DS` §0) — *HIFI mang độ tin cậy của DS* |
+
+## 1. Bản đồ màn hình → tệp
+
+| SCR | Tên | HIFI (`#id`) | Trạng thái có trong HIFI | SVG (FIGMA) | PNG | Khớp WF §3.x |
+|---|---|---|---|---|---|---|
+| SCR-01 | | `HIFI_<US>_v1.0.html#SCR-01` | default · loading · empty-none · empty-filter · error | `SCR-01.desktop.svg` · `SCR-01.mobile.svg` | `png/SCR-01.desktop.default.png` … | ✅ |
+
+*Mọi `SCR` của `SRS` §2.1 phải có một dòng. Trạng thái phải khớp `SRS` §2.3.6 / `WF` §3.x.3 — thiếu trạng thái nào ghi rõ và lý do.*
+
+## 2. Redline từng màn hình
+
+### 2.1 SCR-01 — <Tên màn hình>
+
+| Vùng (WF) | Kích thước desktop | Kích thước mobile | Padding | Gap | Token nền / viền |
+|---|---|---|---|---|---|
+| Z1 Header màn hình | full × auto | full × auto | `space.6` `space.4` | `space.2` | `bg.canvas` |
+| Z3 Dữ liệu | full | full | 0 | — | `bg.surface` + `border.default`, `radius.md` |
+
+| C-id | Thành phần | Lớp DS | Kích thước | Token chữ | Token màu | Trạng thái thể hiện trong HIFI |
+|---|---|---|---|---|---|---|
+| C01 | lbl_title | h1 | auto | `size.xl / semibold` | `text.primary` | — |
+| C02 | btn_create | `.ds-btn--primary` | auto × 36 (44 mobile) | `size.sm / semibold` | `brand.primary` | hover · focus · disabled(+tooltip) |
+
+**Khác biệt so với `WF` §3.1:** *(không có / liệt kê — mọi khác biệt về vị trí phải có lý do và Designer duyệt)*
+
+### 2.2 SCR-02 — …
+
+*(lặp 2.1)*
+
+## 3. Ánh xạ trạng thái nghiệp vụ → hiển thị
+
+| Trạng thái (BR §3) | Badge (DS §3) | Nhãn nguyên văn (SRS §4.2) | Hành động bị khoá (W7, SRS §2.3.1) |
+|---|---|---|---|
+
+## 4. Luồng prototype *(chỉ khi có prototype bấm được)*
+
+*Mỗi cạnh khớp `SRS` §2.2; cạnh có trong HIFI mà SRS không có ⇒ §6.*
+
+| Từ | Thành phần (`data-nav`) | Đến | Có trong SRS §2.2 |
+|---|---|---|---|
+| SCR-01 | C02 btn_create | SCR-03 | ✅ |
+
+## 5. Khả năng truy cập
+
+| Kiểm tra | Kết quả | Bằng chứng |
+|---|---|---|
+| Tương phản chữ (AA ≥ 4.5) trên mọi cặp dùng trong HIFI | ☐/✅ | `design-check.mjs` T2 |
+| Hit target mobile ≥ 44 px cho mọi nút/ô nhập | | `size.control.touch` áp qua `body[data-view="mobile"]` |
+| Thứ tự focus khớp `WF` §3.x.6 | | thứ tự DOM trong HIFI |
+| Mọi ô nhập có nhãn; mọi icon-button có `aria-label` | | grep `aria-label` |
+| Không truyền nghĩa chỉ bằng màu (badge có chữ, lỗi có icon + text) | | |
+| Tắt motion khi `prefers-reduced-motion` | | DS §7 |
+
+## 6. Lệch HIFI ↔ WF / SRS / DS
+
+*Bắt buộc, kể cả rỗng ("đã đối chiếu n màn hình, không lệch"). Lệch với `SRS` về Tồn tại/Hành vi/Text ⇒ 🔴 chặn G3; lệch với `WF` về bố cục ⇒ Designer quyết; lệch với `DS` ⇒ phải có dòng `DS` §8.*
+
+| # | Màn hình | HIFI có | Tài liệu nói | Loại | Bên thắng | Xử lý | Ai quyết | Trạng thái |
+|---|---|---|---|---|---|---|---|---|
+
+**Kết quả `design-check.mjs`:** C-id lệch hai chiều: *(rỗng)* · data-key text lệch SRS §4.2: *(rỗng)* · mã màu thô ngoài token: *(0)* · SCR thiếu: *(0)*.
+
+## 7. Bàn giao cho Dev FE
+
+| | |
+|---|---|
+| **Lấy từ HIFI** | Bố cục, khoảng cách, token, trạng thái thị giác, thứ tự DOM/focus. Mở `?ids=1&zones=1` để thấy C-id và vùng |
+| **Lấy từ SRS** | Hành vi, điều kiện ẩn/khoá, validation, mã lỗi, text (HIFI chỉ *chép* text từ SRS §4.2) |
+| **Lấy từ DS** | `tokens.json` → biến CSS/theme của stack đã chọn; lớp `.ds-*` → component tương ứng (DS §3 cột 3) |
+| **Không được suy ra từ HIFI** | Dữ liệu mẫu (số liệu, tên) · độ dài/khoảng giá trị (ở SRS §2.3.3) · hành vi khi lỗi (SRS §2.3.5) |
+| **Khi Designer sửa trong Figma** | Báo BA ⇒ chạy lại `hifi` + `figma` với `--proto <link>`; `SRS` chỉ đổi nếu lệch Tồn tại/Hành vi được PO chấp nhận |
+| **Ảnh tham chiếu** | `FIGMA_<US>_v1.0/png/` — chụp từ HIFI, dùng để đối chiếu pixel khi review giao diện đã build (ba-4) |
+
+## 8. Open Questions
+
+| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì | 🔴 chặn G3? |
+|---|---|---|---|---|---|
+
+---
+
+## Tự chấm
+
+| # | Tiêu chí | ☐/✅ | Ghi chú |
+|---|---|---|---|
+| 1 | Mọi `SCR` của `SRS` §2.1 có mặt trong HIFI (`#SCR-xx`) và §1 | | design-check H5 |
+| 2 | Tập `data-c`/`data-f` trong HIFI khớp **hai chiều** với `SRS` §2.3.1 / §2.3.3 | | design-check H3 |
+| 3 | Mọi `data-key` có text **nguyên văn** bằng `SRS` §4.2 (W5) | | design-check H4 |
+| 4 | Mọi trạng thái `SRS` §2.3.6 có khối `data-state` tương ứng; hai trạng thái rỗng trông khác nhau | | |
+| 5 | HIFI chỉ dùng biến `--ds-*` và lớp `.ds-*`; không mã màu thô trong markup | | design-check H2 |
+| 6 | Khối `:root` và khối `ds-components` trong HIFI **trùng nguyên văn** với `ds/tokens.css` + `ds/components.html` | | design-check H1 |
+| 7 | Mỗi SCR có ≥ 2 khung nhìn (desktop + mobile) trong HIFI **và** trong `FIGMA/*.svg` | | design-check S1 |
+| 8 | Mã màu trong SVG ⊆ tập token | | design-check S1 |
+| 9 | §5 tương phản đạt AA cho mọi cặp chữ | | design-check T2 |
+| 10 | §6 đã điền; không còn lệch Tồn tại/Hành vi/Text với SRS | | |
+| 11 | Có chữ ký Designer (hoặc PO + `DEC-nn`) | | |