Tạo tài liệu bàn giao thiết kế đóng vai trò làm hướng dẫn triển khai trực tiếp cho các tác tử lập trình AI (AI coding agents). Khác với các ghi chú bàn giao truyền thống vốn chỉ mô tả thiết kế "nên mang lại cảm giác như thế nào", tài liệu này cung cấp các thông số kỹ thuật có thể phân tích bằng máy với độ mơ hồ bằng không. Mọi giá trị đều tường minh, mọi trạng thái đều được định nghĩa rõ và mọi trường hợp biên đều có quy tắc xử lý cụ thể.
1# Ghi chú Bàn giao Thiết kế — Ưu tiên AI, Dễ đọc cho Con người (AI-First, Human-Readable)23### Một tài liệu bàn giao có cấu trúc được tối ưu hóa cho các tác tử triển khai mã nguồn bằng AI (Claude Code, Cursor, Copilot) nhưng vẫn đảm bảo sự rõ ràng, mạch lạc cho các lập trình viên con người45---67## Giới thiệu về Prompt Này89**Mô tả:** Tạo ra một tài liệu bàn giao thiết kế đóng vai trò làm chỉ dẫn triển khai trực tiếp cho các tác tử lập trình AI (AI coding agents). Khác với các ghi chú bàn giao truyền thống vốn chỉ mô tả chung chung rằng thiết kế "nên mang lại cảm giác như thế nào", tài liệu này cung cấp các thông số kỹ thuật có thể đọc hiểu bằng máy với độ mơ hồ bằng không. Mọi giá trị đều tường minh, mọi trạng thái đều được định nghĩa rõ ràng và mọi trường hợp biên đều có quy tắc xử lý cụ thể. Tài liệu được cấu trúc sao cho một tác tử AI có thể đọc từ trên xuống dưới và lập trình hoàn chỉnh mà không cần hỏi lại bất kỳ câu hỏi làm rõ nào — trong khi một lập trình viên con người cũng có thể đọc hiểu một cách tự nhiên.1011**Triết lý cốt lõi:** Nếu một AI đọc tài liệu này mà vẫn phải tự phỏng đoán bất kỳ chi tiết nào, thì tài liệu đó đã thất bại.1213**Khi nào nên sử dụng:** Sau khi bản thiết kế đã được chốt hoàn tất, và trước khi bắt đầu bước lập trình triển khai. Tài liệu này thay thế cho quy trình bàn giao trên Figma truyền thống, các tệp PDF đặc tả thiết kế và những cuộc trò chuyện kiểu "cứ làm cho nó trông giống như hình mockup là được".1415**Ai là người đọc tài liệu này:**16- Đối tượng chính: Các tác tử lập trình AI (Claude Code, Cursor, Copilot, v.v.)17- Đối tượng thứ hai: Các lập trình viên con người khi đánh giá (review) hoặc gỡ lỗi kết quả đầu ra của AI18- Đối tượng thứ ba: Chính bạn (nhà thiết kế), khi kiểm tra đối chiếu xem bản triển khai thực tế có khớp với ý đồ thiết kế hay không1920**Mối quan hệ với tệp CLAUDE.md:** Tài liệu này giả định rằng trong thư mục gốc của dự án đã có sẵn một tệp hệ thống thiết kế `CLAUDE.md`. Ghi chú Bàn giao sẽ tham chiếu đến các token từ `CLAUDE.md` chứ không định nghĩa lại chúng. Nếu chưa có tệp `CLAUDE.md`, hãy chạy các prompt Trích xuất Hệ thống Thiết kế (Design System Extraction) trước.2122---2324## Nội dung Prompt2526```27Bạn là một kỹ sư hệ thống thiết kế (design systems engineer) đang viết tài liệu đặc tả kỹ thuật để triển khai giao diện.28Kết quả đầu ra của bạn sẽ được đọc chủ yếu bởi các tác tử lập trình AI (Claude Code, Cursor)29và tiếp đó là các lập trình viên con người.3031Bài viết của bạn bắt buộc phải tuân thủ một quy tắc tuyệt đối:32**Nếu người đọc phải tự phỏng đoán, suy luận hoặc giả định bất kỳ điều gì, bạn đã thất bại.**3334Mọi giá trị đều phải tường minh. Mọi trạng thái đều phải được định nghĩa rõ. Mọi trường hợp biên35đều phải có quy tắc xử lý. Tuyệt đối không dùng những từ như "sao cho phù hợp", "khoảng chừng", hay "tương tự như".3637## Bối cảnh Dự án38- **Dự án:**39- **Framework:** [Next.js 14+ / React / v.v.]40- **Công cụ định dạng (Styling):** [Tailwind 3.x / CSS Modules / v.v.]41- **Thư viện thành phần (Component library):** [shadcn/ui / tự viết (custom) / v.v.]42- **Vị trí tệp CLAUDE.md:** [đường dẫn — hoặc "chưa được tạo"]43- **Nguồn thiết kế:** [mã nguồn tải lên / URL trực tiếp / ảnh chụp màn hình]44- **Các trang cần viết đặc tả:** [tất cả / các trang cụ thể]4546## Quy tắc Định dạng Đầu ra4748Trước khi viết bất kỳ đặc tả nào, hãy tuân thủ chính xác các quy tắc định dạng sau:49501. **Các giá trị luôn ở dạng sẵn sàng đưa vào mã nguồn (code-ready).**51 SAI: "khoảng cách vừa phải"52 ĐÚNG: `p-6` (24px)53542. **Màu sắc luôn là tham chiếu token + mã màu hex dự phòng.**55 SAI: "màu xanh thương hiệu"56 ĐÚNG: `text-brand-500` (#2563EB) — lấy từ các token trong CLAUDE.md57583. **Kích thước luôn tuân theo hệ thống đơn vị đo lường của dự án.**59 Nếu dùng Tailwind: sử dụng class Tailwind làm chính, ghi chú px trong ngoặc60 Nếu dùng CSS thuần: sử dụng đơn vị rem làm chính, ghi chú px trong ngoặc61 SAI: "làm cho chữ to hơn trên màn hình máy tính"62 ĐÚNG: `text-lg` (18px) ở màn hình ≥768px, `text-base` (16px) ở màn hình nhỏ hơn63644. **Các điều kiện rẽ nhánh sử dụng cấu trúc if/else tường minh, không bao giờ viết "khi cần thiết".**65 SAI: "hiển thị trạng thái đang tải sao cho phù hợp"66 ĐÚNG: "nếu việc lấy dữ liệu mất >300ms, hiển thị khung xương (skeleton). Nếu lấy dữ liệu thất bại, hiển thị trạng thái lỗi (error state). Nếu dữ liệu trả về mảng rỗng, hiển thị trạng thái trống (empty state)."67685. **Đường dẫn tệp tin phải cụ thể, rõ ràng.**69 SAI: "tạo một component nút bấm"70 ĐÚNG: "tạo tệp `src/components/ui/Button.tsx`"71726. **Mọi thuộc tính thị giác đều phải được nêu rõ, không bao giờ mặc định kế thừa theo giả định.**73 Ngay cả khi điều đó có vẻ "hiển nhiên" — vẫn phải ghi rõ ra. Các tác tử AI không có ngữ cảnh thị giác như mắt người.7475---7677## Cấu trúc Tài liệu7879Hãy tạo tài liệu bàn giao với đầy đủ các phần sau:8081### PHẦN 1: BẢN ĐỒ TRIỂN KHAI (IMPLEMENTATION MAP)8283Một bảng được sắp xếp theo thứ tự ưu tiên liệt kê mọi thứ cần xây dựng.84Các tác tử AI cần triển khai theo đúng thứ tự này để giải quyết các mối quan hệ phụ thuộc một cách chính xác.8586| Thứ tự | Thành phần/Phần | Đường dẫn Tệp | Phụ thuộc vào | Độ phức tạp | Ghi chú |87|-------|------------------|-----------|-------------|-----------|-------|88| 1 | Thiết lập design tokens | `tailwind.config.ts` | Không có | Thấp | Bắt buộc làm đầu tiên — tất cả các component khác đều tham chiếu tới đây |89| 2 | Các component Typography | `src/components/ui/Text.tsx` | Tokens | Thấp | Các biến thể Heading, Body, Caption, Label |90| 3 | Button | `src/components/ui/Button.tsx` | Tokens, Typography | Trung bình | 3 biến thể × 3 kích thước × 6 trạng thái |91| ... | ... | ... | ... | ... | ... |9293Quy tắc:94- Không một mục nào được phép tham chiếu tới một component nằm ở dòng phía sau nó trong bảng95- Độ phức tạp = số lượng biến thể (variants) × số lượng trạng thái (states) mà component đó có96- Ghi chú = bất kỳ lưu ý nào không hiển nhiên trong quá trình lập trình9798---99100### PHẦN 2: ĐẶC TẢ TOÀN CỤC (GLOBAL SPECIFICATIONS)101102Những thông số này áp dụng trên toàn bộ dự án. Tác tử AI phải cấu hình xong những mục này TRƯỚC KHI bắt tay vào xây dựng bất kỳ component nào.103104#### 2.1 Các điểm ngắt màn hình (Breakpoints)105Định nghĩa ranh giới hành vi chính xác:106107```108BREAKPOINTS {109 mobile: 0px — 767px110 tablet: 768px — 1023px111 desktop: 1024px — 1279px112 wide: 1280px — ∞113}114```115116Đối với mỗi breakpoint, hãy nêu rõ:117- Chiều rộng tối đa của khung chứa (container max-width) và khoảng đệm (padding)118- Cỡ chữ cơ sở (base font size)119- Hệ số nhân khoảng cách toàn cục (nếu có thay đổi)120- Chế độ hiển thị thanh điều hướng (nút menu hamburger / thanh ngang / v.v.)121122#### 2.2 Giá trị Mặc định cho Hiệu ứng Chuyển tiếp (Transition Defaults)123```124TRANSITIONS {125 default: duration-200 ease-out126 slow: duration-300 ease-in-out127 spring: duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)128 none: duration-0129}130131RULE: Mọi phần tử tương tác đều sử dụng mức `default` trừ khi132 tài liệu này có chỉ định cụ thể khác.133RULE: Hiệu ứng chuyển tiếp chỉ áp dụng cho: background-color, color, border-color,134 opacity, transform, box-shadow. Tuyệt đối không áp dụng cho: width, height, padding,135 margin (vì những thuộc tính này gây tính toán lại toàn bộ bố cục / layout recalculation).136```137138#### 2.3 Thang phân cấp Lớp hiển thị (Z-Index Scale)139```140Z-INDEX {141 base: 0142 dropdown: 10143 sticky: 20144 overlay: 30145 modal: 40146 toast: 50147 tooltip: 60148}149150RULE: Không bao giờ sử dụng giá trị z-index nào nằm ngoài thang đo này.151```152153#### 2.4 Định dạng Tiêu điểm Bàn phím (Focus Style)154```155FOCUS {156 style: ring-2 ring-offset-2 ring-brand-500157 applies-to: mọi phần tử tương tác (buttons, links, inputs, selects, checkboxes)158 visible: chỉ hiển thị khi điều hướng bằng bàn phím (sử dụng focus-visible, không dùng focus thường)159}160```161162---163164### PHẦN 3: ĐẶC TẢ CHI TIẾT TỪNG TRANG (PAGE SPECIFICATIONS)165166Đối với mỗi trang, hãy cung cấp một bản đặc tả triển khai hoàn chỉnh.167168#### Trang:169**Đường dẫn (Route):** `/exact-route-path`170**Bố cục bao ngoài (Layout):**171**Yêu cầu dữ liệu:** [trang này cần những dữ liệu gì, lấy từ nguồn nào]172173##### Cấu trúc Trang (từ trên xuống dưới)174175```176PAGE STRUCTURE:177├── Section: Hero178│ ├── Component: Heading (h1)179│ ├── Component: Subheading (p)180│ ├── Component: CTA Button (primary, lg)181│ └── Component: HeroImage182├── Section: Features183│ ├── Component: SectionHeading (h2)184│ └── Component: FeatureCard × 3 (grid)185├── Section: Testimonials186│ └── Component: TestimonialSlider187└── Section: CTA188 ├── Component: Heading (h2)189 └── Component: CTA Button (primary, lg)190```191192##### Đặc tả Chi tiết Từng Phần (Section-by-Section Specs)193194Đối với mỗi phần (section):195196****197198```199LAYOUT {200 container: max-w-[1280px] mx-auto px-6 (mobile: px-4)201 direction: flex-col (mobile) → flex-row (desktop)202 gap: gap-8 (32px)203 padding: py-16 (64px) (mobile: py-10)204 background: bg-white205}206207CONTENT {208 heading {209 text: ""210 element: h2211 class: text-3xl font-bold text-gray-900 (mobile: text-2xl)212 max-width: max-w-[640px]213 }214 body {215 text: ""216 class: text-lg text-gray-600 leading-relaxed (mobile: text-base)217 max-width: max-w-[540px]218 }219}220221GRID (nếu áp dụng) {222 columns: grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)223 gap: gap-6 (24px)224 items:225 alignment: items-start226}227228ANIMATION (nếu có áp dụng) {229 type: fade-up khi cuộn trang (on scroll)230 trigger: khi phần nội dung đi vào khung nhìn viewport (threshold: 0.2)231 stagger: mỗi phần tử con trễ 100ms sau phần tử liền trước232 duration: duration-500233 easing: ease-out234 runs: một lần (once — không kích hoạt lại khi cuộn ngược lên)235}236```237238---239240### PHẦN 4: ĐẶC TẢ THÀNH PHẦN (COMPONENT SPECIFICATIONS)241242Đối với mỗi thành phần (component), hãy cung cấp một bản hợp đồng triển khai đầy đủ.243244#### Thành phần:245**Tệp:** `src/components//.tsx`246**Mục đích:** [một câu — thành phần này làm nhiệm vụ gì]247248##### Giao diện Props (Props Interface)249```typescript250interface Props {251 variant: 'primary' | 'secondary' | 'ghost' // kiểu dáng thị giác252 size: 'sm' | 'md' | 'lg' // kích thước253 disabled?: boolean // mặc định: false254 loading?: boolean // mặc định: false255 icon?: React.ReactNode // biểu tượng dẫn đầu tùy chọn256 children: React.ReactNode // nội dung nhãn257 onClick?: () => void // hàm xử lý sự kiện nhấp chuột258}259```260261##### Ma trận Biến thể × Kích thước (Variant × Size Matrix)262Xác định các giá trị chính xác cho mọi tổ hợp:263264```265VARIANT: primary266 SIZE: sm267 height: h-8 (32px)268 padding: px-3 (12px)269 font: text-sm font-medium (14px)270 background: bg-brand-500 (#2563EB)271 text: text-white (#FFFFFF)272 border: none273 border-radius: rounded-md (6px)274 shadow: none275276 SIZE: md277 height: h-10 (40px)278 padding: px-4 (16px)279 font: text-sm font-medium (14px)280 background: bg-brand-500 (#2563EB)281 text: text-white (#FFFFFF)282 border: none283 border-radius: rounded-lg (8px)284 shadow: shadow-sm285286 SIZE: lg287 height: h-12 (48px)288 padding: px-6 (24px)289 font: text-base font-semibold (16px)290 background: bg-brand-500 (#2563EB)291 text: text-white (#FFFFFF)292 border: none293 border-radius: rounded-lg (8px)294 shadow: shadow-sm295296VARIANT: secondary297 [cùng cấu trúc, giá trị khác nhau]298299VARIANT: ghost300 [cùng cấu trúc, giá trị khác nhau]301```302303##### Đặc tả Trạng thái (State Specifications)304Mọi trạng thái phải được định nghĩa rõ cho từng biến thể:305306```307STATES (áp dụng cho TẤT CẢ các biến thể trừ khi được ghi đè):308309 hover {310 background: — làm tối hơn một nấc so với mặc định311 transform: none (không phóng to/thu nhỏ hay dịch chuyển khi di chuột qua)312 shadow:313 cursor: pointer314 transition: default (duration-200 ease-out)315 }316317 active {318 background: — làm tối hơn hai nấc so với mặc định319 transform: scale-[0.98]320 transition: duration-75321 }322323 focus-visible {324 ring: ring-2 ring-offset-2 ring-brand-500325 all other: giống như trạng thái mặc định326 }327328 disabled {329 opacity: opacity-50330 cursor: not-allowed331 pointer-events: none332 ALL hover/active/focus states: không áp dụng333 }334335 loading {336 content: thay thế children bằng biểu tượng xoay spinner (16px, animate-spin)337 width: giữ nguyên chiều rộng như trạng thái không tải (ngăn chặn dịch chuyển bố cục - layout shift)338 pointer-events: none339 opacity: opacity-80340 }341```342343##### Hành vi của Biểu tượng (Icon Behavior)344```345ICON RULES {346 position: bên trái văn bản nhãn (luôn luôn)347 size: 16px (sm), 16px (md), 20px (lg)348 gap: gap-1.5 (sm), gap-2 (md), gap-2 (lg)349 color: kế thừa màu văn bản (currentColor)350 when loading: biểu tượng bị ẩn đi, spinner thế vào vị trí của nó351 icon-only: nếu không có children, thành phần trở thành hình vuông (width = height)352 bắt buộc thêm thuộc tính prop aria-label353}354```355356---357358### PHẦN 5: LUỒNG TƯƠNG TÁC (INTERACTION FLOWS)359360Đối với mỗi luồng người dùng, hãy cung cấp hướng dẫn triển khai từng bước:361362#### Luồng: [Tên Luồng, ví dụ: "Người dùng Đăng ký"]363```364TRIGGER: người dùng nhấp vào nút "Sign Up" trên thanh tiêu đề (header)365366STEP 1: Hộp thoại Modal mở ra367 animation: fade-in (opacity 0→1, duration-200)368 backdrop: bg-black/50, nhấp ra bên ngoài sẽ đóng modal369 focus: giữ tiêu điểm (trap focus) bên trong modal, tự động đặt tiêu điểm vào ô nhập đầu tiên370 body: scroll-lock (ngăn cuộn trang nền phía sau)371372STEP 2: Người dùng điền biểu mẫu373 fields:374 validation: khi rời ô nhập - on blur (không kiểm tra ngay khi đang gõ - on change — giúp giảm nhiễu)375376 field: email {377 type: email378 required: true379 validate: mẫu regex + "phải chứa ký tự @ và tên miền"380 error: "Có vẻ đây không phải là địa chỉ email hợp lệ — hãy kiểm tra lỗi chính tả"381 success: biểu tượng dấu tích xanh xuất hiện (fade-in, duration-150)382 }383384 field: password {385 type: password (có nút bật/tắt hiện/ẩn mật khẩu)386 required: true387 validate: tối thiểu 8 ký tự, 1 chữ hoa, 1 chữ số388 error: hiển thị danh sách kiểm tra các yêu cầu, làm nổi bật mục chưa đạt389 strength: hiển thị thanh đo độ mạnh mật khẩu (yếu/trung bình/mạnh)390 }391392STEP 3: Người dùng gửi biểu mẫu393 button: hiển thị trạng thái đang tải (xem đặc tả thành phần Button)394 request: POST /api/auth/signup395 duration: dự kiến 1-3 giây396397STEP 4a: Thành công398 modal: nội dung chuyển sang thông báo thành công (crossfade, duration-200)399 message: "Đã tạo tài khoản! Hãy kiểm tra email của bạn để xác minh."400 action: nút "Đã hiểu" ("Got it") sẽ đóng modal401 redirect: sau khi đóng, chuyển hướng tới /dashboard402 toast: none (chính modal ĐÃ LÀ thông báo xác nhận)403404STEP 4b: Lỗi — email đã tồn tại405 field: ô nhập email hiển thị trạng thái lỗi406 message: "Email này đã có tài khoản — bạn có muốn đăng nhập không?"407 action: liên kết "Đăng nhập" ("Log in") chuyển modal sang biểu mẫu đăng nhập408 button: trở về trạng thái mặc định (không còn đang tải)409410STEP 4c: Lỗi — sự cố mạng411 display: biểu ngữ báo lỗi ở đầu modal (không dùng toast)412 message: "Đã xảy ra sự cố từ phía hệ thống của chúng tôi. Thử lại nhé?"413 action: nút "Thử lại" ("Try again") gửi lại biểu mẫu414 button: trở về trạng thái mặc định415416STEP 4d: Lỗi — vượt quá giới hạn tần suất (rate limited)417 display: biểu ngữ báo lỗi418 message: "Quá nhiều lần thử. Vui lòng đợi 60 giây rồi thử lại."419 button: bị vô hiệu hóa (disabled) trong 60 giây kèm đồng hồ đếm ngược hiển thị rõ420```421422---423424### PHẦN 6: QUY TẮC HÀNH VI ĐÁP ỨNG (RESPONSIVE BEHAVIOR RULES)425426Đừng chỉ mô tả chung chung những gì thay đổi — hãy chỉ định rõ các quy tắc chính xác:427428```429RESPONSIVE RULES:430431Rule 1: Điều hướng (Navigation)432 ≥1024px: thanh điều hướng ngang, hiển thị tất cả các mục433 <1024px: biểu tượng hamburger, ngăn kéo trượt vào (slide-in drawer) từ bên phải434 drawer-width: 80vw (max-w-[320px])435 animation: translate-x (duration-300 ease-out)436 backdrop: bg-black/50, nhấp ra ngoài sẽ đóng ngăn kéo437438Rule 2: Các Phần Lưới (Grid Sections)439 ≥1024px: grid-cols-3440 768-1023px: grid-cols-2 (mục cuối cùng trải rộng toàn hàng nếu tổng số mục là số lẻ)441 <768px: grid-cols-1442443Rule 3: Phần Mở đầu (Hero Section)444 ≥1024px: hai cột (văn bản bên trái, hình ảnh bên phải) — tỷ lệ chia 55/45445 <1024px: một cột duy nhất (văn bản ở trên, hình ảnh ở dưới)446 image max-height: 400px, object-cover447448Rule 4: Co giãn Kiểu chữ (Typography Scaling)449 ≥1024px: h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base450 <1024px: h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base451452Rule 5: Co giãn Khoảng cách (Spacing Scaling)453 ≥1024px: section-padding: py-16, container-padding: px-8454 768-1023px: section-padding: py-12, container-padding: px-6455 <768px: section-padding: py-10, container-padding: px-4456457Rule 6: Vùng Chạm Cảm ứng (Touch Targets)458 <1024px: tất cả các phần tử tương tác phải có vùng nhận diện chạm tối thiểu 44×44px459 nếu kích thước hiển thị trực quan < 44px, hãy sử dụng phần đệm (padding) vô hình để đạt đủ 44px460461Rule 7: Hình ảnh (Images)462 all images: sử dụng next/image với thuộc tính prop sizes đáp ứng (responsive)463 hero: sizes="(max-width: 1024px) 100vw, 50vw"464 grid items: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"465```466467---468469### PHẦN 7: CÁC TRƯỜNG HỢP BIÊN & ĐIỀU KIỆN RANH GIỚI (EDGE CASES & BOUNDARY CONDITIONS)470471Phần này giúp ngăn chặn những vấn đề kiểu "nhưng chuyện gì sẽ xảy ra khi...":472473```474EDGE CASES:475476Tràn Văn bản (Text Overflow) {477 headings: tối đa 2 dòng, sau đó cắt bớt bằng dấu ba chấm text-ellipsis (thêm thuộc tính title để xem toàn bộ văn bản)478 body text: cho phép tự động xuống dòng tự nhiên, không cắt bớt479 button labels: chỉ một dòng duy nhất, tối đa 30 ký tự, không cắt bớt (ràng buộc thiết kế)480 nav items: một dòng duy nhất, cắt bớt nếu >16 ký tự trên thiết bị di động481 table cells: cắt bớt kèm chú giải nổi (tooltip) khi di chuột qua482}483484Trạng thái Trống (Empty States) {485 lists/grids with 0 items: hiển thị thành phần486 - illustration:487 - heading: ""488 - body: ""489 - CTA: "" →490491 user avatar missing: hiển thị chữ cái viết tắt tên trên nền màu492 - background: tạo tự động từ mã băm (hash) tên người dùng (mang tính tất định - deterministic)493 - initials: chữ cái đầu tiên của tên + họ, viết hoa494 - font: text-sm font-medium text-white495496 image fails to load: hiển thị khung giữ chỗ màu xám với biểu tượng hình ảnh497 - background: bg-gray-100498 - icon: ImageOff từ thư viện lucide-react, text-gray-400, 24px499}500501Trạng thái Đang tải (Loading States) {502 page load: khung xương toàn trang - full-page skeleton (không dùng vòng xoay spinner)503 component load: khung xương cấp độ thành phần khớp với kích thước hiển thị cuối cùng504 button action: vòng xoay spinner nội dòng bên trong nút bấm (xem đặc tả Button)505 infinite list: dòng khung xương skeleton × 3 ở dưới cùng trong khi đang tải trang tiếp theo506507 skeleton style: bg-gray-200 rounded animate-pulse508 skeleton rule: hình dạng khung xương phải khớp với hình dạng nội dung cuối cùng509 (hình chữ nhật cho văn bản, hình tròn cho ảnh đại diện, rounded-lg cho thẻ card)510}511512Trạng thái Lỗi (Error States) {513 API error (500): hiển thị biểu ngữ lỗi nội dòng kèm nút thử lại (retry)514 Network error: hiển thị biểu ngữ "Có vẻ bạn đang ngoại tuyến" ở trên cùng (tự động ẩn đi khi có kết nối trở lại)515 404 content: hiển thị thành phần 404 tùy chỉnh (không dùng trang mặc định của Next.js)516 Permission denied: chuyển hướng tới /login kèm tham số URL quay lại (return URL param)517 Form validation: hiển thị nội dòng trên từng trường (xem đặc tả luồng), không bao giờ dùng hàm alert()518}519520Dữ liệu Cực trị (Data Extremes) {521 username 1 character: hiển thị bình thường522 username 50 characters: cắt bớt ở mức 20 ký tự trên thanh điều hướng, hiển thị đầy đủ trong trang hồ sơ523 price $0.00: hiển thị "Free" ("Miễn phí")524 price $999,999.99: đảm bảo bố cục không bị vỡ (kiểm thử với con số đã định dạng)525 list with 1 item: giữ cùng bố cục như khi có nhiều mục (không xử lý ngoại lệ riêng)526 list with 500 items: phân trang ở mức 20 mục, hiển thị nút "Load more" ("Tải thêm")527 date today: hiển thị "Today" ("Hôm nay") thay vì ngày tháng cụ thể528 date this year: hiển thị "Mar 13" thay vì "Mar 13, 2026"529 date other year: hiển thị "Mar 13, 2025"530}531```532533---534535### PHẦN 8: DANH SÁCH KIỂM TRA XÁC MINH TRIỂN KHAI (IMPLEMENTATION VERIFICATION CHECKLIST)536537Sau khi triển khai, tác tử AI (hoặc lập trình viên con người) cần xác minh:538539```540VERIFICATION:541542□ Mọi thành phần đều khớp chính xác với ma trận biến thể × kích thước543□ Mọi trạng thái (hover, active, focus, disabled, loading) đều hoạt động đúng544□ Thứ tự nhấn phím Tab tuân theo đúng thứ tự thị giác trên tất cả các trang545□ Vòng sáng focus-visible xuất hiện khi điều hướng bằng bàn phím, không xuất hiện khi nhấp chuột546□ Tất cả các hiệu ứng chuyển tiếp (transitions) đều sử dụng đúng thời lượng và hàm gia tốc (easing) đã chỉ định (không dùng mặc định của trình duyệt)547□ Không xảy ra hiện tượng dịch chuyển bố cục trong quá trình tải trang (kiểm tra chỉ số CLS)548□ Các trạng thái khung xương (skeleton) khớp với kích thước nội dung cuối cùng549□ Tất cả các trường hợp biên từ Phần 7 đều đã được xử lý550□ Vùng chạm cảm ứng ≥ 44×44px trên các điểm ngắt (breakpoints) di động551□ Không xuất hiện thanh cuộn ngang ở bất kỳ điểm ngắt nào552□ Tất cả hình ảnh đều sử dụng next/image với thuộc tính prop sizes chính xác553□ Các giá trị Z-index chỉ sử dụng thang đo đã được định nghĩa554□ Các trạng thái lỗi hiển thị chính xác (kiểm thử bằng tính năng bóp băng thông mạng - network throttle)555□ Các trạng thái trống hiển thị chính xác (kiểm thử với dữ liệu rỗng)556□ Việc cắt bớt văn bản hoạt động chuẩn xác tại các độ dài ranh giới557□ Các token chế độ tối (Dark mode - nếu có áp dụng) đều đã được ánh xạ đầy đủ558```559560---561562## Cách Tác tử AI Nên Sử dụng Tài liệu Này563564Hãy đưa hướng dẫn này vào đầu tài liệu bàn giao được tạo ra565để AI thực thi biết cách làm việc với tài liệu đó:566567```568INSTRUCTIONS FOR AI IMPLEMENTATION AGENT:5695701. Đọc kỹ toàn bộ tài liệu này trước khi viết bất kỳ dòng mã nào.5712. Triển khai theo đúng thứ tự được chỉ định trong PHẦN 1 (Sơ đồ Triển khai - Implementation Map).5723. Tham chiếu tệp CLAUDE.md để lấy giá trị của các token. Nếu một token được tham chiếu ở đây573 không có trong CLAUDE.md, hãy gắn cờ cảnh báo nó và sử dụng giá trị dự phòng (fallback) được cung cấp.5744. Mọi giá trị trong tài liệu này đều có chủ đích rõ ràng. Không tự ý thay thế575 bằng các giá trị "gần giống". `gap-6` có nghĩa là `gap-6`, không phải `gap-5`.5765. Mọi trạng thái đều phải được triển khai đầy đủ. Nếu một trạng thái không được chỉ định cho577 một thành phần, đó là một khoảng trống trong bản đặc tả — hãy gắn cờ cảnh báo, đừng tự đoán.5786. Sau khi triển khai xong mỗi thành phần, hãy duyệt qua ma trận trạng thái của nó579 và xác minh tất cả các trạng thái đều hoạt động tốt trước khi chuyển sang thành phần tiếp theo.5807. Khi gặp điểm chưa rõ ràng, hãy ưu tiên cách hiểu tường minh hơn.581 Nếu vẫn còn mơ hồ, hãy thêm một dòng ghi chú TODO: "// HANDOFF-AMBIGUITY: [description]"582```583```584585---586587## Ghi chú Tùy chỉnh (Customization Notes)588589**Nếu bạn không sử dụng Tailwind:** Hãy thay thế tất cả các tham chiếu lớp Tailwind trong prompt bằng các giá trị tương đương trong hệ thống của bạn. Cấu trúc vẫn giữ nguyên — chỉ có định dạng giá trị là thay đổi. Hãy nói với Claude: "Sử dụng các thuộc tính tùy chỉnh CSS (CSS custom properties) làm chính, các giá trị px làm chú thích đi kèm."590591**Nếu bạn đang bàn giao cho một công cụ AI cụ thể:** Hãy thêm các ghi chú đặc thù cho công cụ đó. Ví dụ, đối với Cursor: "Tạo bản triển khai dưới dạng các bước chỉnh sửa từng phần trên các tệp hiện có, không viết đè lại toàn bộ tệp." Đối với Claude Code: "Tạo mỗi thành phần thành một tệp hoàn chỉnh, kiểm thử nó, sau đó mới chuyển sang thành phần tiếp theo."592593**Nếu chưa có tệp CLAUDE.md:** Hãy yêu cầu prompt tạo một phần token tối giản ở ngay đầu tài liệu bàn giao, chỉ bao gồm các token cần thiết cho đợt bàn giao cụ thể này. Nó sẽ không phải là một hệ thống thiết kế (design system) đầy đủ, nhưng sẽ ngăn chặn được tình trạng gắn cứng (hardcode) các giá trị.594595**Đối với các dự án nhiều trang:** Hãy chạy prompt một lần cho mỗi trang, nhưng chỉ đưa Phần 1 (Sơ đồ Triển khai) và Phần 2 (Đặc tả Toàn cục) vào lần chạy đầu tiên. Các trang tiếp theo sẽ tham chiếu lại cùng những thông số toàn cục đó.596
Tạo bản thiết kế trang kiểm thử tính năng cho Enterprise WeChat/DingTalk tập trung vào quản lý danh bạ, quản lý lịch/lịch trình và gửi/nhận tin nhắn. Thiết kế phải thân thiện với người dùng, bóng bẩy và mang đậm tính công nghệ.
Kiểm toán các cặp màu tiền cảnh/hậu cảnh theo độ tương phản WCAG 2.x (mức AA và AAA cho văn bản thường và văn bản lớn), báo cáo tỷ lệ và kết quả đạt/không đạt, đồng thời lưu ý các rủi ro đối với người mù màu. Sử dụng khi kiểm tra bảng màu giao diện người dùng (UI palette), design token, hoặc hỏi "màu xám trên nền trắng này có dễ đọc không?". Bao gồm công cụ kiểm tra độ tương phản bằng thư viện chuẩn Python có hỗ trợ --self-test.
Kỹ năng này giúp các tác tử AI tái tạo lại thiết kế trang web dựa trên những hình ảnh cảm hứng do người dùng tải lên, đảm bảo sự hòa quyện giữa phong cách nguyên bản và dấu ấn cá nhân.
