182 lines
14 KiB
Markdown
182 lines
14 KiB
Markdown
---
|
||
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.
|