docs(agent): thư viện instruction cho việc sửa bug UI/UX

Bộ 7 role chuyên biệt (triage → specialist → implementer → reviewer) cùng
lớp dùng chung: guardrail, tri thức về repo, checklist, và contract đầu ra.

Vì sao có: bug UI/UX được báo bằng lời kể triệu chứng, và người sửa hay bỏ
qua ba thứ mà repo này rất dễ vi phạm — luật "không file nào ngoài theme/
được đặt tên một màu", trần LOC theo bánh cóc, và việc ui/ với presentation/
cùng tồn tại nên sửa nhầm file là "đã fix mà vẫn thấy lỗi".

knowledge/qt_pitfalls.md chép lại 20 nguyên nhân gốc hay gặp của bug PySide6;
examples/bad_fix.md có hai ca CÓ THẬT, gồm ca chính bản vá trong nhánh này
từng mắc (compare_digest trên str ngoài ASCII) và lọt qua vòng review đầu.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

agent/checklist/ui_review.md

@@ -0,0 +1,49 @@
+# Checklist review bản vá UI (visual)
+
+Dùng bởi `ui-visual-fixer` (bước 7) và `regression-reviewer` (bước 5).
+
+## A. Đúng file
+
+- [ ] Đã `grep` cả `ui/` và `presentation/`; file được sửa là file thực sự import vào runtime.
+- [ ] Widget này không có bản trùng tên ở thư mục còn lại.
+
+## B. Màu & theme
+
+- [ ] Không hex literal (`#rrggbb`), không tên màu (`"red"`) ngoài `theme/`.
+- [ ] Không `setStyleSheet` cục bộ mới; style đi qua `objectName` + `theme/qss.py`.
+- [ ] Token mới có ở **cả** `DARK` và `LIGHT`.
+- [ ] Chữ trên nền đặc dùng `accent_solid`, không dùng `accent`.
+- [ ] Bậc bề mặt đúng ngữ nghĩa: `bg` / `surface` / `surface_raised` / `overlay` / `sunken`.
+- [ ] Contrast ≥ 4.5:1 cho body text và chữ trên nút đặc, ở cả hai theme.
+- [ ] Không thêm gradient/glow (trái ràng buộc thiết kế).
+- [ ] Nav rail vẫn tối hơn vùng nội dung.
+- [ ] Không trả bốn giá trị đã nhích lên WCAG AA về giá trị VS Code gốc.
+- [ ] Nếu chạm `_TEMPLATE`: đã liệt kê phạm vi ảnh hưởng toàn app.
+
+## C. Layout & kích thước
+
+- [ ] Không thêm `setFixedWidth` / `setFixedSize` / `setFixedHeight` mới.
+- [ ] Stretch factor / size policy được đặt tường minh.
+- [ ] `QScrollArea` có `setWidgetResizable(True)`.
+- [ ] Margin/spacing của layout lồng nhau không cộng dồn ngoài ý muốn.
+- [ ] Còn đúng ở cửa sổ nhỏ nhất **và** maximize.
+- [ ] Còn đúng ở scale 125% / 150% nếu bản vá chạm kích thước.
+
+## D. Icon & vẽ tay
+
+- [ ] Icon lấy qua `ui/icons.py::icon`, không load file trực tiếp.
+- [ ] `paintEvent` đọc màu qua `current_palette()`, không đọc lại config.
+- [ ] Dùng `update()`, không `repaint()` trong vòng lặp.
+- [ ] `QPainter` có `end()`; nền được xoá đúng cách.
+
+## E. Vòng đời
+
+- [ ] Bản vá còn đúng khi đổi theme **trước** rồi mới mở màn dựng lười (P07).
+- [ ] `setProperty` để đổi style động có kèm `unpolish`/`polish`.
+- [ ] Không `connect()` lặp lại trong hàm được gọi nhiều lần.
+
+## F. Bằng chứng
+
+- [ ] Đã đối chiếu `docs/screens/<slug>-dark.png` và `<slug>-light.png`.
+- [ ] Ảnh trong `docs/screens/` cần cập nhật thì đã nêu.
+- [ ] Có test regression chạy headless, đỏ-trước-xanh-sau.