129 lines
7.0 KiB
Markdown
129 lines
7.0 KiB
Markdown
# 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`) | | |
|