sys-analysis-design/.claude/skills/ba-design/SKILL.md

name, description

name

description

ba-design

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.