André Farias

# Ngữ cảnh tác vụ

Bạn sẽ đóng vai trò là role. Ngữ cảnh hiện tại là context. Mục tiêu của bạn là goal, nhằm đạt được sucess_criteria.

# Ngữ cảnh giọng điệu

Bạn cần duy trì giọng điệu tone.

# Dữ liệu nền tảng, tài liệu và hình ảnh

Trước tiên, hãy đọc toàn bộ các tệp này một cách完整 (đầy đủ) trước khi phản hồi:
<guide>guide_document</guide>

# Mô tả chi tiết tác vụ & các quy tắc

Dưới đây là một số quy tắc quan trọng cho tác vụ này:
- task_rule_1
- task_rule_2
- task_rule_3
- task_rule_4
- task_rule_5

# Các ví dụ

Dưới đây là một ví dụ về cách phản hồi trong một cuộc tương tác tiêu chuẩn:

<example>
example
</example>

# Lịch sử hội thoại

Dưới đây là lịch sử cuộc trò chuyện (giữa người dùng và bạn) trước câu hỏi này:
<history>history</history>

# Mô tả tác vụ hoặc yêu cầu tức thời

- task_description_1
- task_description_2
- task_description_3
- task_description_4
- task_description_5

# Lập kế hoạch và suy nghĩ thấu đáo

Hãy suy nghĩ thật cẩn trọng về câu trả lời của bạn trước khi phản hồi và ĐỪNG bắt đầu thực thi tác vụ ngay. Thay vào đó, hãy đặt cho tôi các câu hỏi làm rõ (sử dụng công cụ 'AskUserQuestion' nếu có sẵn) để chúng ta có thể cùng nhau tinh chỉnh phương pháp tiếp cận theo từng bước. Sau đó, hãy đưa ra kế hoạch thực thi của bạn (tối đa 5-10 bước), để chúng ta chỉ bắt đầu công việc một khi đã thống nhất hoàn toàn với nhau.


# Định dạng đầu ra

Hãy đặt câu trả lời của bạn bên trong cặp thẻ <response></response>.

# Phản hồi điền sẵn (nếu có)

response_tag

Hãy tạo một bản tóm tắt bàn giao bao gồm tất cả các quyết định đã được đưa ra trong phiên này, được định dạng sao cho tôi có thể dán trực tiếp vào một cuộc trò chuyện mới để tiếp tục thực hiện các bước tiếp theo đang chờ xử lý.

bạn là một người thầy thông thái và dạy học đầy hiệu quả. mục tiêu của bạn là đảm bảo người học hiểu sâu sắc nội dung của phiên làm việc này.

hãy thực hiện điều này từng bước một theo từng chặng nhỏ thay vì dồn tất cả vào cuối buổi. trước khi chuyển sang chặng tiếp theo, bạn cần xác nhận rằng cô ấy đã nắm vững mọi thứ trong chặng hiện tại. việc hiểu bài cần bao quát cả ở cấp độ tổng quan (ví dụ: động lực, lý do ra đời) lẫn cấp độ chi tiết bên dưới (ví dụ: logic nghiệp vụ, các trường hợp biên).

hãy duy trì một tài liệu markdown (.md) cập nhật liên tục chứa danh sách kiểm tra (checklist) những điều người học cần nắm được. hãy đảm bảo cô ấy hiểu rõ: 1) vấn đề là gì, tại sao vấn đề đó lại tồn tại, các nhánh rẽ khác nhau của vấn đề; 2) giải pháp là gì, tại sao nó lại được giải quyết theo cách đó, các quyết định thiết kế, các trường hợp biên (edge cases); 3) bối cảnh rộng hơn về việc tại sao điều này lại quan trọng, những thay đổi này sẽ tác động đến những gì.

hãy đảm bảo cô ấy hiểu rõ câu hỏi tại sao (và đào sâu thêm nhiều tầng câu hỏi tại sao nữa), đồng thời nắm chắc cả nội dung cái gì và thực hiện như thế nào. việc thấu hiểu tường tận bản chất vấn đề là điều tối quan trọng.

để nắm được mức độ hiểu hiện tại của cô ấy, hãy chủ động yêu cầu cô ấy diễn đạt lại theo cách hiểu của mình trước. sau đó giúp cô ấy lấp đầy những khoảng trống kiến thức từ điểm đó—cô ấy có thể đặt câu hỏi cho bạn hoặc yêu cầu giải thích kiểu eli5 (như cho trẻ 5 tuổi), eli14 (như cho thiếu niên 14 tuổi), hoặc elii (giải thích như cho một thực tập sinh mới vào nghề).

hãy kiểm tra bài cô ấy bằng các câu hỏi tự luận mở hoặc câu hỏi trắc nghiệm thông qua công cụ AskUserQuestion (nhớ đảo vị trí của đáp án đúng, và tuyệt đối không tiết lộ đáp án cho đến khi cô ấy đã nộp câu trả lời). hãy cho cô ấy xem mã nguồn hoặc hướng dẫn cô ấy sử dụng trình gỡ lỗi (debugger) nếu cần thiết!

/goal phiên học tập này không được kết thúc cho đến khi bạn đã xác minh rằng người học đã chứng minh được mình hiểu thấu đáo mọi mục có trong danh sách của bạn.

Đây là trang dashboard của một ứng dụng government audit hiện đại có tên là AuditFlow.

Hãy phân tích kỹ lưỡng giao diện người dùng (UI) trong ảnh chụp màn hình này và mô tả nó chi tiết nhất có thể để bàn giao từ nhà thiết kế UI sang cho lập trình viên. Bản mô tả thiết kế cần bao gồm cả chế độ sáng (light mode) và chế độ tối (dark mode), đồng thời chứa các điểm ngắt đáp ứng màn hình (responsive breakpoints) khớp với thiết lập mặc định của Tailwind CSS v4.3.

Xuất các đặc tính thiết kế dưới định dạng JSONC có cấu trúc.

Đối với màu sắc, hãy trích xuất một bảng màu tổng quát và chỉ mô tả chi tiết cho các màu nhấn (accents) cũng như các thành phần đa phương tiện phức tạp. Mục tiêu là chỉ sử dụng 2 bảng màu chính: màu chính (primary) và màu phụ (secondary) tương tự như hệ màu của Tailwind. Bên cạnh 2 bảng màu này, bạn có thể định nghĩa bất kỳ số lượng sắc độ xám và màu nhấn nào cho các chi tiết giao diện phức tạp hơn (dải chuyển màu gradients, bóng đổ shadows, hình SVG, v.v.).

Kết thúc bằng một câu lệnh (prompt) hướng dẫn cách triển khai giao diện này cho lập trình viên, nhưng không đề cập đến bất kỳ thông số kỹ thuật công nghệ nào; chỉ nêu bản mô tả giao diện cần triển khai cùng các quy tắc và cách sử dụng hệ thống token thiết kế. Xuất câu lệnh này dưới dạng một khối mã (code block) Markdown.

Đầu ra phải bao gồm hai khối mã: một khối mã cho bản mô tả thiết kế (design brief) và một khối mã cho đặc tả thiết kế định dạng JSONC.

Bạn được giao nhiệm vụ tích hợp một thành phần React (React component) có sẵn vào cơ sở mã nguồn (codebase).

Cơ sở mã nguồn cần hỗ trợ:
- Cấu trúc dự án shadcn  
- Tailwind CSS
- Typescript

Nếu dự án chưa hỗ trợ các công nghệ trên, hãy cung cấp hướng dẫn cách thiết lập dự án thông qua shadcn CLI, cài đặt Tailwind hoặc Typescript.

Xác định đường dẫn mặc định cho các thành phần giao diện (components) và tệp định kiểu (styles). 
Nếu đường dẫn mặc định cho các thành phần không phải là `/components/ui`, hãy giải thích rõ tại sao việc tạo thư mục này lại quan trọng.
Sao chép và dán thành phần giao diện này vào thư mục `/components/ui`:

21st.dev_component

Hướng dẫn Triển khai
 1. Phân tích cấu trúc thành phần và xác định tất cả các thư viện phụ thuộc (dependencies) bắt buộc
 2. Rà soát các đối số (props) và trạng thái (state) của thành phần
 3. Xác định bất kỳ context providers hoặc hooks cần thiết nào và cài đặt chúng
 4. Các câu hỏi cần đặt ra
 - Những dữ liệu/props nào sẽ được truyền vào thành phần này?
 - Có yêu cầu quản lý trạng thái cụ thể nào không?
 - Có cần các tài nguyên bắt buộc nào (hình ảnh, biểu tượng, v.v.) không?
 - Hành vi hiển thị đáp ứng (responsive) mong đợi là gì?
 - Vị trí tốt nhất để sử dụng thành phần này trong ứng dụng là ở đâu?

Các bước tích hợp
 0. Sao chép và dán toàn bộ đoạn mã ở trên vào đúng các thư mục quy định
 1. Cài đặt các thư viện phụ thuộc bên ngoài
 2. Điền vào các vị trí tài nguyên hình ảnh bằng ảnh kho lưu trữ Unsplash mà bạn biết chắc chắn có tồn tại
 3. Sử dụng bộ biểu tượng `lucide-react` cho các hình svg hoặc logo nếu thành phần đó yêu cầu

# Bộ chuyển đổi Giao diện Thành phần shadcn (shadcn Component Visual Adapter)

## 🎯 Mục tiêu
Tái cấu trúc (refactor) thành phần giao diện `component_name` hiện có nằm tại đường dẫn `component_file_path` để khớp với **thiết kế trực quan, cấu trúc và hành vi** của thành phần tham chiếu có tại:

> bunx --bun shadcn@latest add accordion
reference_url   ← tùy chọn; để trống nếu không có trang tài liệu nào

KHÔNG thay thế logic nghiệp vụ, giao diện thuộc tính (props interface) hiện có, hoặc các mẫu truy xuất dữ liệu (data-fetching patterns). Hãy bảo toàn chúng.
Chỉ điều chỉnh **tầng hiển thị trực quan (visual layer)**: cấu trúc thẻ đánh dấu (markup), tên lớp CSS (class names), hiệu ứng chuyển động (animations) và các thuộc tính hỗ trợ tiếp cận (accessibility attributes).

---

## 📋 Bước 1 — Phân tích Thành phần Hiện có

Trước khi viết bất kỳ dòng mã nào:

1. Đọc toàn bộ mã nguồn của `component_file_path`.
2. Lập sơ đồ chi tiết:
   - Toàn bộ **các thuộc tính (props) và kiểu dữ liệu của chúng** (TypeScript interfaces hoặc PropTypes).
   - Các **biến trạng thái (state variables)** nội bộ (`useState`, `useReducer`, Zustand slices, v.v.).
   - **Các Context providers hoặc custom hooks** đang được sử dụng.
   - **Các thành phần con (child components)** được kết xuất và vị trí lưu trữ của chúng.
   - **Các hàm xử lý sự kiện (event handlers)** và hàm gọi lại (callbacks) được truyền ra cho thành phần cha.
3. Liệt kê mọi câu lệnh **import** — gắn cờ bất kỳ thư viện nào sẽ xung đột hoặc có thể được thay thế bằng thành phần nguyên thủy (primitive) của shadcn.

Xuất ra một bảng kiểm toán ngắn gọn trước khi chạm vào mã nguồn:

| Hạng mục | Giá trị hiện tại | Hành động |
|------|--------------|--------|
| Props | ... | giữ nguyên / đổi tên / xóa |
| State | ... | giữ nguyên / chuyển đổi |
| Context/Hooks | ... | giữ nguyên / thay thế |
| Sub-components | ... | giữ nguyên / thay thế |
| Dependencies | ... | giữ nguyên / cài đặt thêm / gỡ bỏ |

---

## 📦 Bước 2 — Giải quyết Thư viện Phụ thuộc (Dependency Resolution)

Chạy trực tiếp câu lệnh cài đặt sau:

install_command

Sau khi lệnh chạy xong, các tệp được tạo ra sẽ xuất hiện trong thư mục
components/ui/. Tiến hành sang Bước 3 bằng cách sử dụng các tệp đó.

---

## 🔬 Bước 3 — Rà soát Thành phần Tham chiếu

NẾU reference_url được cung cấp → truy xuất trang đó và trích xuất đặc tả giao diện như thông thường.

NẾU reference_url để trống → đọc các tệp vừa được tải về bởi lệnh CLI
ở Bước 2 và trích xuất trực tiếp các thông tin tương tự từ mã nguồn:
  - lược đồ biến thể `cva` (cva variant schema)
  - các thuộc tính `data-state` / `data-disabled`
  - các lớp hiệu ứng động/chuyển cảnh (animation/transition classes)
  - các vai trò và thuộc tính ARIA (ARIA roles and props)
  - các mẫu sử dụng hàm `cn()`

---

## 🛠 Bước 4 — Tái cấu trúc Thành phần (Refactor)

Áp dụng cấu trúc giao diện từ Bước 3 vào thành phần hiện có từ Bước 1.

### Quy tắc:
- ✅ Giữ nguyên toàn bộ **tên và kiểu dữ liệu của các prop hiện có** trừ khi có prop tương đương trực tiếp trong shadcn.
- ✅ Giữ nguyên toàn bộ **logic truy xuất dữ liệu, logic nghiệp vụ và các hàm callback**.
- ✅ Bọc các thành phần nguyên thủy Radix bằng **`forwardRef`** và trải phẳng `...props` để giữ nguyên tính linh hoạt.
- ✅ Sử dụng hàm `cn()` cho mọi thao tác gộp `className` — tuyệt đối không nối chuỗi thủ công.
- ✅ Xuất (export) các thành phần con phức hợp có đặt tên nếu thành phần tham chiếu sử dụng chúng (ví dụ: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`).
- ❌ KHÔNG import tệp shadcn vừa sinh ra rồi xuất lại (re-export) — hãy xây dựng thành phần nguyên thủy trực tiếp ngay bên trong tệp được tái cấu trúc để giữ logic nằm chung một chỗ.
- ❌ KHÔNG tự ý thêm các lớp Tailwind không có mặt trong thành phần tham chiếu nếu không có chỉ dẫn rõ ràng.

### Hành vi đáp ứng kích thước màn hình (`sm md lg`):
Áp dụng các lớp đáp ứng ưu tiên thiết bị di động (mobile-first). Xác nhận các điểm ngắt (breakpoints) hiện tại trong `tailwind.config.ts` khớp với quy ước của dự án. Nếu bản tham chiếu sử dụng truy vấn vùng chứa (container queries), hãy cài đặt gói `@tailwindcss/container-queries`.

---

## 🧩 Bước 5 — Context Providers và Hooks

Nếu thành phần tham chiếu yêu cầu một context provider (ví dụ: `ToastProvider`, `TooltipProvider`):

1. Kiểm tra xem nó đã được gắn (mount) trong `app/layout.tsx` hoặc `app/providers.tsx` hay chưa.
2. Nếu chưa, hãy thêm nó vào tệp bố cục (layout) phù hợp. Cung cấp bản so sánh khác biệt (diff) chính xác.
3. Nếu cần một custom hook (ví dụ: `useToast`, `useDialog`), hãy đặt nó vào thư mục `hooks/` và import từ đó.

---

## ❓ Bước 6 — Câu hỏi Làm rõ (hỏi trước khi sinh mã nếu chưa rõ)

Nếu bất kỳ thông tin nào dưới đây không thể xác định được từ mã nguồn hiện có, **hãy hỏi trước khi viết mã**:

1. **Dữ liệu/props**: Dữ liệu truyền vào sẽ có cấu trúc như thế nào? (Cung cấp một đối tượng mẫu nếu hữu ích.)
2. **Quản lý trạng thái**: Trạng thái của thành phần là cục bộ (local), hay được quản lý từ bên ngoài (Zustand, Redux, React Query)?
3. **Tài nguyên (Assets)**: Có cần hình ảnh, logo hoặc biểu tượng tùy chỉnh nào nằm ngoài thư viện `lucide-react` hay không?
4. **Đáp ứng màn hình (Responsive)**: Bố cục mong đợi tại các điểm ngắt `sm md lg` là gì?
5. **Vị trí đặt**: Thành phần này sẽ nằm ở đâu trong cây định tuyến/bố cục (routing/layout tree) của ứng dụng? (Rất quan trọng để đặt context provider đúng chỗ.)

---

## 📐 Bước 7 — Định dạng Đầu ra

Cung cấp kết quả theo cấu trúc sau:

1. **`component_file_path`** — toàn bộ tệp thành phần đã được tái cấu trúc hoàn chỉnh.
2. **`components/ui/shadcn_component_slug.tsx`** — thành phần nguyên thủy shadcn (chỉ khi thực sự cần thiết và chưa được công cụ CLI tạo ra).
3. **`lib/utils.ts`** — chỉ khi cần tạo mới hoặc cập nhật.
4. **Bản diff của Layout/provider** — chỉ khi cần bổ sung thêm một provider.
5. Một phần **ghi chú chuyển đổi (migration notes)** ngắn gọn liệt kê:
   - Các thư viện phụ thuộc đã gỡ bỏ
   - Các thuộc tính (props) đã đổi tên (nếu có)
   - Bất kỳ bước thủ công nào cần thực hiện thêm (ví dụ: thêm biến CSS vào `globals.css`)

---

## 🎨 Các Biến Tailwind CSS (shadcn design tokens)

Xác nhận rằng tệp `globals.css` đã chứa đầy đủ các thuộc tính tùy chỉnh CSS bắt buộc. Nếu thành phần tham chiếu sử dụng các token như `--radius`, `--background`, `--foreground`, `--primary`, `--ring`, hãy nối thêm các biến còn thiếu vào. Sử dụng bộ token mặc định của shadcn cho chủ đề màu `zinc` trừ khi dự án đã định nghĩa sẵn một chủ đề tùy chỉnh riêng.

---

## 🚫 Các Ràng buộc

- Framework: **Next.js 14+ App Router**
- Định kiểu (Styling): Chỉ sử dụng **Tailwind CSS 3** — không dùng inline styles, không dùng CSS modules, không dùng styled-components.
- TypeScript: **chế độ nghiêm ngặt (strict mode)**. Toàn bộ mã mới viết phải được định kiểu đầy đủ.
- Không nâng cấp hoặc hạ cấp bất kỳ phiên bản thư viện phụ thuộc hiện có nào trừ khi xảy ra xung đột phụ thuộc ngang hàng (peer conflict) trực tiếp.