# 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:

  ```bash
  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:

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