Khi BA chọn thư viện UI — ảnh hưởng lên control-type-library.md

Chuyện gì xảy ra khi bạn chọn một thư viện UI?

Tưởng tượng bạn đang làm một dự án phần mềm. Bạn cần màn hình có nút bấm, ô nhập liệu, bảng dữ liệu, dropdown... Thay vì bắt developer tự code từng cái một, bạn chọn một thư viện UI có sẵn — như Ant Design, Shadcn UI, hay MUI.

Khoảnh khắc bạn chốt thư viện đó, rất nhiều thứ trong tài liệu BA của bạn tự động được đơn giản hóa. Vì sao? Vì những behaviour cơ bản như "nút đổi màu khi hover", "dropdown tự động đóng khi chọn", "input báo đỏ khi sai" — thư viện đã lo hết rồi. Bạn không cần mô tả lại.

Trang này giải thích:

• Control Type Library là gì, nó nằm ở đâu
• Backbone có một cái "cổng" (gate) — bắt bạn dừng lại suy nghĩ trước khi chốt thư viện
• Quy trình từng bước để quyết định
• Ví dụ thực tế với Ant Design và Shadcn UI

---

Control Type Library là gì?

Control Type Library (control-type-library.md) là một file nằm trong 02_backbone/ — cùng cấp với backbone.md. Nó định nghĩa 20 loại control chuẩn mà mọi màn hình trong dự án sẽ dùng:

Mỗi control type có 4 phần:

1. Default States — các trạng thái tự nhiên (hover, focus, disabled, loading, empty...)
2. Default Behaviour — cách nó hoạt động mặc định
3. Edge Cases — các tình huống đặc biệt cần mô tả thêm
4. Component Mapping — component tương ứng trong thư viện

File này do Lead BA tạo và quản lý. Module BA không được sửa.

---

"Cổng" thư viện UI — backbone hỏi bạn trước khi tạo control-type-library

Đây là điều quan trọng nhất cần hiểu: backbone không tạo control-type-library một cách im lặng. Nó luôn hỏi bạn trước — bạn muốn chọn thư viện nào?

Có hai con đường để qua cổng:

Đường nhanh (single-run) — chọn ngay, đi tiếp luôn

Bạn đã biết team sẽ dùng thư viện gì. Backbone hỏi, bạn chọn, xong.

1. BA chạy ba-start backbone
2. BA-kit tạo DESIGN.md (đã có sẵn Section 10 "Thư viện UI" với giá trị TBD) và shared-shell-contract.md
3. BA-kit kiểm tra Section 10 → thấy TBD → hỏi bạn bằng prompt tương tác:

Hỏi: "DESIGN.md đã có design direction nhưng chưa chốt thư viện UI. Bạn muốn chọn thư viện nào?"

Các lựa chọn:
- "Shadcn UI" — component library phổ biến, Tailwind-based
- "Ant Design 5.x" — design system đầy đủ, phù hợp enterprise
- "MUI (Material UI)" — Material Design, hệ sinh thái React lớn
- "Chakra UI" — accessible, composable
- "Tailwind UI" — utility-first, không opinionated
- "Flowbite" — Tailwind component library
- "none" — không dùng thư viện UI nào
- "Tôi cần thời gian research" — dừng backbone, điền DESIGN.md sau rồi chạy lại

4. Bạn chọn, ví dụ "Ant Design 5.x" → BA-kit ghi vào DESIGN.md Section 10, gate passed
5. BA-kit tiếp tục tạo control-type-library.md với pruning theo Ant Design — tất cả trong cùng một lần chạy

Đường nghiên cứu (two-run) — cần thời gian, dừng lại đã

Bạn chưa chắc chọn gì. Cần hỏi Tech Lead, so sánh, research.

1. BA chạy ba-start backbone
2. BA-kit tạo DESIGN.md và hỏi prompt như trên
3. Bạn chọn "Tôi cần thời gian research" → BA-kit dừng, in hướng dẫn:

⏸️  Đã dừng ở gate 5.1a. DESIGN.md đã được tạo với library = TBD.

Khi đã chốt thư viện UI:
- Cách 1: Mở DESIGN.md → điền Section 10 "Thư viện UI" → chạy lại backbone.
- Cách 2: Chạy lại backbone, em sẽ hỏi lại câu này.

Gợi ý: Shadcn UI, MUI, Ant Design, Chakra UI, Tailwind UI, Flowbite...
Hoặc chọn "none" nếu không dùng thư viện nào.

4. Bạn nghiên cứu, hỏi team, chốt thư viện
5. Bạn điền Section 10 trong DESIGN.md (hoặc chạy lại backbone và chọn khi được hỏi)
6. Chạy lại ba-start backbone → gate passed → tạo control-type-library.md

DESIGN.md Section 10 — nơi giữ quyết định của bạn

Khi backbone tạo DESIGN.md lần đầu, Section 10 trông như sau:

## 10. Thư viện UI / UI Library

> **Quan trọng:** Mục này là gate bắt buộc trước khi tạo `control-type-library.md`.

| Trường | Giá trị |
|--------|---------|
| Thư viện UI | `TBD` |
| Phiên bản | `TBD` |
| Docs tham chiếu | `TBD` |
| Ghi chú | [Lý do chọn library này, trade-off, hoặc "none" nếu không dùng thư viện nào] |

**Trạng thái chốt:** [ ] Chưa chốt

Sau khi bạn chốt (qua prompt hoặc tự điền):

| Trường | Giá trị |
|--------|---------|
| Thư viện UI | `Ant Design` |
| Phiên bản | `5.x` |
| Docs tham chiếu | `https://ant.design/components/overview/` |
| Ghi chú | Coverage cao (18/20 control type), có docs tiếng Việt, team dev đã quen |

**Trạng thái chốt:** [x] Đã chốt — 2026-06-10, Lead BA + Tech Lead

Gate này không chỉ có trong backbone

Ngay cả khi bạn dùng lệnh ba-kit init-control-library trực tiếp, gate 5.1a vẫn chạy. CLI sẽ kiểm tra DESIGN.md Section 10 và chặn nếu vẫn là TBD hoặc trống. Không có đường tắt nào bỏ qua gate này.

Sơ đồ tóm tắt

Lần 1: ba-start backbone
  → Tạo DESIGN.md + shared-shell-contract
  → Gate 5.1a: Prompt "Chọn thư viện UI?"
    ├─ Chọn library cụ thể → Ghi vào DESIGN.md → ✓ passed
    │   → Tạo control-type-library.md NGAY trong lần chạy này (single-run)
    │
    └─ "Tôi cần thời gian research" → ⏸️ DỪNG (two-run)
        → ... research, hỏi team, điền DESIGN.md ...
        → Chạy lại backbone → gate passed → tạo control-type-library.md

---

Baseline pruning là gì?

Baseline pruning = "tỉa bớt" những behaviour mà thư viện đã làm sẵn, chỉ giữ lại những gì khác biệt (deviation).

Ví dụ với Shadcn UI:

Kết quả sau khi prune: file control-type-library.md chỉ còn baseline info + deviation behaviour + edge cases. Ngắn hơn rất nhiều so với template gốc.

---

Quy trình từng bước để BA quyết định thư viện UI

Đây là quy trình 6 bước dành cho BA (không cần biết code):

Bước 1: Xác định bạn có cần thư viện UI không

Không phải dự án nào cũng cần. Hỏi 3 câu sau:

• Dự án có giao diện người dùng không? Nếu là API/system backend thuần → không cần, chọn none.
• Có bao nhiêu màn hình? Dưới 5 màn hình đơn giản → có thể không cần thư viện.
• Team dev dùng gì? Nếu dev team đã quen một thư viện → dùng luôn thư viện đó.

Nếu câu trả lời là "cần" — đi tiếp bước 2. Nếu "không cần" — ghi none vào DESIGN.md và chạy backbone.

Bước 2: Lên danh sách tiêu chí đánh giá

Ngồi với team (Lead BA + Tech Lead + 1 đại diện dev) và chốt các tiêu chí sau:

Mỗi tiêu chí chấm 1-5. Tổng điểm cao nhất → chọn.

Bước 3: So sánh 2-3 thư viện

Lập bảng so sánh ngắn. Ví dụ:

Bước 4: Chốt quyết định và ghi vào DESIGN.md

Sau khi team thống nhất, Lead BA ghi quyết định vào designs/\{slug\}/DESIGN.md Section 10:

## 10. Thư viện UI / UI Library

| Trường | Giá trị |
|--------|---------|
| Thư viện UI | `Ant Design` |
| Phiên bản | `5.x` |
| Docs tham chiếu | `https://ant.design/components/overview/` |
| Ghi chú | Coverage cao (18/20 control type), có docs tiếng Việt, team dev đã quen |

**Trạng thái chốt:** [x] Đã chốt — 2026-06-10, Lead BA + Tech Lead

Ba cách để điền: (1) Chọn ngay khi backbone hỏi prompt → BA-kit tự ghi. (2) Mở DESIGN.md, điền tay vào bảng. (3) Chạy lại backbone, trả lời prompt lần nữa. Cách nào cũng được — miễn là Section 10 không còn TBD.

Bước 5: Qua cổng — tạo control-type-library

Sau khi DESIGN.md Section 10 đã có thư viện cụ thể (không phải TBD), chạy ba-start backbone.

Nếu bạn chọn library ngay từ prompt ở lần chạy trước, bước này đã xong — BA-kit đã tạo control-type-library.md trong cùng lần chạy đó.

Nếu bạn đi đường two-run (research trước), lần chạy này BA-kit sẽ:

1. Thấy DESIGN.md và shared-shell-contract đã có → skip, không tạo lại
2. Đọc Section 10 → library đã chốt → Gate 5.1a passed
3. Copy control-type-library-template.md vào 02_backbone/
4. Đọc docs của thư viện (qua link trong DESIGN.md)
5. So sánh từng behaviour trong template với library default
6. Xóa behaviour nào thư viện đã có sẵn
7. Giữ behaviour nào khác biệt (deviation)
8. Giữ nguyên Edge Cases (luôn là project-specific)
9. Điền bảng Baseline ở đầu file

Bước 6: Review kết quả prune

Sau khi BA-kit chạy xong, Lead BA nên mở control-type-library.md và kiểm tra:

• Baseline đúng không? Tên thư viện, phiên bản, link docs có chính xác không?
• Có bỏ sót deviation không? Behaviour nào quan trọng với dự án nhưng bị xóa nhầm?
• Có giữ nhầm behaviour library làm sẵn không? Behaviour nào rõ ràng là default của library nhưng vẫn còn trong file?

Nếu phát hiện sai → sửa trực tiếp trong control-type-library.md hoặc chạy lại backbone.

Kết quả: file control-type-library.md gọn, chỉ chứa những gì dev cần biết thêm ngoài thư viện.

---

Ví dụ cụ thể: Chọn Ant Design

Trước khi prune (template gốc)

### 3. Button (`button`)

**Default States:** `default`, `hover`, `focus`, `active`, `disabled`, `loading`

**Default Behaviour:**
- Hover: đổi màu nền nhạt hơn 10%
- Focus: hiện viền outline 2px
- Active: đổi màu nền đậm hơn 10%
- Disabled: xám đi, con trỏ thành `not-allowed`
- Loading: hiện spinner, vô hiệu hóa click
- Click vào button primary → submit form
- Click vào button danger → mở confirmation dialog trước khi thực hiện hành động hủy

**Edge Case cần mô tả thêm:**
- Button bị click 2 lần liên tiếp trong < 300ms → chặn double submit
- Button trong trạng thái loading quá 30s → timeout và báo lỗi

Sau khi prune (Ant Design làm baseline)

Giả sử Ant Design đã có sẵn: hover, focus, active, disabled, loading với behaviour y hệt. Nhưng Ant Design không có sẵn confirmation dialog cho button danger, và không có sẵn double-submit prevention.

### 3. Button (`button`) — Baseline: Ant Design 5.x

**Default States:**
- (default) Kế thừa từ Ant Design Button
- **Khác default:** Không (tất cả state đều dùng default của Ant Design)

**Default Behaviour:**
- (default) Hover, Focus, Active, Disabled, Loading — kế thừa từ Ant Design
- **Khác default:**
  - Click vào button danger → mở confirmation dialog trước khi thực hiện hành động hủy
  - Click vào button primary → submit form (Ant Design có sẵn)

**Edge Case cần mô tả thêm:**
- Button bị click 2 lần liên tiếp trong < 300ms → chặn double submit
- Button trong trạng thái loading quá 30s → timeout và báo lỗi

**Component Mapping:** `<Button>` từ `antd`

Để ý: file sau khi prune ngắn hơn hẳn. BA chỉ mô tả những gì Ant Design không làm sẵn.

---

Vai trò của từng người trong quá trình này

---

Những câu hỏi thường gặp

"Nếu dự án không dùng thư viện UI thì sao?"

Ghi none vào DESIGN.md mục "Thư viện UI", rồi chạy backbone lần 2. Gate 5.1a vẫn passed. File control-type-library.md giữ nguyên toàn bộ 20 control type với đầy đủ behaviour. BA sẽ phải mô tả tất cả behaviour cho mọi control type trong mọi màn hình.

"Tôi chạy backbone lần đầu, nó dừng lại — tôi phải làm gì?"

Đây là hành vi bình thường. Backbone đang hỏi bạn chọn thư viện UI. Bạn có 2 lựa chọn ngay lúc đó:

• Chọn library ngay trong prompt nếu đã biết → BA-kit ghi vào DESIGN.md và tiếp tục tạo control-type-library luôn (xong trong 1 lần chạy).
• Chọn "Tôi cần thời gian research" nếu chưa chắc → backbone dừng. Bạn nghiên cứu, hỏi team, điền Section 10 trong DESIGN.md, rồi chạy lại backbone.

"Tôi không chắc nên chọn thư viện nào thì sao?"

Bắt đầu với gợi ý của BA-kit: Shadcn UI, MUI, Ant Design, Chakra UI, Tailwind UI, Flowbite. Đây là những thư viện phổ biến nhất. Thu hẹp xuống 2-3 cái dựa trên framework team dev dùng (React/Vue/Angular), rồi hỏi Tech Lead chọn giúp.

Nếu vẫn không chắc, chọn none — an toàn nhất. Có thể đổi sau (xem câu dưới).

"Nếu giữa dự án muốn đổi thư viện?"

Đây là thay đổi lớn — phải chạy ba-impact trước. Lead BA sẽ:

1. Chạy impact analysis để biết những module nào bị ảnh hưởng
2. Cập nhật DESIGN.md với thư viện mới
3. Chạy lại backbone để prune control-type-library.md theo thư viện mới
4. Module BA cập nhật lại màn hình của mình theo library mới

"Nếu thư viện không có control type tôi cần?"

Trong control-type-library.md, section của control type đó sẽ được giữ nguyên toàn bộ (vì không có library default để prune). BA phải mô tả đầy đủ behaviour như khi baseline = none.

"Module BA có được thêm control type mới không?"

Không. Control type library là artifact cấp backbone. Nếu module cần control type chưa có trong library → escalate lên Lead BA qua impact. Lead BA sẽ cập nhật backbone, sau đó module BA mới được dùng.

"Làm sao để biết behaviour nào thư viện có sẵn?"

BA-kit tự động đọc docs của thư viện (qua link trong DESIGN.md) khi chạy backbone lần 2. BA không cần tự tra. Tuy nhiên, BA nên review lại kết quả prune (Bước 6) để chắc chắn không bỏ sót deviation quan trọng.

"DESIGN.md có sẵn rồi, tôi điền thư viện vào, chạy backbone — nó có tạo lại DESIGN.md không?"

Không. Backbone kiểm tra: nếu DESIGN.md đã tồn tại → skip, không ghi đè. Nó chỉ tạo những file còn thiếu (trong trường hợp này là control-type-library.md).

---

Tóm tắt

1. Control Type Library là file backbone định nghĩa 20 control type chuẩn cho toàn dự án
2. Gate 5.1a có 2 đường: chọn library ngay trong prompt (single-run, xong 1 lần) hoặc "cần research" (two-run, dừng rồi chạy lại)
3. DESIGN.md Section 10 là nơi giữ quyết định — bảng có sẵn, chỉ cần điền giá trị (không còn định dạng tự do)
4. Không có đường tắt: kể cả ba-kit init-control-library cũng bị gate chặn nếu DESIGN.md chưa chốt
5. Lead BA là người quyết định cuối cùng và duy trì control-type-library.md
6. Module BA chỉ dùng, không sửa. Cần thay đổi → escalate qua impact
7. Kết quả: File control-type-library.md gọn, màn hình dễ viết hơn, dev không phải đoán behaviour