# DSPEC — Đặc tả thiết kế & bàn giao — | | | |---|---| | **Version** | 1.0 | | **Date** | YYYY-MM-DD | | **Author** | (skill ba-design, activity `dspec`) | | **Status** | 🟡 Draft | | **Approved by** | Designer: — · PO: — | | **Source** | SRS_ v1.0 · WF_ v1.0 · UICONV_ v1.0 · DS_ v1.0 · prototype: <đường dẫn / "không có"> | | **Scope** | US-0nn · SCR-01, SCR-02, … | | **Tệp kèm** | `HIFI__v1.0.html` · `FIGMA__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__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 — | 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 `; `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__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`) | | |