---
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.