Lắp ghép Hoàn chỉnh 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: - Ngăn xếp công nghệ: [Next.js 14+ / React 18+ / Tailwind 3.x / v.v.] - Phiên bản Node: - 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).