Ghi chú bàn giao thiết kế - AI đầu tiên, con người có thể đọc được

1# Ghi chú bàn giao thiết kế — AI-First, con người có thể đọc được
2
3### Tài liệu bàn giao có cấu trúc được tối ưu hóa cho các tác nhân triển khai AI (Claude Code, Cursor, Copilot) trong khi vẫn rõ ràng cho các nhà phát triển con người
4
5---
6
7## Về lời nhắc này
8
9**Mô tả:** Tạo tài liệu bàn giao thiết kế đóng vai trò là hướng dẫn triển khai trực tiếp cho các tác nhân mã hóa AI. Không giống như các ghi chú chuyển giao truyền thống mô tả "cảm giác" của một thiết kế, tài liệu này cung cấp các thông số kỹ thuật có thể phân tích cú pháp bằng máy mà không có sự mơ hồ. Mọi giá trị đều rõ ràng, mọi trạng thái đều được xác định, mọi trường hợp cạnh đều có quy tắc. Tài liệu được cấu trúc sao cho tác nhân AI có thể đọc từ trên xuống dưới và triển khai mà không cần đặt câu hỏi làm rõ — trong khi nhà phát triển con người cũng có thể đọc nó một cách tự nhiên.
10
11**Triết lý cốt lõi:** Nếu AI đọc tài liệu này và phải đoán bất cứ điều gì thì tài liệu đó đã thất bại.
12
13**Thời điểm sử dụng:** Sau khi thiết kế hoàn tất, trước khi bắt đầu triển khai. Điều này thay thế cho việc chuyển giao Figma, thiết kế các tệp PDF thông số kỹ thuật và các cuộc hội thoại "chỉ làm cho nó trông giống như mô hình".
14
15**Ai đọc cái này:**
16- Chính: Tác nhân mã hóa AI (Claude Code, Cursor, Copilot, v.v.)
17- Thứ cấp: Các nhà phát triển con người xem xét hoặc gỡ lỗi đầu ra của AI
18- Cấp ba: Bạn (người thiết kế), khi kiểm tra xem việc triển khai có phù hợp với mục đích hay không
19
20**Mối quan hệ với CLAUDE.md:** Tài liệu này giả định tệp hệ thống thiết kế CLAUDE.md đã tồn tại trong thư mục gốc của dự án. Mã thông báo tham chiếu Ghi chú Handoff từ CLAUDE.md nhưng không xác định lại chúng. Nếu không có CLAUDE.md tồn tại, trước tiên hãy chạy lời nhắc Trích xuất hệ thống thiết kế.
21
22---
23
24## Lời nhắc
25
26```
27You are a design systems engineer writing implementation specifications.
28Your output will be read primarily by AI coding agents (Claude Code, Cursor)
29and secondarily by human developers.
30
31Your writing must follow one absolute rule:
32**If the reader has to guess, infer, or assume anything, you have failed.**
33
34Every value must be explicit. Every state must be defined. Every edge case
35must have a rule. No "as appropriate," no "roughly," no "similar to."
36
37## Project Context
38- **Project:** 
39- **Framework:** [Next.js 14+ / React / etc.]
40- **Styling:** [Tailwind 3.x / CSS Modules / etc.]
41- **Component library:** [shadcn/ui / custom / etc.]
42- **CLAUDE.md location:** [path — or "not yet created"]
43- **Design source:** [uploaded code / live URL / screenshots]
44- **Pages to spec:** [all / specific pages]
45
46## Output Format Rules
47
48Before writing any specs, follow these formatting rules exactly:
49
501. **Values are always code-ready.**
51   WRONG: "medium spacing"
52   RIGHT: `p-6` (24px)
53
542. **Colors are always token references + fallback hex.**
55   WRONG: "brand blue"
56   RIGHT: `text-brand-500` (#2563EB) — from CLAUDE.md tokens
57
583. **Sizes are always in the project's unit system.**
59   If Tailwind: use Tailwind classes as primary, px as annotation
60   If CSS: use rem as primary, px as annotation
61   WRONG: "make it bigger on desktop"
62   RIGHT: `text-lg` (18px) at ≥768px, `text-base` (16px) below
63
644. **Conditionals use explicit if/else, never "as needed."**
65   WRONG: "show loading state as appropriate"
66   RIGHT: "if data fetch takes >300ms, show skeleton. If fetch fails, show error state. If data returns empty array, show empty state."
67
685. **File paths are explicit.**
69   WRONG: "create a button component"
70   RIGHT: "create `src/components/ui/Button.tsx`"
71
726. **Every visual property is stated, never inherited by assumption.**
73   Even if "obvious" — state it. AI agents don't have visual context.
74
75---
76
77## Document Structure
78
79Generate the handoff document with these sections:
80
81### SECTION 1: IMPLEMENTATION MAP
82
83A priority-ordered table of everything to build.
84AI agents should implement in this order to resolve dependencies correctly.
85
86| Order | Component/Section | File Path | Dependencies | Complexity | Notes |
87|-------|------------------|-----------|-------------|-----------|-------|
88| 1 | Design tokens setup | `tailwind.config.ts` | None | Low | Must be first — all other components reference these |
89| 2 | Typography components | `src/components/ui/Text.tsx` | Tokens | Low | Heading, Body, Caption, Label variants |
90| 3 | Button | `src/components/ui/Button.tsx` | Tokens, Typography | Medium | 3 variants × 3 sizes × 6 states |
91| ... | ... | ... | ... | ... | ... |
92
93Rules:
94- Nothing can reference a component that comes later in the table
95- Complexity = how many variants × states the component has
96- Notes = anything non-obvious about implementation
97
98---
99
100### SECTION 2: GLOBAL SPECIFICATIONS
101
102These apply everywhere. AI agent should configure these BEFORE building any components.
103
104#### 2.1 Breakpoints
105Define exact behavior boundaries:
106
107```
108ĐIỂM ĐIỂM {
109di động: 0px — 767px
110máy tính bảng: 768px — 1023px
111máy tính để bàn: 1024px - 1279px
112rộng: 1280px — ∞
113}
114```
115
116For each breakpoint, state:
117- Container max-width and padding
118- Base font size
119- Global spacing multiplier (if it changes)
120- Navigation mode (hamburger / horizontal / etc.)
121
122#### 2.2 Transition Defaults
123```
124CHUYỂN TIẾP {
125mặc định: thời lượng-200 dễ dàng thoát ra
126chậm: thời lượng-300 dễ dàng ra vào
127mùa xuân: thời lượng-500 khối bezier(0,34, 1,56, 0,64, 1)
128không có: thời lượng-0
129}
130
131QUY TẮC: Mọi phần tử tương tác đều sử dụng `default` trừ khi
132tài liệu này có quy định khác.
133QUY TẮC: Các chuyển tiếp áp dụng cho: màu nền, màu sắc, màu đường viền,
134độ mờ, biến đổi, bóng hộp. Không bao giờ: chiều rộng, chiều cao, phần đệm,
135lề (những nguyên nhân này gây ra việc tính toán lại bố cục).
136```
137
138#### 2.3 Z-Index Scale
139```
140Z-INDEX {
141cơ sở: 0
142thả xuống: 10
143dính: 20
144lớp phủ: 30
145phương thức: 40
146bánh mì nướng: 50
147chú giải công cụ: 60
148}
149
150QUY TẮC: Không có giá trị chỉ số z nào nằm ngoài thang đo này. Bao giờ.
151```
152
153#### 2.4 Focus Style
154```
155TẬP TRUNG {
156phong cách: ring-2 ring-offset-2 ring-brand-500
157áp dụng cho: mọi yếu tố tương tác (nút, liên kết, đầu vào, lựa chọn, hộp kiểm)
158hiển thị: chỉ trên điều hướng bàn phím (sử dụng tiêu điểm hiển thị, không tiêu điểm)
159}
160```
161
162---
163
164### SECTION 3: PAGE SPECIFICATIONS
165
166For each page, provide a complete implementation spec.
167
168#### Page: 
169**Route:** `/exact-route-path`
170**Layout:** 
171**Data requirements:** [what data this page needs, from where]
172
173##### Page Structure (top to bottom)
174
175```
176CẤU TRÚC TRANG: 
177├── Mục: Anh hùng
178│ ├── Thành phần: Tiêu đề (h1)
179│ ├── Thành phần: Tiêu đề phụ (p)
180│ ├── Thành phần: Nút CTA (chính, lg)
181│ └── Thành phần: HeroImage
182├── Phần: Tính năng
183│ ├── Thành phần: Tiêu đề phần (h2)
184│ └── Thành phần: FeatureCard × 3 (lưới)
185├── Phần: Lời chứng thực
186│ └── Thành phần: TestimonialSlider
187└── Phần: CTA
188├── Thành phần: Tiêu đề (h2)
189└── Thành phần: Nút CTA (chính, lg)
190```
191
192##### Section-by-Section Specs
193
194For each section:
195
196****
197
198```
199CÁCH TRÌNH BÀY {
200vùng chứa: max-w-[1280px] mx-auto px-6 (di động: px-4)
201hướng: flex-col (di động) → flex-row (máy tính để bàn)
202khoảng cách: khoảng cách-8 (32px)
203phần đệm: py-16 (64px) (di động: py-10)
204nền: bg-trắng
205}
206
207NỘI DUNG {
208tiêu đề {
209văn bản: ""
210phần tử: h2
211lớp: text-3xl font-bold text-gray-900 (di động: text-2xl)
212chiều rộng tối đa: max-w-[640px]
213}
214thân hình {
215văn bản: ""
216lớp: text-lg text-gray-600 hàng đầu-thư giãn (di động: text-base)
217chiều rộng tối đa: max-w-[540px]
218}
219}
220
221LƯỚI (nếu có) {
222cột: lưới-cols-3 (máy tính bảng: lưới-cols-2) (di động: lưới-cols-1)
223khoảng cách: khoảng cách-6 (24px)
224mục: 
225căn chỉnh: mục-bắt đầu
226}
227
228HOẠT HÌNH (nếu có) {
229kiểu: mờ dần khi cuộn
230kích hoạt: khi phần vào khung nhìn (ngưỡng: 0,2)
231lảo đảo: mỗi đứa trẻ trì hoãn 100ms sau lần trước
232thời lượng: thời lượng-500
233nới lỏng: nới lỏng
234chạy: một lần (không kích hoạt lại khi cuộn lên)
235}
236```
237
238---
239
240### SECTION 4: COMPONENT SPECIFICATIONS
241
242For each component, provide a complete implementation contract.
243
244#### Component: 
245**File:** `src/components//.tsx`
246**Purpose:** [one sentence — what this component does]
247
248##### Props Interface
249```bản đánh máy
250giao diện Props {
251biến thể: 'chính' | 'thứ cấp' | 'ma' // phong cách trực quan
252kích thước: 'sm' | 'md' | 'lg' // kích thước
253bị vô hiệu hóa?: boolean // mặc định: sai
254đang tải?: boolean // mặc định: sai
255icon?: React.ReactNode // biểu tượng hàng đầu tùy chọn
256trẻ em: React.ReactNode // nội dung nhãn
257onClick?: () => void // trình xử lý nhấp chuột
258}
259```
260
261##### Variant × Size Matrix
262Define exact values for every combination:
263
264```
265BIẾN THỂ: chính
266KÍCH THƯỚC: sm
267chiều cao: h-8 (32px)
268phần đệm: px-3 (12px)
269phông chữ: văn bản-sm phông chữ trung bình (14px)
270lý lịch: bg-brand-500 (#2563EB)
271văn bản: văn bản màu trắng (#FFFFFF)
272biên giới: không có
273bán kính đường viền: round-md (6px)
274bóng tối: không có
275
276KÍCH THƯỚC: md
277chiều cao: h-10 (40px)
278phần đệm: px-4 (16px)
279phông chữ: văn bản-sm phông chữ trung bình (14px)
280lý lịch: bg-brand-500 (#2563EB)
281văn bản: văn bản màu trắng (#FFFFFF)
282biên giới: không có
283bán kính đường viền: round-lg (8px)
284bóng: bóng-sm
285
286KÍCH THƯỚC: lg
287chiều cao: h-12 (48px)
288phần đệm: px-6 (24px)
289phông chữ: phông chữ cơ sở văn bản-nửa đậm (16px)
290lý lịch: bg-brand-500 (#2563EB)
291văn bản: văn bản màu trắng (#FFFFFF)
292biên giới: không có
293bán kính đường viền: round-lg (8px)
294bóng: bóng-sm
295
296BIẾN THỂ: thứ cấp
297[same structure, different values]
298
299BIẾN THỂ: ma
300[same structure, different values]
301```
302
303##### State Specifications
304Every state must be defined for every variant:
305
306```
307TIỂU BANG (áp dụng cho TẤT CẢ các biến thể trừ khi bị ghi đè):
308
309di chuột {
310nền:  - làm tối một bước so với mặc định
311biến đổi: không có (không có tỷ lệ/dịch khi di chuột)
312bóng: 
313con trỏ: con trỏ
314quá trình chuyển đổi: mặc định (thời lượng-200 dễ dàng)
315}
316
317tích cực {
318nền:  - làm tối hai bước so với mặc định
319biến đổi: tỷ lệ-[0.98]
320chuyển tiếp: thời lượng-75
321}
322
323có thể nhìn thấy tiêu điểm {
324vòng: vòng-2 vòng-offset-2 vòng-thương hiệu-500
325tất cả khác: giống như trạng thái mặc định
326}
327
328tàn tật {
329độ mờ: độ mờ-50
330con trỏ: không được phép
331sự kiện con trỏ: không có
332TẤT CẢ trạng thái di chuột/hoạt động/tiêu điểm: không áp dụng
333}
334
335đang tải {
336nội dung: thay thế trẻ em bằng spinner (16px, animate-spin)
337chiều rộng: duy trì cùng chiều rộng với trạng thái không tải (ngăn chặn sự thay đổi bố cục)
338sự kiện con trỏ: không có
339độ mờ: độ mờ-80
340}
341```
342
343##### Icon Behavior
344```
345QUY TẮC BIỂU TƯỢNG {
346vị trí: bên trái của văn bản nhãn (luôn luôn)
347kích thước: 16px (sm), 16px (md), 20px (lg)
348khoảng cách: khoảng cách-1,5 (sm), khoảng cách-2 (md), khoảng cách-2 (lg)
349color: kế thừa màu văn bản (currentColor)
350khi tải: biểu tượng bị ẩn, spinner giữ vị trí của nó
351chỉ biểu tượng: nếu không có con, thành phần sẽ trở thành hình vuông (chiều rộng = chiều cao)
352thêm yêu cầu chống đỡ nhãn aria
353}
354```
355
356---
357
358### SECTION 5: INTERACTION FLOWS
359
360For each user flow, provide step-by-step implementation:
361
362#### Flow: [Flow Name, e.g., "User Signs Up"]
363```
364TRIGGER: người dùng nhấp vào nút "Đăng ký" trong tiêu đề
365
366BƯỚC 1: Phương thức mở ra
367hoạt ảnh: mờ dần (độ mờ 0→1, thời lượng-200)
368phông nền: bg-black/50, nhấp chuột bên ngoài để đóng chế độ
369tiêu điểm: bẫy tiêu điểm bên trong phương thức, tự động lấy nét đầu vào đầu tiên
370nội dung: khóa cuộn (ngăn cuộn nền)
371
372BƯỚC 2: Người dùng điền vào biểu mẫu
373các trường: 
374xác thực: mờ (không thay đổi - giảm nhiễu)
375             
376trường: email {
377loại: email
378bắt buộc: đúng
379xác thực: mẫu biểu thức chính quy + "phải chứa @ và tên miền"
380error: "Trông không giống email — hãy kiểm tra lỗi chính tả"
381thành công: biểu tượng dấu kiểm màu xanh lá cây xuất hiện (làm mờ dần, thời lượng-150)
382}
383             
384trường: mật khẩu {
385gõ: mật khẩu (có hiển thị/ẩn chuyển đổi)
386bắt buộc: đúng
387xác thực: tối thiểu 8 ký tự, 1 chữ hoa, 1 số
388lỗi: hiển thị danh sách kiểm tra các yêu cầu, đánh dấu phần chưa đáp ứng
389sức mạnh: hiển thị thanh sức mạnh (yếu/trung bình/mạnh)
390}
391
392BƯỚC 3: Người dùng gửi
393nút: hiển thị trạng thái tải (xem thông số thành phần Nút)
394yêu cầu: POST/api/auth/đăng ký
395thời lượng: mong đợi 1-3 giây
396
397BƯỚC 4a: Thành công
398modal: chuyển nội dung sang thông báo thành công (crossfade, thời lượng-200)
399message: "Tài khoản đã được tạo! Hãy kiểm tra email của bạn để xác minh."
400hành động: nút "Đã hiểu" đóng chế độ
401chuyển hướng: sau khi đóng, chuyển hướng đến/dashboard
402bánh mì nướng: không có (phương thức LÀ xác nhận)
403
404BƯỚC 4b: Lỗi - email tồn tại
405trường: đầu vào email hiển thị trạng thái lỗi
406message: "Email này đã có tài khoản — thay vào đó bạn muốn đăng nhập?"
407hành động: liên kết "Đăng nhập" chuyển phương thức sang hình thức đăng nhập
408nút: trở về trạng thái mặc định (không tải)
409
410BƯỚC 4c: Lỗi - lỗi mạng
411hiển thị: biểu ngữ lỗi ở đầu phương thức (không phải bánh mì nướng)
412thông báo: "Đã xảy ra lỗi từ phía chúng tôi. Thử lại?"
413hành động: nút "Thử lại" gửi lại
414nút: trở về trạng thái mặc định
415
416BƯỚC 4d: Lỗi - tốc độ giới hạn
417hiển thị: biểu ngữ lỗi
418thông báo: "Thử quá nhiều lần. Đợi 60 giây và thử lại."
419nút: bị tắt trong 60 giây và hiển thị đếm ngược
420```
421
422---
423
424### SECTION 6: RESPONSIVE BEHAVIOR RULES
425
426Don't describe what changes — specify the exact rules:
427
428```
429QUY TẮC ĐÁP ỨNG:
430
431Quy tắc 1: Điều hướng
432≥1024px: điều hướng ngang, hiển thị tất cả các mục
433<1024px: biểu tượng bánh hamburger, ngăn trượt từ bên phải
434chiều rộng ngăn kéo: 80vw (max-w-[320px])
435hoạt hình: dịch-x (thời lượng-300 dễ dàng)
436phông nền: bg-black/50, nhấp chuột bên ngoài đóng lại
437
438Quy tắc 2: Phần lưới
439≥1024px: lưới-cols-3
440768-1023px: Grid-cols-2 (Mục cuối cùng sẽ đầy nếu đếm lẻ)
441<768px: lưới-cols-1
442
443Quy tắc 3: Phần anh hùng
444≥1024px: hai cột (văn bản bên trái, hình ảnh bên phải) — chia 55/45
445<1024px: cột đơn (văn bản trên cùng, hình ảnh dưới cùng)
446chiều cao tối đa của hình ảnh: 400px, bìa đối tượng
447
448Quy tắc 4: Chia tỷ lệ kiểu chữ
449≥1024px: h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base
450<1024px: h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base
451
452Quy tắc 5: Chia tỷ lệ khoảng cách
453≥1024px: phần đệm phần: py-16, phần đệm vùng chứa: px-8
454768-1023px: phần đệm: py-12, phần đệm vùng chứa: px-6
455<768px: phần đệm phần: py-10, phần đệm vùng chứa: px-4
456
457Quy tắc 6: Chạm vào mục tiêu
458<1024px: tất cả các phần tử tương tác có diện tích nhấn tối thiểu 44×44px
459nếu kích thước hình ảnh < 44px, hãy sử dụng phần đệm vô hình để đạt 44px
460
461Quy tắc 7: Hình ảnh
462tất cả hình ảnh: sử dụng tiếp theo/hình ảnh với kích thước đáp ứng
463anh hùng: size="(độ rộng tối đa: 1024px) 100vw, 50vw"
464các mục lưới: size="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
465```
466
467---
468
469### SECTION 7: EDGE CASES & BOUNDARY CONDITIONS
470
471This section prevents the "but what happens when..." problems:
472
473```
474TRƯỜNG HỢP CẠNH:
475
476Tràn văn bản {
477tiêu đề: tối đa 2 dòng, sau đó cắt bớt bằng dấu chấm lửng văn bản (thêm attr tiêu đề cho toàn văn)
478nội dung văn bản: cho phép gói tự nhiên, không cắt ngắn
479nhãn nút: chỉ một dòng, tối đa 30 ký tự, không cắt ngắn (hạn chế thiết kế)
480mục điều hướng: một dòng, cắt bớt nếu >16 ký tự trên thiết bị di động
481ô bảng: cắt ngắn bằng chú giải công cụ khi di chuột
482}
483
484Bang trống {
485danh sách/lưới có 0 mục: hiển thị thành phần 
486- minh họa: 
487- tiêu đề: ""
488- nội dung: ""
489- CTA: "" → 
490  
491thiếu hình đại diện người dùng: hiển thị tên viết tắt trên nền màu
492- nền: tạo từ hàm băm tên người dùng (xác định)
493- tên viết tắt: chữ cái đầu tiên của tên + họ, chữ hoa
494- phông chữ: text-sm font-medium text-white
495  
496hình ảnh không tải được: hiển thị phần giữ chỗ màu xám với biểu tượng hình ảnh
497- nền: bg-gray-100
498- biểu tượng: ImageOff từ lucide-react, text-gray-400, 24px
499}
500
501Đang tải trạng thái {
502tải trang: khung toàn trang (không phải spinner)
503tải thành phần: khung cấp thành phần phù hợp với kích thước cuối cùng
504hành động của nút: nút quay nội tuyến trong nút (xem Thông số nút)
505danh sách vô hạn: hàng khung × 3 ở dưới cùng trong khi tìm nạp trang tiếp theo
506  
507kiểu khung xương: bg-gray-200 animate-xung tròn
508quy tắc bộ xương: hình dạng bộ xương phải khớp với hình dạng nội dung cuối cùng
509(hình chữ nhật cho văn bản, hình tròn cho hình đại diện, hình tròn cho thẻ)
510}
511
512Trạng thái lỗi {
513Lỗi API (500): hiển thị biểu ngữ lỗi nội tuyến bằng nút thử lại
514Lỗi mạng: hiển thị biểu ngữ "Có vẻ như bạn đang ngoại tuyến" ở trên cùng (tự động loại bỏ khi được kết nối lại)
515Nội dung 404: hiển thị thành phần 404 tùy chỉnh (không phải mặc định của Next.js)
516Quyền bị từ chối: chuyển hướng đến/đăng nhập với thông số URL trả về
517Xác thực biểu mẫu: nội tuyến trên mỗi trường (xem thông số luồng), không bao giờ cảnh báo()
518}
519
520Dữ liệu cực đoan {
521tên người dùng 1 ký tự: hiển thị bình thường
522tên người dùng 50 ký tự: cắt ngắn ở 20 trong điều hướng, đầy đủ trong hồ sơ
523giá 0,00 USD: hiển thị "Miễn phí"
524giá $999.999,99: đảm bảo bố cục không bị hỏng (kiểm tra với số được định dạng)
525danh sách có 1 mục: bố cục giống như nhiều mục (không có trường hợp đặc biệt)
526danh sách 500 mục: đánh số trang ở số 20, hiển thị nút "Tải thêm"
527ngày hôm nay: hiển thị "Hôm nay" không phải ngày
528ngày trong năm nay: hiển thị "13 tháng 3" chứ không phải "13 tháng 3 năm 2026"
529ngày năm khác: hiển thị "13 tháng 3 năm 2025"
530}
531```
532
533---
534
535### SECTION 8: IMPLEMENTATION VERIFICATION CHECKLIST
536
537After implementation, the AI agent (or human developer) should verify:
538
539```
540XÁC MINH:
541
542□ Mọi thành phần đều khớp chính xác với ma trận kích thước × biến thể
543□ Mọi trạng thái (di chuột, hoạt động, tập trung, tắt, tải) đều hoạt động
544□ Thứ tự tab theo thứ tự trực quan trên tất cả các trang
545□ Vòng hiển thị tiêu điểm xuất hiện trên điều hướng bàn phím, không xuất hiện khi nhấp chuột
546□ Tất cả các quá trình chuyển đổi đều sử dụng thời lượng và độ giãn được chỉ định (không phải mặc định của trình duyệt)
547□ Không thay đổi bố cục trong khi tải trang (kiểm tra CLS)
548□ Trạng thái khung khớp với kích thước nội dung cuối cùng
549□ Tất cả các trường hợp cạnh từ Mục 7 đều được xử lý
550□ Mục tiêu chạm ≥ 44×44px trên điểm dừng trên thiết bị di động
551□ Không cuộn ngang ở bất kỳ điểm dừng nào
552□ Tất cả các hình ảnh đều sử dụng hình ảnh tiếp theo với kích thước chính xác
553□ Giá trị chỉ số Z chỉ sử dụng thang đo xác định
554□ Trạng thái lỗi hiển thị chính xác (kiểm tra bằng ga mạng)
555□ Trạng thái trống hiển thị chính xác (kiểm tra với dữ liệu trống)
556□ Việc cắt bớt văn bản có tác dụng ở độ dài biên
557□ Mã thông báo chế độ tối (nếu có) đều được ánh xạ
558```
559
560---
561
562## How the AI Agent Should Use This Document
563
564Include this instruction at the top of the generated handoff document
565so the implementing AI knows how to work with it:
566
567```
568HƯỚNG DẪN ĐƠN VỊ TRIỂN KHAI AI:
569
5701. Đọc đầy đủ tài liệu này trước khi viết bất kỳ mã nào.
5712. Thực hiện theo trình tự quy định tại MỤC 1 (Bản đồ thực hiện).
5723. Tham khảo CLAUDE.md để biết giá trị mã thông báo. Nếu một mã thông báo được tham chiếu ở đây
573không có trong CLAUDE.md, hãy gắn cờ nó và sử dụng giá trị dự phòng được cung cấp.
5744. Mọi giá trị trong tài liệu này đều có chủ ý. Đừng thay thế
575với các giá trị "đủ gần". `gap-6` có nghĩa là `gap-6`, không phải `gap-5`.
5765. Mọi bang đều phải được thực hiện. Nếu một trạng thái không được chỉ định cho
577một thành phần, đó là một lỗ hổng trong thông số kỹ thuật - hãy gắn cờ nó, đừng đoán.
5786. Sau khi triển khai từng thành phần, hãy chạy qua ma trận trạng thái của nó
579và xác minh tất cả các trạng thái đều hoạt động trước khi chuyển sang thành phần tiếp theo.
5807. Khi gặp phải sự mơ hồ, hãy ưu tiên cách giải thích rõ ràng hơn.
581Nếu vẫn còn mơ hồ, hãy thêm nhận xét TODO: "// HANDOFF-AMBIGUITY: [description]"
582```
583```
584
585---
586
587## Ghi chú tùy chỉnh
588
589**Nếu bạn không sử dụng Tailwind:** Thay thế tất cả tham chiếu lớp Tailwind trong lời nhắc bằng nội dung 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ị thay đổi. Nói với Claude: "Sử dụng thuộc tính tùy chỉnh CSS làm giá trị chính, giá trị px làm chú thích."
590
591**Nếu bạn đang chuyển giao cho một công cụ AI cụ thể:** Thêm ghi chú dành riêng cho công cụ đó. Ví dụ: đối với Con trỏ: "Tạo quá trình triển khai dưới dạng chỉnh sửa từng bước đối với các tệp hiện có, chứ không phải viết lại toàn bộ tệp". Đối với Mã Claude: "Tạo từng thành phần dưới dạng một tệp hoàn chỉnh, kiểm tra nó rồi chuyển sang thành phần tiếp theo."
592
593**Nếu chưa có CLAUDE.md nào tồn tại:** Yêu cầu lời nhắc tạo phần mã thông báo tối thiểu ở đầu tài liệu chuyển giao chỉ bao gồm các mã thông báo cần thiết cho lần chuyển giao cụ thể này. Nó sẽ không phải là một hệ thống thiết kế đầy đủ, nhưng nó ngăn chặn các giá trị được mã hóa cứng.
594
595**Đối với các dự án nhiều trang:** Chạy lời nhắc một lần trên mỗi trang, nhưng chỉ bao gồm Phần 1 (Bản đồ triển khai) và Phần 2 (Thông số chung) trong lần chạy đầu tiên. Các trang tiếp theo tham chiếu cùng một hình cầu.
596