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- → color-brand-
├── text-color → button-text- → color-white
├── padding-x → button-padding-x- → spacing-{n}
├── padding-y → button-padding-y- → spacing-{n}
├── border-radius → button-radius → radius-md
├── font-size → button-font- → 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.
