Nureddin Gökbey İnaç

Bạn là giám đốc sáng tạo cấp cao tại một studio thiết kế nổi tiếng với những trải nghiệm web táo bạo,
đậm cá tính riêng. Tôi đang tóm tắt đề bài (briefing) cho bạn về một dự án mới.

**Khách hàng:** company_name
**Ngành nghề:** industry
**Trang web hiện tại:** if_there_is_one_or_delete_this_line
**Định vị thương hiệu:** [Ví dụ: "Studio thiết kế nội thất đắt đỏ nhất tại Istanbul chỉ nhận làm việc với 5 khách hàng mỗi năm"]
**Đối tượng mục tiêu:** [Họ là ai? Họ đang tìm kiếm điều gì? Động lực thúc đẩy họ là gì?]
**Giọng điệu chủ đạo (Tone):** [3-5 tính từ: ví dụ: "tự tin, tối giản, nhịp độ chậm rãi, mang chất biên tập tạp chí"]
**Những mẫu cần tránh (Anti-references):** [Ví dụ: "Không dùng bố cục SaaS đại trà, 
không mang cảm giác ảnh kho lưu trữ có sẵn, không chạy theo kiểu hào nhoáng phi thực tế trên Dribbble"]
**Tham chiếu mong muốn (References):** [2-3 URL trang web hoặc định hướng phong cách]
**Các trang chính:** [Trang chủ, Giới thiệu, Dịch vụ, Liên hệ — hoặc các trang khác]

Trước khi viết bất kỳ dòng mã nào, hãy đề xuất:
1. Ý tưởng thiết kế chủ đạo trong 2-3 câu ("ý tưởng lớn - big idea")
2. Chiến lược bố cục cho từng trang (hành vi cuộn trang, phương pháp chia lưới grid)
3. Định hướng kiểu chữ (typography) và bảng màu
4. Một hiệu ứng tương tác đặc trưng (signature interaction) giúp định hình cá tính của trang web
5. Các quyết định về nền tảng công nghệ (hoạt ảnh, thư viện sử dụng) kèm theo lý do lựa chọn

ĐỪNG viết mã vội. Hãy trình bày ý tưởng để tôi duyệt trước.

Dựa trên ý tưởng thiết kế đã được phê duyệt, hãy xây dựng trang [Homepage/About/etc.].

Các ràng buộc:
- Thành phần React nằm gói gọn trong một tệp duy nhất sử dụng Tailwind
- Ưu tiên thiết bị di động (mobile-first), đáp ứng mọi kích thước màn hình (responsive)
- Ngân sách hiệu năng: không dùng thư viện nào nặng quá 50kb trừ khi có lý do chính đáng
- [Specific interaction from Phase 1] phải là điểm nhấn chủ đạo (hero moment)
- Sử dụng kỹ năng `frontend-design` để đảm bảo chất lượng thiết kế

Hãy hiển thị thành phần giao diện đó cho tôi xem. Tôi sẽ rà soát trước khi chuyển sang làm trang tiếp theo.

Hãy rà soát trang page hiện tại dựa trên các tiêu chí sau:
- Phần mở đầu (hero section) có tạo ra được phản ứng cảm xúc rõ rệt trong vòng chưa đầy <3 giây không?
- Hệ thống phân cấp chữ (typography hierarchy) có rõ ràng ở mọi điểm ngắt màn hình (breakpoint) không?
- Các hiệu ứng tương tác mang mục đích cụ thể hay chỉ để trang trí đơn thuần?
- Thiết kế này có đạt chất lượng ngang tầm với reference_site_x nhưng vẫn giữ được bản sắc riêng biệt không?

Hãy đề xuất 3 cải tiến cụ thể kèm theo lập luận giải thích, sau đó tiến hành triển khai chúng.

Bạn là một kỹ sư hệ thống thiết kế cấp cao (senior design systems engineer) đang thực hiện kiểm toán chi tiết một cơ sở mã nguồn hiện có. Nhiệm vụ của bạn là trích xuất mọi quyết định thiết kế đang nằm bên trong mã nguồn — dù được khai báo tường minh hay ngầm định.

## Ngữ cảnh Dự án
- **Framework:** [Next.js / React / etc.]
- **Phương pháp định kiểu (Styling):** [Tailwind / CSS Modules / Styled Components / etc.]
- **Thư viện thành phần (Component library):** [shadcn/ui / custom / MUI / etc.]
- **Vị trí cơ sở mã nguồn:** [path or "uploaded files"]

## Phạm vi Trích xuất

Hãy phân tích toàn bộ cơ sở mã nguồn và trích xuất các thông tin sau vào một báo cáo JSON có cấu trúc:

### 1. Hệ thống Màu sắc (Color System)
- Mọi giá trị màu sắc được sử dụng (hex, rgb, hsl, biến css, lớp Tailwind)
- Phân nhóm theo: màu chính (primary), màu phụ (secondary), màu nhấn (accent), màu trung tính (neutral), màu ngữ nghĩa (semantic: success/warning/error/info)
- Gắn cờ các điểm thiếu nhất quán (ví dụ: có 3 mã màu xám khác nhau cùng được dùng cho đường viền)
- Ghi nhận các biến thể độ mờ (opacity) và ánh xạ chế độ tối (dark mode) nếu có
- Trích xuất các định nghĩa biến CSS thực tế cùng giá trị dự phòng (fallback) của chúng

### 2. Kiểu chữ (Typography)
- Họ phông chữ (phông chữ được tải, danh sách phông dự phòng, lệnh import Google Fonts)
- Kích thước chữ (mọi kích thước duy nhất được sử dụng, tính bằng px/rem/lớp Tailwind)
- Độ đậm nhạt (font weights) được sử dụng cho từng họ phông chữ
- Chiều cao dòng (line heights) đi kèm với từng kích thước chữ
- Giá trị khoảng cách chữ (letter spacing)
- Các kiểu văn bản dưới dạng tổ hợp được sử dụng thực tế (ví dụ: "heading-large" = Inter 32px/700/1.2)
- Quy tắc chữ đáp ứng màn hình (kích thước trên di động so với máy tính để bàn)

### 3. Khoảng cách & Bố cục (Spacing & Layout)
- Thang khoảng cách (mọi giá trị margin/padding/gap được sử dụng)
- Chiều rộng và chiều rộng tối đa của khung chứa (container widths & max-widths)
- Hệ thống lưới (số cột, khoảng cách rãnh giữa các cột, điểm ngắt màn hình)
- Định nghĩa các điểm ngắt (breakpoints)
- Các lớp chiều sâu Z-index và mục đích sử dụng của chúng
- Các giá trị bo góc (border radius)

### 4. Kiểm kê Thành phần Giao diện (Components Inventory)
Đối với mỗi thành phần tái sử dụng được tìm thấy:
- Tên thành phần và đường dẫn tệp
- Giao diện thuộc tính (Props interface - kiểu dữ liệu TypeScript nếu có)
- Các biến thể hiển thị trực quan (kích thước, màu sắc, trạng thái)
- Các token khoảng cách và kích thước nội bộ được sử dụng
- Sự phụ thuộc vào các thành phần giao diện khác
- Số lần được sử dụng trên toàn bộ cơ sở mã nguồn (ước tính)

### 5. Chuyển động & Hoạt ảnh (Motion & Animation)
- Thời lượng chuyển cảnh (transition durations) và hàm điều chỉnh nhịp độ (timing functions)
- Các khung hình chính của hoạt ảnh (animation keyframes)
- Hiệu ứng chuyển tiếp ở các trạng thái di chuột/tiêu điểm/nhấn giữ (hover/focus/active)
- Các mẫu chuyển trang (page transition patterns)
- Hoạt ảnh theo thao tác cuộn trang (nếu có sử dụng thư viện như Framer Motion, GSAP)

### 6. Hệ thống Biểu tượng & Tài nguyên (Iconography & Assets)
- Hệ thống biểu tượng (Lucide, Heroicons, SVG tùy chỉnh, v.v.)
- Các kích thước biểu tượng được sử dụng
- Các biến thể của favicon và logo

### 7. Báo cáo Các điểm Thiếu nhất quán (Inconsistencies Report)
- Các giá trị trùng lặp lẽ ra phải được đặt thành token (ví dụ: mã `#1a1a1a` được dùng tới 47 lần nhưng không được khai báo làm biến)
- Các mẫu thiết kế xung đột nhau (ví dụ: một số nút bấm dùng padding để tạo kích thước, số khác lại gán chiều cao cố định)
- Thiếu trạng thái tương tác (các thành phần không có trạng thái hover/focus/disabled)
- Khoảng trống về khả năng tiếp cận (thiếu vòng sáng tiêu điểm focus ring, độ tương phản màu sắc không đạt chuẩn)

## Định dạng Đầu ra

Trả về một đối tượng JSON duy nhất theo cấu trúc sau:
{
  "colors": { "primary": [], "secondary": [], ... },
  "typography": { "families": [], "scale": [], "styles": [] },
  "spacing": { "scale": [], "containers": [], "breakpoints": [] },
  "components": [ { "name": "", "path": "", "props": {}, "variants": [] } ],
  "motion": { "durations": [], "easings": [], "animations": [] },
  "icons": { "system": "", "sizes": [], "count": 0 },
  "inconsistencies": [ { "type": "", "description": "", "severity": "high|medium|low" } ]
}

ĐỪNG cố gắng sắp xếp lại hay cải tiến bất cứ thứ gì ở bước này.
ĐỪNG đề xuất tên token hay cách tái cấu trúc.
Chỉ trích xuất chính xác những gì đang tồn tại, giữ nguyên hiện trạng của chúng.

Bạn là một kiến trúc sư hệ thống thiết kế (design systems architect). Tôi đang cung cấp cho bạn một tệp JSON kiểm toán thiết kế thô được trích xuất từ một cơ sở mã nguồn hiện có. Công việc của bạn là biến sự hỗn loạn này thành một kiến trúc token có cấu trúc chặt chẽ.

## Đầu vào
[Dán kết quả đầu ra JSON của Giai đoạn 1 vào đây, hoặc tham chiếu tới tệp]

## Phân cấp Token (Token Hierarchy)

Hãy thiết kế một hệ thống token 3 tầng:

### Tầng 1 — Token Nguyên thủy (Primitive Tokens - các giá trị thô)
Các giá trị được đặt tên và bất biến. Không mang ý nghĩa ngữ cảnh sử dụng.
- Màu sắc: `color-gray-100`, `color-blue-500`
- Khoảng cách: `space-1` đến `space-N`
- Kích thước phông chữ: `font-size-xs` đến `font-size-4xl`
- Độ bo góc: `radius-sm`, `radius-md`, `radius-lg`

### Tầng 2 — Token Ngữ nghĩa (Semantic Tokens - ý nghĩa theo ngữ cảnh)
Ánh xạ các token nguyên thủy vào mục đích sử dụng. Các giá trị này sẽ thay đổi khi chuyển đổi giữa các giao diện chủ đề (themes).
- `color-text-primary` → `color-gray-900`
- `color-bg-surface` → `color-white`
- `color-border-default` → `color-gray-200`
- `spacing-section` → `space-16`
- `font-heading` → `font-size-2xl` + `font-weight-bold` + `line-height-tight`

### Tầng 3 — Token Thành phần (Component Tokens - giới hạn phạm vi trong từng thành phần)
- `button-padding-x` → `spacing-4`
- `button-bg-primary` → `color-brand-500`
- `card-radius` → `radius-lg`
- `input-border-color` → `color-border-default`

## Quy tắc Hợp nhất (Consolidation Rules)
1. Gộp các giá trị chênh lệch nhau trong phạm vi 2px (ví dụ: 14px và 15px → chọn một giá trị, ghi chú rõ đã chọn giá trị nào)
2. Thiết lập một thang đo khoảng cách nhất quán (khuyến nghị lấy bội số cơ sở 4px, gắn cờ các giá trị lệch chuẩn)
3. Thu gọn bảng màu xuống mức ≤60 token tổng cộng (gắn cờ những màu cần ngừng sử dụng)
4. Chuẩn hóa thang đo kích thước phông chữ theo một cấp số tiến hợp lý
5. Tạo các mẫu cài đặt sẵn (presets) cho hoạt ảnh có đặt tên rõ ràng từ các giá trị dùng lẻ tẻ một lần

## Định dạng Đầu ra

Cung cấp:
1. **Bản đồ token hoàn chỉnh** ở định dạng JSON — đầy đủ cả ba tầng kèm theo các tham chiếu
2. **Bảng chuyển đổi (Migration table)** — giá trị hiện tại → tên token mới → những tệp nào đang sử dụng nó
3. **Danh sách ngừng sử dụng (Deprecation list)** — các giá trị cần loại bỏ kèm theo gợi ý thay thế
4. **Nhật ký quyết định (Decision log)** — mọi phán đoán bạn đã đưa ra (tại sao bạn lại gộp X vào Y, v.v.)

Đối với mỗi quyết định, hãy giải thích rõ sự đánh đổi. Tôi có thể không đồng tình với một số lựa chọn hợp nhất
của bạn, vì vậy sự minh bạch quan trọng hơn việc tỏ ra tự tin tuyệt đối.

Bạn là một chuyên gia lập tài liệu hệ thống thiết kế đang xây dựng bản đặc tả thành phần
cho tệp CLAUDE.md. Tài liệu này sẽ được các trợ lý lập trình AI
(Claude, Cursor, Copilot) sử dụng để tạo ra mã nguồn giao diện (UI) nhất quán.

## Ngữ cảnh
- **Hệ thống token:** [Dán hoặc tham chiếu đầu ra của Giai đoạn 2]
- **Thành phần cần lập tài liệu:** [Tên thành phần, hoặc "tất cả các thành phần trong danh mục kiểm kê"]
- **Framework:** [Next.js + React + Tailwind / v.v.]

## Đối với Mỗi Thành phần, Hãy Lập Tài liệu Gồm:

### 1. Tổng quan (Overview)
- Tên thành phần (viết theo chuẩn PascalCase)
- Mô tả ngắn gọn trong một dòng
- Danh mục (Điều hướng - Navigation / Nhập liệu - Input / Phản hồi - Feedback / Bố cục - Layout / Hiển thị Dữ liệu - Data Display)

### 2. Giải phẫu Cấu trúc (Anatomy)
- Liệt kê mọi bộ phận thị giác cấu thành (ví dụ: Button = khung chứa container + nhãn label + biểu tượng trái icon-left + biểu tượng phải icon-right)
- Bộ phận nào là tùy chọn (optional) so với bắt buộc (required)
- Quy tắc lồng ghép (những gì có thể / không thể đặt bên trong thành phần này)

### 3. Đặc tả Thuộc tính (Props Specification)
Đối với mỗi prop:
- Tên, kiểu dữ liệu, giá trị mặc định, bắt buộc/tùy chọn
- Các giá trị được phép nhận (nếu là kiểu liệt kê enum)
- Mô tả ngắn gọn về yếu tố thị giác mà nó điều khiển
- Ví dụ cách sử dụng

### 4. Các Biến thể Thị giác (Visual Variants)
- Các biến thể kích thước kèm theo giá trị token chính xác (padding, font-size, height)
- Các biến thể màu sắc kèm theo tham chiếu token chính xác
- Các biến thể trạng thái: default, hover, active, focus, disabled, loading, error
- Đối với MỖI trạng thái: chỉ rõ những token nào thay đổi và thay đổi sang giá trị nào

### 5. Sơ đồ Tiêu thụ Token (Token Consumption Map)
Component: Button
├── background → button-bg-variant → color-brand-shade
├── text-color → button-text-variant → color-white
├── padding-x → button-padding-x-size → spacing-{n}
├── padding-y → button-padding-y-size → spacing-{n}
├── border-radius → button-radius → radius-md
├── font-size → button-font-size → font-size-{n}
├── font-weight → button-font-weight → font-weight-semibold
└── transition → motion-duration-fast + motion-ease-default

### 6. Nguyên tắc Sử dụng (Usage Guidelines)
- Khi nào nên sử dụng (và khi nào KHÔNG nên sử dụng — gợi ý các thành phần thay thế)
- Số lượng bản thể (instances) tối đa trên mỗi khung nhìn viewport (ví dụ: "chỉ dùng duy nhất 1 nút CTA chính cho mỗi phần")
- Nguyên tắc nội dung (độ dài nhãn, quy tắc viết hoa, cách sử dụng biểu tượng)

### 7. Khả năng Tiếp cận (Accessibility)
- Các thuộc tính ARIA bắt buộc
- Mẫu tương tác bằng bàn phím
- Quy tắc quản lý tiêu điểm (focus management)
- Hành vi với trình đọc màn hình (screen reader)
- Tỷ lệ tương phản tối thiểu đạt được bởi các token mặc định

### 8. Ví dụ Mã nguồn (Code Example)
Cung cấp một ví dụ mã nguồn sẵn sàng để sao chép-dán, sử dụng đúng các mẫu
thực tế trong cơ sở mã nguồn (đường dẫn import, quy ước viết className, v.v.)

## Định dạng Đầu ra

Định dạng Markdown, được chia cấu trúc bằng các tiêu đề cho từng phần. Nội dung này sẽ được chèn
trực tiếp vào tệp CLAUDE.md.

Bạn đang biên soạn tệp tham chiếu hệ thống thiết kế CLAUDE.md hoàn chỉnh cuối cùng.
Tệp này sẽ nằm ở thư mục gốc của dự án và đóng vai trò là nguồn chân lý duy nhất (single source of
truth) cho bất kỳ trợ lý AI (hoặc lập trình viên con người) nào làm việc trên cơ sở mã nguồn này.

## Đầu vào
- **Kiến trúc token:** [Đầu ra Giai đoạn 2]
- **Tài liệu thành phần:** [Đầu ra Giai đoạn 3]
- **Siêu dữ liệu dự án (Project metadata):**
  - Tên dự án: name
  - Ngăn xếp công nghệ: [Next.js 14+ / React 18+ / Tailwind 3.x / v.v.]
  - Phiên bản Node: version
  - Trình quản lý gói: [npm / pnpm / yarn]

## Cấu trúc Tệp CLAUDE.md

Hãy biên soạn tệp cuối cùng với các phần sau đây THEO ĐÚNG THỨ TỰ NÀY:

### 1. Bản sắc Dự án (Project Identity)
- Tên dự án, mô tả, định vị sản phẩm
- Tóm tắt ngăn xếp công nghệ (một bảng duy nhất)
- Tổng quan cấu trúc thư mục (bố cục thư mục src/)

### 2. Thẻ Tham khảo Nhanh (Quick Reference Card)
Một bảng tra cứu cô đọng — những thông tin cần dùng thường xuyên nhất chỉ trong một cái nhìn lướt qua:
- Các màu chủ đạo kèm mã hex (tối đa 6 màu)
- Ngăn xếp phông chữ (Font stack)
- Thang đo khoảng cách (biểu diễn trực quan: 4, 8, 12, 16, 24, 32, 48, 64)
- Các điểm ngắt màn hình (Breakpoints)
- Các giá trị bo góc (Border radius)
- Các giá trị đổ bóng (Shadow)
- Bản đồ phân lớp Z-index

### 3. Design Tokens — Tài liệu Tham chiếu Đầy đủ
Được tổ chức theo phân tầng (Nguyên thủy - Primitive → Ngữ nghĩa - Semantic → Thành phần - Component).
Mỗi mục token bao gồm: tên, giá trị, biến CSS, lớp Tailwind tương đương.
Sử dụng bảng biểu để dễ dàng đọc lướt.

### 4. Hệ thống Kiểu chữ (Typography System)
- Bảng thang đo kiểu chữ (tên, kích thước, độ đậm, chiều cao dòng, khoảng cách chữ, ngữ cảnh sử dụng)
- Các quy tắc hiển thị đáp ứng (responsive)
- Chiến lược tải phông chữ

### 5. Hệ thống Màu sắc (Color System)
- Bảng màu đầy đủ kèm mô tả mẫu màu (tên, mã hex, ngữ cảnh sử dụng)
- Bảng ánh xạ màu sắc ngữ nghĩa
- Ánh xạ chế độ tối (Dark mode - nếu có áp dụng)
- Ghi chú tuân thủ tỷ lệ tương phản

### 6. Hệ thống Bố cục (Layout System)
- Đặc tả hệ thống lưới (Grid)
- Chiều rộng khung chứa (Container widths)
- Hệ thống khoảng cách kèm thang đo trực quan
- Hành vi tại các điểm ngắt (breakpoints)

### 7. Thư viện Thành phần (Component Library)
[Chèn đầu ra của Giai đoạn 3 cho từng thành phần vào đây]

### 8. Chuyển động & Hoạt ảnh (Motion & Animation)
- Bảng các mẫu cài đặt sẵn có đặt tên (tên, thời lượng, hàm gia tốc easing, cách sử dụng)
- Quy tắc: khi nào nên tạo hiệu ứng chuyển động, khi nào không nên
- Các ràng buộc về hiệu năng

### 9. Quy ước Lập trình (Coding Conventions)
- Các mẫu đặt tên tệp
- Thứ tự khai báo import
- Mẫu cấu trúc tệp thành phần (Component file structure template)
- Quy ước sắp xếp thứ tự lớp CSS (nếu dùng Tailwind)
- Các mẫu quản lý trạng thái (state management) được sử dụng

### 10. Quy tắc & Ràng buộc (Rules & Constraints)
Những quy tắc cứng không bao giờ được phép vi phạm:
- "Không bao giờ sử dụng mã màu hex nội dòng — luôn phải tham chiếu qua token"
- "Tất cả các phần tử tương tác phải có trạng thái focus hiển thị rõ ràng"
- "Vùng chạm cảm ứng tối thiểu: 44x44px"
- "Tất cả hình ảnh đều phải có văn bản thay thế (alt text)"
- "Không sử dụng các giá trị z-index nằm ngoài thang đo đã định nghĩa"
- [Thêm các quy tắc đặc thù của dự án]

## Yêu cầu Định dạng
- Sử dụng bảng markdown cho tất cả các ánh xạ token/giá trị
- Sử dụng khối mã (code blocks) cho tất cả các ví dụ mã nguồn
- Giữ cho mỗi phần có tính độc lập khép kín (có thể đọc hiểu trọn vẹn mà không cần cuộn sang các phần khác)
- Bao gồm mục lục ở đầu tệp kèm theo các liên kết neo (anchor links)
- Độ dài dòng tối đa: 100 ký tự để đảm bảo tính dễ đọc
- Ưu tiên ghi lại các giá trị tường minh thay vì viết tham chiếu kiểu "xem ở trên"

## Quy tắc Cốt tử
Tệp này phải mang tính CHUẨN MỰC CHÍNH THỐNG (AUTHORITATIVE). Nếu có sự mâu thuẫn hay mơ hồ giữa
tệp CLAUDE.md và mã nguồn thực tế, tệp CLAUDE.md phải được cập nhật để
khớp với thực tế — không bao giờ làm ngược lại. Tài liệu này ghi chép lại những gì ĐANG TỒN TẠI,
chứ không phải những gì LẼ RA NÊN CÓ (đó là câu chuyện của một lộ trình phát triển riêng).

Bạn là một kiểm toán viên hệ thống thiết kế (design system auditor) đang thực hiện kiểm tra đồng bộ hóa.

Hãy đối chiếu tài liệu hệ thống thiết kế CLAUDE.md hiện tại với
cơ sở mã nguồn thực tế và tạo một báo cáo độ lệch (drift report).

## Đầu vào
- **CLAUDE.md:** paste_or_reference_file
- **Mã nguồn hiện tại:** path_or_uploaded_files

## Kiểm tra Các Vấn đề Sau:

1. **Các token mới chưa có trong tài liệu**
   - Các giá trị màu sắc xuất hiện trong mã nguồn nhưng không có trong CLAUDE.md
   - Các giá trị khoảng cách (spacing) được sử dụng nhưng chưa được định nghĩa
   - Các kích thước hoặc độ đậm phông chữ (font weights) mới

2. **Các token đã ngừng sử dụng (deprecated) nhưng vẫn còn trong mã nguồn**
   - Các token đã được ghi nhận trong tài liệu là ngừng sử dụng nhưng vẫn đang được dùng
   - Số lượng vị trí còn đang sử dụng đối với từng token đã ngừng hỗ trợ

3. **Các thành phần (components) mới chưa được ghi tài liệu**
   - Các thành phần được tạo sau lần cập nhật CLAUDE.md gần nhất
   - Bị thiếu trong phần thư viện thành phần

4. **Các thành phần đã bị sửa đổi**
   - Các thuộc tính props đã thay đổi (thêm mới/xóa bỏ/đổi tên)
   - Các biến thể (variants) mới chưa được ghi vào tài liệu
   - Các thay đổi về mặt thị giác (sử dụng các token khác với trước đây)

5. **Các tham chiếu bị hỏng (Broken references)**
   - CLAUDE.md tham chiếu tới các token không còn tồn tại nữa
   - Các đường dẫn tệp đã thay đổi
   - Các đường dẫn nhập (import paths) đã lỗi thời

6. **Vi phạm quy ước (Convention violations)**
   - Đoạn mã vi phạm các quy tắc trong CLAUDE.md (dùng màu gắn cứng nội dòng, thiếu trạng thái focus, v.v.)
   - Số lượng và vị trí cụ thể của từng loại vi phạm

## Đầu ra
Một báo cáo định dạng markdown bao gồm:
- **Thống kê tóm tắt:** X token mới, Y token đã ngừng sử dụng, Z thành phần đã bị sửa đổi
- **Các hạng mục cần hành động** được sắp xếp ưu tiên theo mức độ nghiêm trọng (gây lỗi nghiêm trọng → thiếu nhất quán → hình thức bề ngoài)
- **Các phần CLAUDE.md đã được cập nhật** sẵn sàng để sao chép-dán (chỉ bao gồm những phần có thay đổi)

Bạn đang cập nhật một tệp tài liệu FORME.md hiện có để phản ánh
những thay đổi trong cơ sở mã nguồn (codebase) kể từ lần viết gần nhất.

## Đầu vào
- **Tệp FORGME.md hiện tại:** paste_or_reference_file
- **Mã nguồn đã cập nhật:** upload_files_or_provide_path
- **Các thay đổi đã biết (nếu có):** [ví dụ: "Chúng tôi đã thêm tích hợp Stripe và chuyển từ REST sang tRPC" — hoặc "Tôi không rõ những gì đã thay đổi, hãy tự tìm hiểu giúp tôi"]

## Nhiệm vụ của Bạn

1. **Phân tích Khác biệt (Diff Analysis):** Đối chiếu tài liệu với mã nguồn hiện tại.
   Xác định những gì mới thêm vào, những gì đã thay đổi và những gì đã bị gỡ bỏ.

2. **Đánh giá Tác động (Impact Assessment):** Đối với mỗi thay đổi, hãy xác định:
   - Những phần nào trong FORME.md bị ảnh hưởng
   - Thay đổi đó chỉ mang tính hình thức bề ngoài (đổi tên tệp) hay mang tính cấu trúc (luồng dữ liệu mới)
   - Các phép ẩn dụ hiện có còn đúng không hay cần được cập nhật lại

3. **Tạo Nội dung Cập nhật:** Đối với mỗi phần bị ảnh hưởng:
   - Viết đoạn văn bản THAY THẾ (không viết lại toàn bộ tài liệu, chỉ viết những phần có thay đổi)
   - Đánh dấu rõ ràng: section_name → [REPLACE FROM "..." TO "..."]
   - Duy trì cùng giọng điệu, hệ thống ẩn dụ và phong cách như bản gốc

4. **Các Phần Bổ sung Mới:** Nếu có các hệ thống/tính năng hoàn toàn mới:
   - Viết các tiểu mục mới tuân theo cùng cấu trúc và giọng văn
   - Tích hợp chúng vào đúng vị trí trong tài liệu
   - Cập nhật phần Bức tranh Toàn cảnh (Big Picture) nếu mô tả tổng thể về hệ thống có sự thay đổi

5. **Mục Nhật ký Thay đổi (Changelog Entry):** Thêm một dòng ghi chú có ghi ngày tháng ở ngay đầu tài liệu:
   "### Đã cập nhật date — [tóm tắt dài một dòng về những gì đã thay đổi]"

## Quy tắc
- KHÔNG viết lại các phần không có sự thay đổi
- KHÔNG phá vỡ các phép ẩn dụ hiện có trừ khi hệ thống bên dưới đã thực sự thay đổi
- Nếu một công nghệ bị thay thế, hãy cập nhật phép ẩn dụ "đội ngũ nhân sự" ("crew") (hoặc tương đương)
- Giữ nguyên giọng văn — nếu bản gốc mang phong cách thân mật đời thường, hãy tiếp tục viết thân mật đời thường
- Gắn cờ bất kỳ điều gì bạn không chắc chắn: "Tôi nhận thấy [X] nhưng không thể xác định rõ liệu [Y]"

Bạn là một chuyên gia viết tài liệu kỹ thuật (technical writer) cấp cao chuyên làm cho các hệ thống phức tạp
trở nên dễ hiểu đối với những người không phải là kỹ sư. Bạn có năng khiếu sử dụng phép tương tự (analogy), lối kể chuyện và
biến các sơ đồ kiến trúc khô khan thành những câu chuyện sinh động.

Tôi cần bạn phân tích dự án này và viết một tệp tài liệu toàn diện
có tên là `FORME.md` giải thích mọi thứ về dự án này bằng
ngôn ngữ đời thường dễ hiểu.

## Ngữ cảnh Dự án
- **Tên dự án:** name
- **Dự án làm gì (trong một câu):** [ví dụ: "Một nền tảng SaaS giúp các nhà hàng tự quản lý việc đặt món trực tuyến của riêng họ mà không phải trả hoa hồng cho các bên trung gian"]
- **Vai trò của tôi:** [ví dụ: "Tôi là nhà sáng lập / chủ sở hữu sản phẩm / nhà thiết kế — tôi không viết mã nhưng tôi đưa ra mọi quyết định về sản phẩm và kiến trúc"]
- **Ngăn xếp công nghệ (nếu bạn biết):** [ví dụ: "Next.js, Supabase, Tailwind" hoặc "Tôi không chắc lắm, hãy tự tìm hiểu từ mã nguồn nhé"]
- **Giai đoạn:** [MVP / v1 đang chạy thực tế / đang mở rộng quy mô / tái cấu trúc hệ thống cũ]

## Cơ sở Mã nguồn (Codebase)
[Tải các tệp lên, cung cấp đường dẫn hoặc dán các tệp quan trọng vào đây]

## Cấu trúc Tài liệu

Hãy viết tệp FORME.md với các phần sau đây, theo đúng thứ tự này:

### 1. Bức tranh Toàn cảnh (Tổng quan Dự án)
Bắt đầu bằng một bản tóm tắt điều hành dài 3-4 câu mà bất kỳ ai cũng có thể hiểu được.
Sau đó cung cấp:
- Dự án này giải quyết vấn đề gì và cho ai
- Cách người dùng tương tác với nó (hành trình người dùng bằng ngôn từ giản dị)
- Một phép ẩn dụ kiểu "nếu hệ thống này là một nhà hàng" (hoặc tương tự) cho toàn bộ hệ thống

### 2. Kiến trúc Kỹ thuật — Bản Thiết kế Tổng thể
Giải thích cách hệ thống được thiết kế và TẠI SAO những lựa chọn đó lại được đưa ra.
- Vẽ sơ đồ kiến trúc bằng sơ đồ văn bản đơn giản (các khung hộp và mũi tên)
- Giải thích từng lớp / dịch vụ chính như thể bạn đang dẫn khách đi tham quan một tòa nhà:
  "Đây là khu bếp (lớp API) — mọi công việc chế biến thực sự đều diễn ra ở đây.
  Đơn đặt hàng được chuyển vào từ quầy lễ tân (frontend), được xử lý tại đây,
  và kết quả được lưu vào tủ hồ sơ (cơ sở dữ liệu)."
- Đối với mọi quyết định kiến trúc, hãy trả lời câu hỏi: "Tại sao lại chọn cái này mà không phải là phương án thay thế hiển nhiên kia?"
- Làm nổi bật bất kỳ lựa chọn thông minh hoặc khác thường nào mà nhà phát triển đã thực hiện

### 3. Cấu trúc Mã nguồn — Hệ thống Tủ Hồ sơ
Lập bản đồ tổ chức tệp và thư mục của dự án.
- Hiển thị cây thư mục (2-3 cấp độ cao nhất)
- Đối với mỗi thư mục chính, hãy giải thích:
  - Những gì nằm ở đây (bằng ngôn từ dễ hiểu)
  - Khi nào một người sẽ cần mở thư mục này ra
  - Mối liên hệ của nó với các thư mục khác
- Gắn cờ lưu ý bất kỳ quy ước đặt tên nào không hiển nhiên
- Xác định các "điểm khởi đầu" ("entry points") — những tệp nơi mọi thứ bắt đầu chạy

### 4. Kết nối & Luồng Dữ liệu — Cách Mọi thứ Trò chuyện Với Nhau
Truy vết cách dữ liệu di chuyển xuyên suốt hệ thống.
- Chọn 2-3 hành động cốt lõi của người dùng (ví dụ: "người dùng đăng ký", "người dùng đặt hàng")
- Đối với mỗi hành động, hãy dẫn dắt qua TOÀN BỘ hành trình từng bước một:
  "Khi người dùng nhấp vào nút 'Đặt hàng' ('Place Order'), đây là những gì diễn ra ở hậu trường:
  1. Nút bấm kích hoạt một hàm trong [file] — hãy hình dung nó giống như việc bấm chuông gọi món
  2. Tiếng chuông đó truyền tới api_route — nhà bếp nghe thấy đơn hàng
  3. Nhà bếp kiểm tra với [database] — chúng ta còn đủ nguyên liệu không?
  4. Nếu có, nó gửi trả lại một xác nhận — người phục vụ mang hóa đơn ra cho khách"
- Giải thích các kết nối dịch vụ bên ngoài (thanh toán, email, các API) và chuyện gì sẽ xảy ra nếu chúng gặp sự cố
- Mô tả luồng xác thực (làm sao ứng dụng biết bạn là ai?)

### 5. Lựa chọn Công nghệ — Hộp Đồ nghề
Đối với mỗi công nghệ / thư viện / dịch vụ quan trọng được sử dụng:
- Nó là gì (một câu, không dùng biệt ngữ chuyên môn)
- Nó đảm nhận công việc cụ thể gì trong dự án này
- Tại sao nó được chọn thay vì các phương án khác (hãy cụ thể: "Chúng ta sử dụng Supabase thay vì Firebase bởi vì...")
- Bất kỳ hạn chế hoặc sự đánh đổi nào mà bạn cần biết
- Hệ quả về chi phí (có gói miễn phí không? trả phí cố định? hay tính theo mức sử dụng?)

Định dạng thành một bảng:
| Công nghệ | Vai trò Tại đây | Tại sao Chọn Nó | Điểm Cần Lưu ý |
|-----------|------------------|-------------|---------------|

### 6. Môi trường & Cấu hình
Giải thích cách thiết lập mà không giả định người đọc đã có kiến thức kỹ thuật:
- Những biến môi trường (environment variables) nào đang tồn tại và mỗi biến điều khiển cái gì (bằng ngôn ngữ đời thường)
- Cách các môi trường khác nhau hoạt động (phát triển - development so với thử nghiệm - staging so với thực tế - production)
- "Nếu bạn cần thay đổi [X], bạn sẽ cập nhật tại [Y] — nhưng hãy cẩn thận vì [Z]"
- Bất kỳ mã bí mật / khóa (secrets/keys) nào và chúng kết nối tới dịch vụ nào (KHÔNG ghi giá trị thực tế của khóa ra)

### 7. Bài học Kinh nghiệm — Những Câu chuyện Chiến trường
Đây là phần giá trị nhất. Hãy ghi chép lại:

**Lỗi & Cách Khắc phục (Bugs & Fixes):**
- Các lỗi lớn đã gặp phải trong quá trình phát triển
- Nguyên nhân gây ra chúng (giải thích đơn giản)
- Cách chúng đã được sửa
- Cách tránh các vấn đề tương tự trong tương lai

**Cạm bẫy & Bãi mìn (Pitfalls & Landmines):**
- Những thứ nhìn bề ngoài có vẻ đơn giản nhưng thực chất lại cực kỳ phức tạp
- "Nếu có lúc nào đó bạn cần thay đổi [X], hãy hết sức cẩn thận vì nó cũng làm ảnh hưởng tới [Y] và [Z]"
- Nợ kỹ thuật (technical debt) đã biết và lý do tại sao nó tồn tại

**Những Khám phá (Discoveries):**
- Các công nghệ hoặc kỹ thuật mới đã được tìm hiểu
- Những gì hoạt động hiệu quả và những gì không
- "Nếu được làm lại từ đầu, tôi sẽ..."

**Đúc kết Kỹ thuật (Engineering Wisdom):**
- Các phương pháp thực hành tốt nhất đúc kết được từ dự án này
- Các mẫu thiết kế (patterns) đã chứng minh được độ tin cậy
- Cách các kỹ sư giàu kinh nghiệm tư duy về những vấn đề này

### 8. Thẻ Tham khảo Nhanh (Quick Reference Card)
Một bảng tra cứu tóm tắt ở cuối tài liệu:
- Cách chạy dự án trên máy cục bộ (từng bước một, giả định máy chưa cài đặt gì)
- Các URL quan trọng (production, staging, trang quản trị admin, bảng điều khiển)
- Cần tìm ai / ở đâu khi có thứ gì đó bị hỏng
- Các câu lệnh thường dùng nhất

## Quy tắc Viết — KHÔNG THỂ THƯƠNG LƯỢNG

1. **Không dùng biệt ngữ mà không giải thích.** Mọi thuật ngữ kỹ thuật đều phải đi kèm ngay một
   lời giải thích bằng ngôn ngữ đời thường hoặc một phép ẩn dụ trong lần đầu tiên xuất hiện. Bạn có thể sử dụng
   thuật ngữ kỹ thuật đó ở các đoạn sau, nhưng người đọc phải hiểu được nó trước đã.

2. **Tích cực sử dụng phép ẩn dụ.** Hãy so sánh các hệ thống với nhà hàng,
   bưu điện, thư viện, nhà máy, dàn nhạc giao hưởng — bất cứ thứ gì giúp
   khái niệm trở nên dễ hiểu ngay lập tức. Phép ẩn dụ phải NHẤT QUÁN trong phạm vi một phần
   (đừng đang ví von với nhà hàng lại nhảy sang bệnh viện ở giữa chừng lời giải thích).

3. **Kể câu chuyện TẠI SAO.** Đừng chỉ ghi chép lại những gì đang tồn tại.
   Hãy giải thích tại sao các quyết định lại được đưa ra, những phương án thay thế nào đã được cân nhắc,
   và những sự đánh đổi nào đã được chấp nhận. "Chúng ta chọn đi theo hướng X bởi vì Y,
   mặc dù điều đó có nghĩa là sau này chúng ta sẽ khó làm Z một cách dễ dàng."

4. **Viết thật cuốn hút.** Sử dụng giọng văn trò chuyện tự nhiên, các câu hỏi tu từ,
   chút hài hước nhẹ nhàng ở những chỗ phù hợp. Tài liệu này phải là thứ mà
   người ta thực sự MUỐN đọc, chứ không phải thứ họ bị ép phải đọc.
   Nếu một phần nào đó terdengar nhàm chán, hãy viết lại cho đến khi nó hết chán.

5. **Trung thực về các vấn đề.** Hãy gắn cờ chỉ rõ các khoản nợ kỹ thuật, các sự cố đã biết,
   và những quyết định kiểu "chúng ta làm thế này vì áp lực thời gian". Tài liệu này
   sẽ hữu ích hơn nhiều khi nó chân thực thay vì cố tỏ ra bóng bẩy hoàn hảo.

6. **Bao gồm mục "chuyện gì có thể trục trặc" cho mọi hệ thống chính.**
   Không phải để hù dọa, mà là để chuẩn bị sẵn sàng. "Nếu dịch vụ thanh toán bị sập,
   đây là những gì sẽ xảy ra và đây là những gì cần làm."

7. **Sử dụng kỹ thuật hé lộ thông tin tăng dần (progressive disclosure).** Bắt đầu mỗi phần bằng
   phiên bản đơn giản trước, sau đó mới đi sâu hơn. Người đọc có thể dừng lại
   ở bất kỳ điểm nào mà vẫn nắm được một lượng kiến thức hữu ích.

8. **Định dạng để dễ đọc lướt (scannability).** Sử dụng các tiêu đề, in đậm các thuật ngữ quan trọng, chia đoạn văn
   ngắn và dùng gạch đầu dòng cho các danh sách. Nhưng hãy viết bằng văn xuôi (không dùng gạch đầu dòng)
   đối với các phần giải thích và dẫn chuyện.

## Ví dụ về Giọng văn

SAI — khô khan và nặng nề biệt ngữ:
"Ứng dụng triển khai kết xuất phía máy chủ (server-side rendering) với cơ chế tái tạo tĩnh
tăng dần (incremental static regeneration), tận dụng Next.js App Router cùng React Server
Components để đạt chỉ số TTFB tối ưu."

ĐÚNG — rõ ràng và lôi cuốn:
"Khi có ai đó truy cập trang web của chúng ta, máy chủ sẽ dựng sẵn trang đó trước khi
gửi đi — giống như một nhà hàng chuẩn bị sẵn món ăn trước khi bạn bước vào quán
thay vì đợi bạn ngồi xuống rồi mới bắt đầu nấu từ đầu. Kỹ thuật này được gọi là
'kết xuất phía máy chủ' ('server-side rendering') và đó là lý do tại sao các trang web tải rất nhanh. Chúng ta sử dụng Next.js
App Router cho việc này, nó giống như hệ thống điều phối quy trình làm việc của nhà bếp giúp
quyết định món nào cần sơ chế trước và món nào sẽ nấu ngay khi có khách gọi."

SAI — liệt kê trống không thiếu ngữ cảnh:
"Các gói phụ thuộc: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"

ĐÚNG — giải thích như một đội ngũ nhân sự:
"Hãy hình dung ngăn xếp công nghệ (tech stack) của chúng ta như một đoàn làm phim, mỗi thành viên có một chuyên môn riêng:
- **React** là nhà thiết kế bối cảnh — nó dựng nên mọi thứ bạn nhìn thấy trên màn hình
- **Next.js** là quản lý sân khấu — nó điều phối thời điểm và cách thức mọi thứ xuất hiện
- **Tailwind** là bộ phận phục trang — nó phụ trách toàn bộ phần tạo kiểu hình ảnh
- **Supabase** là nhân viên lưu trữ hồ sơ — nó cất giữ và truy xuất toàn bộ dữ liệu của chúng ta
- **Stripe** là nhân viên thu ngân — nó xử lý mọi vấn đề liên quan đến tiền bạc một cách an toàn"

Bạn là một chuyên gia kiểm định chất lượng (QA specialist) cấp cao sở hữu đôi mắt tinh tường của một nhà thiết kế. Nhiệm vụ của bạn là tìm ra mọi sự sai lệch về mặt thị giác, lỗi tương tác và vấn đề hiển thị đáp ứng (responsive) trong bản triển khai này.

## Thông tin Đầu vào
- **URL trực tiếp hoặc bản dựng cục bộ:** [URL / hướng dẫn cách chạy ở máy cục bộ]
- **Tài liệu thiết kế đối chiếu:** [Đường liên kết Figma / hệ thống thiết kế (design system) / tệp CLAUDE.md / ảnh chụp màn hình]
- **Các trình duyệt mục tiêu:** [ví dụ: "Chrome, Safari, Firefox bản mới nhất + Safari iOS + Chrome Android"]
- **Các điểm ngắt màn hình (breakpoints) mục tiêu:** [ví dụ: "375px, 768px, 1024px, 1280px, 1440px, 1920px"]
- **Khu vực ưu tiên kiểm tra:** [tùy chọn — "đặc biệt kiểm tra kỹ luồng thanh toán và thanh điều hướng trên di động"]

## Danh mục Kiểm toán (Audit Checklist)

### 1. Kiểm tra Độ Chuẩn xác Thị giác (Visual Fidelity Check)
Đối với từng trang / từng phần, hãy xác minh:
- [ ] Khoảng cách (spacing) khớp chính xác với các token của hệ thống thiết kế (không chấp nhận kiểu "xêm xêm gần giống")
- [ ] Nghệ thuật chữ (Typography): đúng phông chữ, độ đậm (weight), kích thước, chiều cao dòng (line-height), màu sắc tại mọi điểm ngắt màn hình
- [ ] Màu sắc khớp tuyệt đối với các token thiết kế (kiểm tra bằng công cụ chấm màu color picker, không ước lượng bằng mắt thường)
- [ ] Giá trị bo góc (border radius) chuẩn xác
- [ ] Hiệu ứng đổ bóng (shadows) khớp đúng thông số thiết kế
- [ ] Kích thước và sự căn chỉnh của các biểu tượng (icons)
- [ ] Tỷ lệ khung hình và cách cắt cúp (cropping) hình ảnh
- [ ] Giá trị độ mờ đục (opacity) ở những nơi có sử dụng

### 2. Hành vi Đáp ứng Đa Màn hình (Responsive Behavior)
Tại mỗi điểm ngắt kích thước màn hình (breakpoint), hãy kiểm tra:
- [ ] Bố cục chuyển đổi chuẩn xác (không bị chồng chéo, không có phần tử bị rớt lẻ loi)
- [ ] Văn bản vẫn đọc được rõ ràng (không bị cắt cụt làm mất ý nghĩa)
- [ ] Vùng chạm cảm ứng (touch targets) đạt kích thước ≥ 44x44px trên thiết bị di động
- [ ] Không xuất hiện thanh cuộn ngang ngoài ý muốn
- [ ] Hình ảnh co giãn theo tỷ lệ hợp lý (không bị kéo giãn méo mó hoặc vỡ hạt)
- [ ] Thanh điều hướng chuyển đổi trạng thái đúng cách (nút menu hamburger, ngăn kéo trượt drawer, v.v.)
- [ ] Các hộp thoại (modals) và lớp phủ (overlays) hoạt động tốt ở mọi kích thước khung nhìn (viewport)
- [ ] Các bảng dữ liệu có chiến lược hiển thị rõ ràng trên di động (cuộn ngang, xếp chồng hoặc ẩn bớt cột phụ)

### 3. Chất lượng Tương tác (Interaction Quality)
- [ ] Có trạng thái di chuột (hover states) trên tất cả các phần tử tương tác
- [ ] Hiệu ứng chuyển tiếp khi di chuột diễn ra mượt mà (không bị giật cục tức thì)
- [ ] Trạng thái tiêu điểm (focus states) hiển thị rõ ràng trên mọi phần tử tương tác (khi điều hướng bằng bàn phím)
- [ ] Trạng thái đang nhấn giữ (active/pressed states) mang lại phản hồi thị giác rõ ràng
- [ ] Trạng thái vô hiệu hóa (disabled states) có sự phân biệt rõ về mặt thị giác và không thể nhấp vào được
- [ ] Trạng thái đang tải (loading states) xuất hiện đầy đủ trong các tác vụ bất đồng bộ
- [ ] Hiệu ứng hoạt ảnh (animations) chạy mượt mà (không bị khựng giật, không làm xô lệch bố cục)
- [ ] Hoạt ảnh theo thao tác cuộn trang (scroll animations) kích hoạt đúng vị trí
- [ ] Hiệu ứng chuyển trang (nếu có) diễn ra mượt mà

### 4. Các Trường hợp Biên về Nội dung (Content Edge Cases)
- [ ] Văn bản cực kỳ dài trong tiêu đề, nút bấm, nhãn (nó tự xuống dòng hợp lý hay cắt cụt bằng dấu ba chấm?)
- [ ] Văn bản cực kỳ ngắn (bố cục có bị sập hoặc co rúm lại không?)
- [ ] Trạng thái dự phòng khi không có ảnh (ảnh bị lỗi đường dẫn hoặc thiếu dữ liệu ảnh)
- [ ] Trạng thái trống (empty states) cho tất cả các danh sách / lưới / bảng biểu
- [ ] Chỉ có duy nhất 1 mục trong danh sách / lưới (bố cục nhìn vẫn cân đối và hợp lý chứ?)
- [ ] Có từ 100+ mục trở lên (hệ thống có phân trang hợp lý hay bị vỡ giao diện?)
- [ ] Các ký tự đặc biệt trong dữ liệu người dùng nhập vào (dấu tiếng Việt/ngoại ngữ, biểu tượng cảm xúc emoji, văn bản viết từ phải sang trái RTL)

### 5. Kiểm tra Nhanh Khả năng Tiếp cận (Accessibility Quick Check)
- [ ] Tất cả hình ảnh đều có thuộc tính alt text phù hợp
- [ ] Độ tương phản màu sắc đạt ≥ 4.5:1 đối với văn bản nội dung, ≥ 3:1 đối với văn bản cỡ lớn
- [ ] Các ô nhập liệu biểu mẫu đều có thẻ nhãn (labels) được liên kết rõ ràng (không chỉ dùng mỗi chữ gợi ý placeholder)
- [ ] Các thông báo lỗi được đọc lên rõ ràng cho trình đọc màn hình (screen readers)
- [ ] Thứ tự di chuyển phím Tab hợp lý (đi theo đúng trình tự thị giác trên màn hình)
- [ ] Cơ chế giữ tiêu điểm (focus trap) hoạt động đúng trong các hộp thoại modal (không bị bấm Tab lọt ra các phần tử phía dưới nền)
- [ ] Có đường liên kết "Bỏ qua điều hướng để đến thẳng nội dung chính (Skip-to-content)"
- [ ] Không có thông tin quan trọng nào chỉ được truyền tải độc nhất bằng màu sắc

### 6. Tác động Thị giác của Hiệu năng (Performance Visual Impact)
- [ ] Không xảy ra hiện tượng xô lệch bố cục trong quá trình tải trang (CLS)
- [ ] Hình ảnh được tải tiệm tiến mượt mà (hiệu ứng mờ dần rõ lên blur-up hoặc khung xương skeleton, thay vì đột ngột bật nảy ra)
- [ ] Phông chữ không gây ra hiện tượng FOUT/FOIT (chớp nháy chữ chưa định dạng hoặc tàng hình chữ khi đang tải)
- [ ] Nội dung trên màn hình đầu tiên (above-the-fold) hiển thị nhanh chóng
- [ ] Các hoạt ảnh không gây sụt giảm khung hình (frame drops) trên các thiết bị cấu hình tầm trung

## Định dạng Đầu ra

### Báo cáo Chi tiết các Vấn đề
| # | Trang | Vấn đề | Danh mục | Mức độ Nghiêm trọng | Trình duyệt/Thiết bị | Mô tả Ảnh chụp Màn hình | Đề xuất Cách sửa |
|---|------|-------|----------|----------|---------------|----------------------|----------------|
| 1 | ... | ... | Visual/Responsive/Interaction/A11y/Performance | Critical/High/Medium/Low | ... | ... | ... |

### Thống kê Tóm tắt
- Tổng số vấn đề phát hiện: X
- Nghiêm trọng (Critical): X | Cao (High): X | Trung bình (Medium): X | Thấp (Low): X
- Theo danh mục: Thị giác (Visual): X | Đáp ứng (Responsive): X | Tương tác (Interaction): X | Tiếp cận (A11y): X | Hiệu năng (Performance): X
- Top 5 vấn đề cần ưu tiên khắc phục trước tiên (có mức độ tác động lớn nhất)

### Định nghĩa Mức độ Nghiêm trọng
- **Critical (Nghiêm trọng):** Hỏng chức năng hoặc vỡ bố cục khiến người dùng không thể sử dụng được
- **High (Cao):** Vấn đề hiển thị rõ rệt làm ảnh hưởng trực tiếp đến trải nghiệm người dùng
- **Medium (Trung bình):** Có thể nhận thấy khi quan sát kỹ, nhưng không cản trở việc sử dụng bình thường
- **Low (Thấp):** Lỗi trau chuốt nhỏ, sửa thêm được thì càng hoàn thiện (nice-to-have)

Bạn là một chuyên gia tối ưu hóa hiệu năng web (web performance specialist). Hãy phân tích trang web này và đưa ra các khuyến nghị tối ưu hóa sao cho một nhà thiết kế có thể hiểu được rõ ràng và một lập trình viên có thể bắt tay vào triển khai ngay lập tức.

## Đầu vào
- **URL trang web:** url
- **Các vấn đề hiện đã biết:** [tùy chọn — "chạy chậm trên điện thoại", "hình ảnh quá nặng"]
- **Điểm số mục tiêu:** [tùy chọn — "LCP dưới 2.5s, CLS dưới 0.1"]
- **Nền tảng lưu trữ (Hosting):** [Vercel / Netlify / máy chủ tự quản lý / không rõ]

## Các Khu vực Phân tích

### 1. Đánh giá các Chỉ số Core Web Vitals
Đối với mỗi chỉ số, hãy giải thích:
- **Chỉ số này đo lường điều gì** (bằng ngôn ngữ đời thường dễ hiểu)
- **Điểm số hiện tại** (tốt / cần cải thiện / kém)
- **Nguyên nhân nào đang gây ra mức điểm đó**
- **Cách khắc phục** (các bước cụ thể, có thể thực hiện ngay)

Các chỉ số:
- LCP (Largest Contentful Paint) — "nội dung chính xuất hiện nhanh đến mức nào?"
- FID/INP (Interaction to Next Paint) — "trang web phản hồi lại các thao tác nhấp chuột nhanh ra sao?"
- CLS (Cumulative Layout Shift) — "các thành phần trên trang có bị nhảy lung tung trong lúc đang tải không?"

### 2. Tối ưu hóa Hình ảnh
- Liệt kê mọi hình ảnh có kích thước hoặc dung lượng lớn hơn mức cần thiết
- Đề xuất chuyển đổi định dạng ảnh (từ PNG sang WebP, từ ảnh chưa nén sang ảnh đã nén)
- Xác định những nơi còn thiếu triển khai hình ảnh đáp ứng đa màn hình (responsive images)
- Gắn cờ cảnh báo các hình ảnh nằm ngay phần đầu trang (above the fold) nhưng thiếu thuộc tính ưu tiên tải (priority hints)
- Đề xuất các hình ảnh phù hợp để áp dụng tải trễ (lazy loading)

### 3. Tối ưu hóa Phông chữ (Font Optimization)
- Dung lượng tệp phông chữ và chiến lược tải phông chữ
- Cơ hội rút gọn bộ ký tự (subsetting — liệu bạn có thực sự cần tới toàn bộ 800 ký tự glyphs không?)
- Chiến lược hiển thị phông chữ (`swap`, `optional`, `fallback`)
- Khuyến nghị giữa việc tự lưu trữ phông chữ (self-hosting) so với dùng CDN

### 4. Phân tích JavaScript
- Phân tích chi tiết dung lượng gói mã (bundle size — thành phần nào đang gây nặng?)
- Tỷ lệ phần trăm mã JavaScript không được sử dụng
- Các đoạn script chặn quá trình hiển thị trang (render-blocking scripts)
- Tác động từ các đoạn script của bên thứ ba

### 5. Phân tích CSS
- Tỷ lệ phần trăm CSS không được sử dụng
- Các tệp định dạng (stylesheets) chặn quá trình hiển thị
- Cơ hội tách riêng phần CSS quan trọng cần tải trước (Critical CSS extraction)

### 6. Bộ nhớ đệm & Phân phối Nội dung (Caching & Delivery)
- Các tiêu đề bộ nhớ đệm (cache headers) đã có mặt và cấu hình đúng chưa?
- Mức độ tận dụng mạng phân phối nội dung (CDN)
- Tính năng nén dữ liệu (gzip/brotli) đã được bật chưa?

## Định dạng Đầu ra

### Tóm tắt Nhanh (dành cho khách hàng / các bên liên quan)
3–4 câu ngắn gọn: hiện trạng, những vấn đề lớn nhất đang gặp phải và mức độ cải thiện dự kiến sau khi tối ưu.

### Lộ trình Tối ưu hóa (Optimization Roadmap)
| Thứ tự Ưu tiên | Vấn đề | Mức độ Tác động | Công sức Thực hiện | Cách Khắc phục |
|----------|-------|--------|--------|-----------|
| 1 | ... | Cao | Thấp | specific_steps |
| 2 | ... | ... | ... | ... |

### Mức Cải thiện Điểm số Dự kiến
| Chỉ số | Hiện tại | Sau khi Sửa Nhanh (Quick Wins) | Sau khi Tối ưu Toàn diện |
|--------|---------|-----------------|------------------------|
| Hiệu năng tổng thể (Performance) | ... | ... | ... |
| LCP | ... | ... | ... |
| CLS | ... | ... | ... |

### Các Đoạn Mã Triển khai Mẫu (Implementation Snippets)
Đối với 5 hạng mục sửa lỗi ưu tiên hàng đầu, hãy cung cấp sẵn các đoạn mã nguồn hoặc cấu hình có thể sao chép và dán để áp dụng ngay.

Bạn là một chuyên gia đánh giá mức độ sẵn sàng trước khi ra mắt sản phẩm (launch readiness specialist). Hãy tạo một danh mục kiểm tra trước khi ra mắt (pre-launch checklist) toàn diện được thiết kế riêng cho dự án cụ thể này.

## Bối cảnh Dự án
- **Dự án:** [tên, loại hình, mô tả]
- **Ngăn xếp công nghệ (Tech stack):** [framework, dịch vụ lưu trữ/hosting, các dịch vụ tích hợp]
- **Tính năng:** key_features_that_need_verification
- **Hình thức ra mắt:** [ra mắt thử nghiệm hẹp (soft launch) / ra mắt công khai (public launch) / bàn giao cho khách hàng (client handoff)]
- **Tên miền:** [DNS đã được cấu hình sẵn chưa?]

## Tạo Danh mục Kiểm tra Bao phủ các Mảng sau:

### Tính năng Hoạt động (Functionality)
- Tất cả các luồng người dùng quan trọng đều hoạt động trơn tru từ đầu đến cuối (end-to-end)
- Tất cả các biểu mẫu (forms) đều gửi dữ liệu chính xác và hiển thị thông báo phản hồi phù hợp
- Luồng thanh toán hoạt động tốt (nếu có) — kiểm thử bằng môi trường sandbox thực tế
- Xác thực người dùng hoạt động chuẩn xác (đăng nhập, đăng xuất, đặt lại mật khẩu, hết hạn phiên)
- Thông báo email được gửi đi chính xác (kiểm tra cả thư mục spam)
- Các tích hợp bên thứ ba phản hồi đúng kỳ vọng
- Cơ chế xử lý lỗi hoạt động tốt (điều gì xảy ra khi có sự cố phát sinh?)

### Nội dung & Câu chữ (Content & Copy)
- Không còn sót bất kỳ đoạn văn bản giả `lorem ipsum` nào
- Tất cả các đường liên kết đều hoạt động tốt (không có lỗi 404)
- Có đầy đủ các trang pháp lý (chính sách bảo mật, điều khoản dịch vụ, chấp thuận cookie)
- Thông tin liên hệ chính xác
- Năm bản quyền (copyright year) đã được cập nhật theo năm hiện tại
- Các đường liên kết mạng xã hội trỏ đúng đến trang hồ sơ chính thức
- Tất cả hình ảnh đều có văn bản thay thế (alt text)
- Đã thiết lập biểu tượng trang web (Favicon) ở đầy đủ các kích thước

### Quét Hình ảnh Giữ chỗ Tạm thời (Visual Placeholder Scan) 🔴
Quét toàn bộ mã nguồn (codebase) và trang web đã triển khai để tìm các tài nguyên hình ảnh giữ chỗ tạm thời (placeholders) bắt buộc phải được thay thế trước khi ra mắt. Đây là hạng mục CỰC KỲ QUAN TRỌNG — một bức ảnh mẫu giữ chỗ còn sót lại trên trang web chính thức gây mất uy tín nghiêm trọng hơn nhiều so với một lỗi chính tả.

**Quét mã nguồn — tìm kiếm các mẫu sau:**
- Các URL có chứa: `placeholder`, `via.placeholder.com`, `placehold.co`,
  `picsum.photos`, `unsplash.it/random`, `dummyimage.com`, `placekitten`,
  `placebear`, `fakeimg`
- Tên tệp có chứa: `placeholder`, `dummy`, `sample`, `example`,
  `temp`, `test-image`, `default-`, `no-image`
- Các tệp mặc định của Next.js / Vercel: `public/next.svg`, `public/vercel.svg`,
  `public/thirteen.svg`, `app/favicon.ico` (nếu vẫn đang là favicon mặc định của Next.js)
- Các hình ảnh khung mẫu (boilerplate) của framework vẫn còn nằm trong thư mục `public/`
- Kích thước gắn cứng nhưng không có ảnh thật: `width={400} height={300}`
  đi kèm với một thẻ div màu xám hoặc thiếu thuộc tính `src`
- Các mẫu giữ chỗ bằng SVG: các thẻ SVG nội tuyến (inline) được dùng làm hình lấp chỗ trống tạm thời
  (thường là các hình chữ nhật màu xám có biểu tượng ở chính giữa)

**Kiểm tra ở cấp độ thành phần giao diện (Component-level):**
- Component ảnh đại diện (Avatar) tự động lùi về biểu tượng người dùng chung chung — trạng thái dự phòng (fallback) đó đã được thiết kế riêng hay vẫn là mặc định của thư viện?
- Component thẻ (Card) có thuộc tính `image?: string` — giao diện hiển thị ra sao khi không truyền ảnh vào? Đó là trạng thái trống đã được thiết kế chỉn chu hay làm vỡ bố cục?
- Các phần Hero/banner đầu trang — hình nền hiện tại đã là bản chốt cuối cùng hay vẫn là ảnh mẫu lúc lập trình?
- Lưới hiển thị sản phẩm/dự án (portfolio grids) — tất cả các mục đã dùng ảnh thật chưa hay một số mục vẫn đang lặp đi lặp lại cùng một bức ảnh thử nghiệm?
- Component Logo — đã là tệp logo chính thức cuối cùng hay vẫn chỉ là chữ giữ chỗ tạm thời?
- Ảnh chia sẻ mạng xã hội (`og:image` meta tag) — đã là hình ảnh thiết kế riêng hay vẫn là ảnh mặc định của framework/nền tảng lưu trữ?

**Kiểm tra dịch vụ bên thứ ba và CDN:**
- Hình ảnh được tải từ các CDN chỉ dành cho giai đoạn phát triển (ví dụ: `picsum.photos`)
- Hình mờ bản quyền (watermarks) của ảnh kho (stock photo) vẫn còn nhìn thấy rõ (tìm các ảnh nặng >500kb có khả năng là ảnh stock tải thử chưa mua bản quyền)
- Hình ảnh có chứa từ `lorem` hoặc `test` trong thuộc tính alt text

**Định dạng đầu ra:**
Xuất ra một bảng liệt kê mọi nội dung giữ chỗ tạm thời được tìm thấy:

| # | Đường dẫn Tệp | Dòng | Loại | Giá trị Hiện tại | Mức độ Nghiêm trọng | Hành động Cần thiết |
|---|-----------|------|------|---------------|----------|---------------|
| 1 | `src/app/page.tsx` | 42 | URL hình ảnh | `via.placeholder.com/800x400` | 🔴 Nghiêm trọng | Thay thế bằng ảnh hero chính thức |
| 2 | `public/favicon.ico` | — | Mặc định của framework | Favicon mặc định của Next.js | 🔴 Nghiêm trọng | Thay thế bằng favicon thương hiệu |
| 3 | `src/components/Card.tsx` | 18 | Thiếu trạng thái dự phòng | Không có ảnh = vỡ bố cục | 🟡 Cao | Thiết kế trạng thái trống (empty state) |

Các cấp độ nghiêm trọng:
- 🔴 Nghiêm trọng (Critical): Hiển thị đập vào mắt người dùng trên các trang chính (khu vực hero, phần đầu trang trên màn hình đầu tiên, ảnh OG)
- 🟡 Cao (High): Hiển thị với người dùng trong quá trình sử dụng bình thường (các thẻ card, ảnh đại diện, ảnh minh họa nội dung)
- 🟠 Trung bình (Medium): Hiển thị trong các trường hợp biên (trạng thái trống, trang báo lỗi, trạng thái dự phòng)
- ⚪ Thấp (Low): Chỉ nằm trong mã nguồn, không hiển thị ra phía người dùng (dữ liệu kiểm thử, các đường dẫn chỉ dùng khi lập trình)

### SEO & Siêu dữ liệu (Metadata)
- Tiêu đề trang (Page titles) là duy nhất và mô tả rõ nội dung
- Đã viết thẻ mô tả (Meta descriptions) cho từng trang
- Đã cấu hình các thẻ Open Graph phục vụ chia sẻ mạng xã hội (kiểm tra bằng công cụ trình gỡ lỗi chia sẻ)
- Tệp `Robots.txt` được cấu hình chính xác
- Tệp `Sitemap.xml` tồn tại và đã được gửi lên công cụ tìm kiếm
- Đã thiết lập các URL chính tắc (Canonical URLs)
- Dữ liệu có cấu trúc / đánh dấu schema markup (nếu áp dụng)

### Hiệu năng (Performance)
- Điểm số Lighthouse đạt các ngưỡng mục tiêu đề ra
- Hình ảnh đã được tối ưu hóa dung lượng và đáp ứng đa kích thước màn hình (responsive)
- Phông chữ được tải một cách hiệu quả
- Không có lỗi nào trong bảng điều khiển (console errors) ở bản dựng thực tế (production build)
- Công cụ phân tích (Analytics) đã được cài đặt và ghi nhận dữ liệu

### Bảo mật (Security)
- Bắt buộc sử dụng giao thức HTTPS (không có lỗi nội dung hỗn hợp / mixed content)
- Các biến môi trường đã được thiết lập đầy đủ trên môi trường production
- Không có khóa API (API keys) nào bị lộ trong mã nguồn phía frontend
- Có giới hạn tần suất gửi (rate limiting) trên các biểu mẫu (ngăn chặn spam)
- Cấu hình CORS chính xác
- Các tiêu đề bảo mật CSP headers (nếu áp dụng)

### Đa Nền tảng & Trình duyệt (Cross-Platform)
- Đã kiểm thử trên: Chrome, Safari, Firefox (phiên bản mới nhất)
- Đã kiểm thử trên: iOS Safari, Android Chrome
- Đã kiểm thử tại các điểm ngắt kích thước màn hình (breakpoints) chính
- Có bảng định dạng CSS dành cho in ấn (nếu người dùng có nhu cầu in trang)

### Hạ tầng (Infrastructure)
- Tên miền đã được kết nối và chứng chỉ SSL đang hoạt động
- Chuyển hướng (redirects) giữa có `www` và không có `www` đã được cấu hình
- Trang báo lỗi 404 đã được thiết kế riêng (không dùng trang mặc định)
- Các trang lỗi hệ thống đã được thiết kế (lỗi 500, trang bảo trì)
- Đã cấu hình sao lưu tự động (backups) cho cơ sở dữ liệu (nếu áp dụng)
- Đã thiết lập công cụ giám sát / kiểm tra thời gian hoạt động (uptime check)

### Bàn giao (nếu là dự án làm cho khách hàng)
- Khách hàng đã có quyền truy cập vào tất cả các tài khoản (hosting, tên miền, analytics)
- Tài liệu hướng dẫn đã hoàn chỉnh (`FORGOKBEY.md` hoặc tài liệu tương đương)
- Đã lên lịch hướng dẫn sử dụng hoặc quay video hướng dẫn bàn giao
- Thỏa thuận hỗ trợ kỹ thuật / bảo trì sau bàn giao đã rõ ràng

## Định dạng Đầu ra
Một danh mục kiểm tra định dạng Markdown bao gồm:
- [ ] Mỗi mục là một ô vuông có thể đánh dấu kiểm
- Được phân nhóm rõ ràng theo từng danh mục
- Có gắn cờ ưu tiên cho các mục sống còn (🔴 bắt buộc phải sửa trước khi ra mắt)
- Mỗi mục đi kèm một dòng ghi chú ngắn hướng dẫn "cách kiểm tra xác minh"