ba-design — Hướng dẫn sử dụng

Dùng khi nào

Dự án có giao diện (PRODUCT = screen), đã có SRS + WF + UICONV của US, và bạn cần một trong:

Design system cho project: token màu/chữ/khoảng cách, component sheet đủ trạng thái.
Mockup hi-fi của US: mọi màn hình × trạng thái × breakpoint, mở bằng trình duyệt, bấm điều hướng thử.
Gói nhập Figma: SVG từng màn hình, token, ảnh chụp, hướng dẫn nhập.
Redline bàn giao Dev FE: con số cụ thể, ánh xạ component, checklist truy cập.

Dự án không có Designer vẫn dùng được — skill đóng vai Designer đề xuất, PO ký thay kèm DEC-nn.

Cần chuẩn bị

Có	Tốt hơn nếu có
`SRS_<US>`, `WF_<US>` (md + html), `UICONV_<PROJECT>` từ ba-3	Brand guideline (màu, font, logo) hoặc design system đã chọn
`node` ≥ 18 để chạy phép kiểm	Chrome/Edge để chụp PNG cho gói Figma
Biết dự án có Designer hay không	Link Figma/prototype đã có để đối chiếu

Cách gọi

/ba-design <PROJECT> ds                  # sinh design system (một lần)
/ba-design US-002 hifi                   # mockup hi-fi cho US-002
/ba-design US-002 proto                  # bật điều hướng bấm được trên HIFI
/ba-design US-002 figma                  # gói nhập Figma
/ba-design US-002 dspec                  # redline + bàn giao
/ba-design US-002 --brand brand/guide.pdf go   # chạy liền, không dừng Bước 0

Qua pipeline có duyệt: /ba-pipeline → stage design, activity tương ứng.

Đọc kết quả

Mở HIFI_<US>_v1.0.html, dùng toolbar: chọn màn hình, khung nhìn, trạng thái; tick C-id/F-id và Vùng Zn để đối chiếu với SRS/WF; chọn Prototype để bấm điều hướng.

Chạy phép kiểm:

node .claude/skills/ba-design/scripts/design-check.mjs \
  --tokens ba-output/<P>/00-index/ds/tokens.json --css ba-output/<P>/00-index/ds/tokens.css \
  --components ba-output/<P>/00-index/ds/components.html \
  --html ba-output/<P>/03-specification/design/HIFI_<US>_v1.0.html \
  --srs ba-output/<P>/03-specification/SRS_<US>_v1.0.md --wf ba-output/<P>/03-specification/WF_<US>_v1.0.md \
  --svg-dir ba-output/<P>/03-specification/design/FIGMA_<US>_v1.0

Mọi dòng phải ✅. 🔴 H3 = thành phần lệch SRS; 🔴 H4 = text bị sửa; 🔴 T2 = màu không đủ tương phản.

Chụp ảnh cho gói Figma:

.claude/skills/ba-design/scripts/render-figma.sh ba-output/<P>/03-specification/design/HIFI_<US>_v1.0.html \
  ba-output/<P>/03-specification/design/FIGMA_<US>_v1.0/png

Nhập vào Figma

Đọc FIGMA_<US>_v1.0/README-import.md. Tóm tắt: token trước (Tokens Studio), rồi component sheet (html.to.design), rồi kéo SVG từng màn hình vào frame. Không có file .fig — Figma không cho tạo file bằng API; gói này là các định dạng Figma nhập được và giữ layer.

Lỗi thường gặp

Triệu chứng	Nguyên nhân	Sửa
`🔴 H1 khối :root không trùng`	Sửa tay tokens.css hoặc HIFI thay vì sửa tokens.json	`--emit-css` sinh lại, chép vào HIFI
`🔴 H3 chỉ có trong HIFI: C07`	HIFI vẽ nút prototype có mà SRS không có	Bọc `hf-proto-only`, ghi WF §5
`🔴 H4 text khác SRS`	Design "làm gọn" nhãn	Chép lại nguyên văn; muốn đổi ⇒ OQ cho BA/PO
HIFI đẹp nhưng Dev hỏi "màu này là gì"	DS §0 ghi độ tin cậy 🔴 mà không ai chốt	Đưa OQ brand lên PO trước G3
Figma báo Missing fonts	Máy không có font brand	Cài font hoặc đổi `font.family.base`

3.8 KiB Raw Permalink Blame History Unescape Escape