Ba Review Design

Tài liệu tham chiếu BẮT BUỘC đọc trước khi review

Polaris v12 (đọc từ skill)

• .claude/.agent/skills/polaris/SKILL.md — Overview + migration v12
• .claude/.agent/skills/polaris/references/layout.md — Page, Layout, BlockStack, InlineStack, Box, Card, spacing tokens
• .claude/.agent/skills/polaris/references/components.md — Text, Badge, Banner, Modal, Skeleton, EmptyState
• .claude/.agent/skills/polaris/references/buttons.md — Button variants, tones, navigation pattern
• .claude/.agent/skills/polaris/references/icons.md — Icons v9 (KHÔNG có Minor/Major suffix)

App Interface hiện tại (đọc từ documents)

• documents/roger/app-interface/UI-DESIGN-SYSTEM.md — Master design system (màu, typography, spacing, components)
• documents/roger/app-interface/README.md — Navigation + design rules
• documents/roger/app-interface/login-signup/login/LOGIN-PAGE-SPECS.md — Login page specs (tham khảo layout pattern)
• documents/roger/app-interface/login-signup/signup/SIGNUP-PAGE-SPECS.md — Signup page specs
• documents/roger/app-interface/commission/commission-ui.html — Conversions page prototype (tham khảo table/list pattern)

⭐ PNG Screenshots giao diện app thực tế (BẮT BUỘC — source of truth cho visual consistency)

Đây là ảnh chụp thực tế từ app đang chạy. Phải mở & so sánh trực tiếp với design mới.

Cách chọn screenshots để review:

Folder base: documents/roger/app-interface/

Lý do bắt buộc: Nếu design mới không match visual với app hiện tại → dev không merge được. Screenshots là bằng chứng trực quan, không phải spec trên giấy.

Quy Trình Review

Bước 1: Load context (BẮT BUỘC)

1. Đọc Polaris skill files (layout, components, buttons, icons)
2. Đọc UI-DESIGN-SYSTEM.md — nắm design system hiện tại
3. Đọc UI file cần review
4. Đọc PRD tương ứng (nếu có)
5. Mở các HTML prototype hiện có để so sánh visual consistency
6. ⭐ Mở PNG screenshots giao diện app thực tế — chọn screenshots cùng loại với design đang review (xem bảng mapping ở trên). Dùng Read tool để xem ảnh trực tiếp. Đây là bước QUAN TRỌNG NHẤT vì screenshots phản ánh app thực tế đang chạy.

Bước 2: Đánh giá theo 12 tiêu chí

Chấm: Solid / Weak / Missing — quan điểm rõ ràng

A. Polaris Compliance (Trọng số: CAO — ảnh hưởng App Store review)

B. App Consistency (Trọng số: CAO — user experience xuyên suốt)

C. UX Quality (Trọng số: TRUNG BÌNH)

Bước 3: So sánh trực tiếp với app hiện tại (PNG screenshots + HTML prototypes)

3a. So sánh với PNG screenshots (ưu tiên cao nhất)

Mở screenshots đã load ở bước 1.6, so sánh TỪNG yếu tố:

Chỉ ra TỪNG chỗ inconsistent: "Screenshot [tên file] cho thấy [pattern A], nhưng design mới dùng [pattern B] → phải sửa thành [pattern A]"

3b. So sánh với HTML prototypes

Đối chiếu design mới với các trang đã có:

• Commission page (commission-ui.html) — Pattern cho table/list, bulk actions, toast
• Login/Signup pages — Pattern cho form, button, layout 2 cột
• Forgot password — Pattern cho multi-step flow

Chỉ ra TỪNG chỗ inconsistent: "Trang X dùng pattern A, nhưng design mới dùng pattern B"

Bước 4: Cross-check với PRD

• Map TỪNG requirement → có UI tương ứng?
• AC trong PRD có thể test được trên UI này?

Bước 5: Đưa ra verdict

Output Format (trong chat, KHÔNG tạo file)

## Expert Review: Design — {Feature Name}

### Verdict: [APPROVED / NEEDS FIXES / REDESIGN]

> [1-2 câu thẳng thắn]

---

### A. Polaris Compliance

| # | Check | Kết quả | Chi tiết |
|---|-------|---------|----------|
| 1 | Component đúng v12 | ✅/⚠️/❌ | [cụ thể component nào sai] |
| 2 | Layout pattern | ✅/⚠️/❌ | [Page→Layout→Card đúng chưa] |
| 3 | Button pattern | ✅/⚠️/❌ | [mấy primary button? navigation đúng?] |
| 4 | Icons v9 | ✅/⚠️/❌ | [icon nào import sai tên] |
| 5 | Form pattern | ✅/⚠️/❌ | [FormLayout? Save bar?] |

### B. App Consistency

| # | Check | Kết quả | Chi tiết |
|---|-------|---------|----------|
| 6 | Color palette | ✅/⚠️/❌ | [màu nào ngoài palette] |
| 7 | Typography | ✅/⚠️/❌ | [font size nào sai scale] |
| 8 | Spacing | ✅/⚠️/❌ | [chỗ nào không theo grid 8px] |
| 9 | Component style | ✅/⚠️/❌ | [height/radius/shadow sai ở đâu] |

### C. UX Quality

| # | Check | Kết quả | Chi tiết |
|---|-------|---------|----------|
| 10 | User Flow | ✅/⚠️/❌ | [thiếu state nào] |
| 11 | Info Hierarchy | ✅/⚠️/❌ | [CTA có rõ?] |
| 12 | Data Display | ✅/⚠️/❌ | [pagination? filter?] |

---

### Polaris Violations (phải sửa)
1. **[Vi phạm]** — Polaris nói: [guideline]. Design đang: [sai gì]. Sửa: [code/component cụ thể]
2. ...

### Inconsistency với App hiện tại
1. **[Trang hiện tại]** dùng [pattern A], nhưng design mới dùng [pattern B] — Nên: [chọn cái nào, tại sao]
2. ...

### Missing States
- [ ] Empty state — [mô tả: dùng EmptyState component, illustration gì, heading, body, CTA]
- [ ] Error state — [mô tả]
- [ ] Loading state — [Skeleton components nào: SkeletonPage? SkeletonBodyText?]
- [ ] Permission denied — [mô tả]

### PRD Coverage

| PRD Requirement | Có UI? | Ghi chú |
|----------------|--------|---------|
| [Req 1] | ✅/❌ | — |
| [Req 2] | ❌ | Thiếu màn cho case này |

### Bước tiếp theo
- [Action cụ thể]

Quy tắc

• Verdict:
  • APPROVED: Polaris compliant, consistent với app, đủ states, PRD coverage ≥90%
  • NEEDS FIXES: Có Weak ở Polaris hoặc Consistency nhưng structure OK — sửa vài giờ
  • REDESIGN: Vi phạm nhiều Polaris guidelines, hoặc inconsistent nghiêm trọng với app hiện tại
• Polaris violations là blocking — Không APPROVED nếu còn vi phạm Polaris
• Inconsistency là blocking — Không APPROVED nếu design mới trông như app khác
• Đề xuất sửa phải có code — Không nói "dùng đúng component". Nói: "Thay <Stack> bằng <BlockStack gap='400'>"
• So sánh phải cụ thể — "Commission page dùng IndexTable với pagination, nhưng design mới dùng plain table không pagination — phải dùng IndexTable"
• KHÔNG review code quality HTML mockup — chỉ review design output