# /generate-design-spec — Sinh Design Specification (FE / App) ## Gate {{include:steps/gate.md}} *Lưu ý: Với lệnh này, target file là một Business PRD (`{TICKET-ID}-{prd-slug}.md` — file `.md` ở gốc feature folder) dưới `{paths.specs_dir}/{domain}/{prd-slug}/`. Phân giải từ `$ARGUMENTS` hoặc liệt kê thư mục và hỏi. Chỉ hỗ trợ PRD của FE và mobile — PRD của BE sẽ bị từ chối ở bước Platform Check.* ## Context {{include:steps/context-loader.md}} *Context bổ sung cho lệnh này: Đọc toàn bộ PRD target. Trích xuất: **TICKET-ID**, **domain**, **tên feature**, **Service** và **Module** từ metadata PRD (row `| **Service** |` và `| **Module** |`), User Flow (Section 4a), và tên màn hình Wireframe (Section 4b).* *Quy tắc trích xuất Service (giống /generate-prd):* - *Nếu metadata PRD có `| **Service** |` → dùng làm `active_service` và `| **Module** |` làm `active_module`.* - *Nếu vắng VÀ `services` được định nghĩa trong `project-context.yaml` → hỏi: "Design Spec này dành cho service nào?" (chỉ liệt kê service FE/App, chờ chọn).* - *Nếu dự án single-service → `active_service = "default"`, `active_module = tech_stack.module`.* --- ## Guard — PRD đã duyệt chưa Đọc `| **Status** |` từ bảng Metadata của Business PRD nguồn: - `Status: approved` → tiếp tục bình thường. - `Status: draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép prototype song song): ``` ⚠️ Business PRD đang ở Status: {status} (chưa duyệt). Design Spec dựng trên PRD chưa chốt có thể phải làm lại theo PRD. Khuyến nghị: PO duyệt PRD (đặt `| **Status** | approved |`) rồi mới sinh Design Spec. Vẫn sinh Design Spec bây giờ? (Y/N) ``` Chỉ tiếp tục khi người dùng chọn Y. --- ## Platform Check Dùng `active_module` và `platform_type` suy ra từ context loading: 1. Nếu `platform_type = "backend"` → **STOP**. Xuất: ``` ❌ Design Spec chỉ dành cho platform FE và mobile. Với service BE, API contract thuộc về Business PRD (Use Case → section Business Logic). ``` 2. Nếu `platform_type = "web-frontend"` → set `active_platform = "web"`. 3. Nếu `platform_type = "mobile"`: - `flutter` hoặc `react-native` → set `active_platform = "app"` - `ios-swiftui` → set `active_platform = "app-ios"` - `android-compose` → set `active_platform = "app-android"` 4. Nếu `platform_type = "unknown"` → hỏi: "Design Spec này dành cho platform nào?" ``` Options: 1 — web (React / Next.js / Vue / Angular) 2 — app (Flutter / React Native) 3 — app-ios (iOS SwiftUI) 4 — app-android (Android Compose) ``` Chờ chọn. Map lựa chọn sang `active_platform` và suy ra `active_module` nếu được. --- ## Version Check (PRD drift) Trước khi sinh, kiểm tra design-spec đã tồn tại cho platform này: `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md` Đọc `| **Version** |` hiện tại của PRD từ Metadata (vd `1.3`). - **Không tồn tại** → sinh mới; ghi `| **Built from PRD** | v{prd_version hiện tại} |`. - **Tồn tại** → đọc row `| **Built from PRD** |` của nó, so với `| **Version** |` PRD hiện tại: - **Bằng nhau** → hỏi: "Design Spec đã dựng từ PRD v{x}. Sinh lại? (Y/N)". - **Khác** (PRD đã đổi) → CHECKPOINT drift: ``` ⚠️ Phát hiện PRD version drift Design Spec dựng từ PRD v{old}; PRD giờ ở v{new}. Thay đổi kể từ v{old} (đọc # Change Log của PRD): {changelog rows} Options: Y — cập nhật phần ảnh hưởng (màn / flow đổi) F — sinh lại toàn bộ N — huỷ ``` - Khi sinh / sinh lại → cập nhật `| **Built from PRD** | v{prd_version hiện tại} |`, bump `| **Version** |` Design Spec, **reset `| **Status** | draft |`** (design đổi → sign-off lại), thêm row Changelog. --- ## Screen Discovery Từ Section 4 của PRD (User Flow + Wireframe), trích xuất mọi tên screen / page / modal được nhắc tới. Trình bày danh sách và hỏi PO xác nhận: ``` Screens detected from PRD: 1. {Screen name 1} 2. {Screen name 2} ... Đây đã đủ các màn cho platform {active_platform} chưa? Thêm màn còn thiếu, bỏ màn không áp dụng, hoặc xác nhận bằng Y. ``` Chờ xác nhận. Lưu danh sách đã xác nhận là `screen_list`. --- ## Figma Frame Links *(bắt buộc — một link node-level đọc được cho mỗi màn)* Một Design Spec chỉ tốt ngang với design mà nó trỏ tới. AI **không đọc được link file trần** (`figma.com/design/{fileKey}/...` không có `node-id`) — nó cần một **link node-level tới từng frame cụ thể** để fetch layout, component, và token thật của frame đó qua Figma MCP. Vậy nên thu thập một link **mỗi màn**, không phải một link cho cả feature. **Hỏi PO, liệt kê mọi màn trong `screen_list`:** ``` Dán link Figma frame cho từng màn bên dưới. Trong Figma: chọn frame → chuột phải → "Copy link to selection" (URL phải chứa ?node-id=... — đó là link per-frame mà AI đọc được) 1. {Screen 1} : ____ 2. {Screen 2} : ____ ... Nếu một màn chưa có design, gõ none cho màn đó. ``` **Với mỗi câu trả lời:** 1. **Validate format** — URL phải khớp `figma.com/design/{fileKey}/...?node-id={nodeId}`. - Hợp lệ → lưu thành `figma_frames[{screen}] = {url}`, parse ra `fileKey` + `nodeId`. - Link file **không có `node-id`** → từ chối: "Link này trỏ tới cả file, không phải một frame. Copy lại qua chuột phải → Copy link to selection." Hỏi lại màn đó. - `none` → `figma_frames[{screen}] = "TBD"`, đánh dấu màn đó ❌ Missing. 2. **Fetch frame qua Figma MCP** (chỉ với link hợp lệ) — gọi `get_design_context` (và `get_screenshot` khi hữu ích) với `fileKey` + `nodeId` đã parse để đọc layout, tên component, và design token thật. Đặt mọi Screen Spec dựa trên dữ liệu đã fetch này; **đừng** bịa layout mà frame không thể hiện. Nếu fetch thất bại (permission / not found) → coi màn đó là ❌ Missing và ghi chú lỗi fetch. 3. Suy ra `figma_url` mức feature = link file (không có `node-id`) chung của các frame, cho row Metadata. Nếu các frame trải nhiều file, liệt kê từng cái. **Gate bắt buộc (không abort — sinh ra draft):** - Nếu **bất kỳ** màn nào ❌ Missing → spec được sinh dưới dạng **draft** với các màn đó được gắn cờ, `Status` giữ `draft` cho tới khi mọi màn có link frame đọc được, đã fetch. `/generate-bdd` FE/App sẽ **cảnh báo mềm** (đồng bộ Guard PRD) nếu sinh BDD khi design-spec chưa `approved`. Ghi `missing_frames = [screens]`. - Thêm một AI Assumption cho mỗi màn thiếu: "Không có Figma frame đọc được cho {screen} — spec của màn này chỉ là text và không được sign off cho tới khi thêm link `node-id`." --- ## CHECKPOINT ``` CHECKPOINT — Design Spec ------------------------- Target PRD : {prd-file-path} Platform : {active_platform} Module : {active_module} Service : {active_service} Domain : {domain} Screens : {N} — {screen_list ngăn cách bởi dấu phẩy} Figma : {linked}/{N} màn có link frame đọc được{; missing: missing_frames ngăn cách bởi dấu phẩy} Output path : {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md {Nếu missing_frames khác rỗng}: ⚠️ {count} màn không có link Figma frame đọc được — các màn này sẽ được sinh dưới dạng draft chỉ-text và spec không thể sign off cho tới khi thêm link node-id. Generate? (Y/N) ``` Chờ Y rõ ràng trước khi tiếp tục. --- ## Ngôn ngữ — Language Guard *(áp khi viết mọi section)* {{include:steps/business-language.md}} **Design Language Guard — phân tầng bề mặt (bổ sung cho guard trên):** Design Spec là cầu nối PRD → code, có **hai loại bề mặt** với ngôn ngữ khác nhau. Nguyên tắc: **không xoá chi tiết kỹ thuật — dồn về đúng tầng** (giống altitude AC/BR ở PRD). - **Tầng A — bề mặt đọc (BẮT ngôn ngữ nghiệp vụ/UX):** §1 Screen Inventory (mọi cột), §2 Layout, cột "Hành vi UI" của Screen States, Actions & Navigation, blockquote mục đích màn, §5 AC-UI. Mô tả theo **vai trò/ý đồ** ("thanh tiến độ", "nút chính", "trạng thái chưa chọn đáp án"). **CẤM ở tầng này:** tên layer/variant Figma (`Q1--Selected`, `Base Design`), mã token/màu hex/số đo px-pt (`Primary/500 #0876B1`, `padding 16px`), định danh code, và ẩn dụ dữ liệu (Nhóm 4 của guard trên: cờ/giá trị/đọc-ghi khi là artifact). - **Tầng B — cột/phụ lục kỹ thuật chuyên dụng (được giữ code):** Component Inventory (`Code Component`, `Import Path`), cột **Figma Frame** (link), bảng **Design Token** (phụ lục). Định danh Figma/code/token **chỉ** được xuất hiện ở đây. Một state mô tả ở tầng A bằng lời ("chưa chọn đáp án → nút vô hiệu"); tên variant Figma của state đó (nếu cần) nằm ở cột Figma Frame / Component Inventory, KHÔNG lẫn vào prose. ## Generation Rules Áp dụng các quy tắc này nhất quán khi sinh mọi section: **Component mapping (C.M — bắt buộc):** - Với mỗi component được tham chiếu, kiểm tra `figma-components/{active_module}.md` (đã nạp trong context). - ✅ Matched → dùng đúng `Code Component` và `Import Path` từ catalog. - ⚠️ Matched nhưng `[TODO]` → đánh dấu ô component là `[TODO — implementation pending]`. - ❌ Không có trong catalog → đánh dấu `[NEW — confirm with designer before generating code]`. - Không bao giờ bịa tên component hay import path. **Section thích ứng theo platform:** - Section 3 (Interaction Patterns) và Section 4 (Platform Considerations) thích ứng theo `active_platform`: - `web` → gồm responsive breakpoint, trạng thái hover/focus, keyboard navigation, accessibility. - `app` / `app-ios` / `app-android` → gồm gesture, safe area, touch target tối thiểu, navigation pattern, deep link, permission, hành vi offline. - Chỉ sinh section liên quan tới `active_platform`. Bỏ hẳn section của platform kia. **Figma grounding (bắt buộc):** - Với mỗi màn có frame đã fetch (`figma_frames[screen]` là link hợp lệ), dựa Layout, Component Inventory, và Screen States trên **dữ liệu Figma đã fetch** — tên component thật, token thật, cấu trúc frame thật. Đừng mâu thuẫn hay bịa layout. - Dùng đúng URL `figma_frames[screen]` từng-màn trong Screen Inventory, header mỗi Screen Spec, và Figma Summary — không bao giờ dùng fragment giả `{figma_url}#screen1`. - Với màn ❌ Missing: sinh draft chỉ-text từ PRD, thêm tiền tố vào Screen Spec `> [DRAFT — no Figma frame; do not sign off]`, và để ô Figma là ❌ Missing. **Screen states (bắt buộc mỗi màn):** - Mỗi màn phải mô tả tối thiểu: `default`, `loading`, `error`. - Thêm `empty` khi màn có thể hiển thị trạng thái không dữ liệu. - Thêm `success` khi một action hoàn tất tạo ra trạng thái xác nhận riêng biệt. - Nếu một state không áp dụng → đánh dấu `N/A` kèm lý do ngắn. --- ## Generate Ghi `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`: ````markdown # {TICKET-ID} {Feature Name} — Design Spec [{active_platform}] --- ## Metadata | Field | Value | |--------------------|---------------------------------------------------------------| | **Spec ID** | {TICKET-ID}-DS-{active_platform} | | **Version** | 1.0 | | **Status** | draft | | **Platform** | {active_platform} | | **Module** | {active_module} | | **Service** | {active_service} | | **Domain** | {domain} | | **Business PRD** | [{TICKET-ID}](../{TICKET-ID}-{prd-slug}.md) | | **Built from PRD** | v{prd_version — `\| **Version** \|` của PRD lúc sinh; dùng phát hiện drift} | | **Figma** | {figma_url — link file feature} ({linked}/{N} frame đã link) | | **Author** | {tên PO hoặc "AI-assisted"} | | **Created** | {YYYY-MM-DD} | | **Updated** | {YYYY-MM-DD} | --- # 1. Danh mục màn hình (Screen Inventory) > **Tầng A:** cột **Điểm vào** và **Ghi chú** viết bằng ngôn ngữ nghiệp vụ — mô tả điều kiện/ý đồ. KHÔNG liệt kê states, KHÔNG tên component/variant Figma (states thuộc §2; tên Figma thuộc cột Figma Frame / §2). Vd Điểm vào: "khi con *chưa làm khảo sát* và có ít nhất một câu hỏi" — KHÔNG "cờ tình trạng = `chưa làm`". | # | Tên màn hình | Điểm vào | Figma Frame | Ghi chú | |---|-------------|-------------|-------------|-------| | 1 | {Màn hình 1} | {điều kiện nghiệp vụ để vào màn — vd: "sau khi hoàn tất Nhập thông tin con và con chưa làm khảo sát"} | [Frame]({figma_frames[Screen 1]}) | {ghi chú nghiệp vụ nếu có — KHÔNG states/tên Figma} | | 2 | {Màn hình 2} | {điểm vào — ngôn ngữ nghiệp vụ} | [Frame]({figma_frames[Screen 2]}) / ❌ Missing | | --- # 2. Đặc tả màn hình (Screen Specs) ## Màn hình 1: {Tên màn hình} **Figma**: [{Tên frame}]({figma_frames[Screen 1]}) ### Layout {Mô tả layout theo CẤU TRÚC & Ý ĐỒ bằng lời: thứ tự section trên→dưới, vai trò từng vùng, hệ phân cấp thị giác, hành vi co giãn. **KHÔNG rải mã token / màu hex / số đo px** trong văn xuôi — số đo & token cụ thể đặt ở cột Component Inventory và bảng Design Token (phụ lục, Tầng B). Vd: "một cột dọc, thanh tiến độ ở đầu, khu nội dung chính giữa, nút hành động cố định đáy màn".} ### Component Inventory | Component (Figma) | Code Component | Import Path | States | Ghi chú | |---------------------|-----------------|------------------------|---------------------------------|--------------------| | {Figma/Button/Primary} | Button | @/components/ui/Button | default, loading, disabled | | | {Figma/Input/Text} | TextInput | @/components/ui/Input | default, focus, error, disabled | | | {Figma/Card/Order} | OrderCard | @/features/{domain}/components/OrderCard | default, skeleton | | ### Screen States | State | Trigger | Hành vi UI (mô tả quan sát được) | |-----------|---------------------------------------------|------------------------------------------------------| | default | Màn đã hiển thị, có dữ liệu | {Mô tả giao diện người dùng thấy} | | loading | Đang tải dữ liệu | {Vùng chờ / vị trí báo đang tải} | | error | Tải dữ liệu thất bại / dữ liệu không hợp lệ | {Thông báo lỗi + hành động khôi phục} | | empty | Không có dữ liệu để hiển thị | {Trạng thái trống + lời mời hành động} | | success | Thao tác hoàn tất (nếu có) | {Xác nhận / chuyển màn / đổi trạng thái} | ### Actions & Navigation | Action | Trigger | Kết quả | |-----------------|--------------------------------|-------------------------------------------------| | {Tên action} | Tap/click {tên phần tử} | Điều hướng tới {Màn hình N} / Mở {Tên modal} | | {Tên action} | Swipe trái trên {list item} | Hiện xác nhận xoá | | {Back / Cancel} | Cử chỉ back / nút Cancel | Quay lại {màn trước} mà không lưu | --- --- # 3. Pattern tương tác (Interaction Patterns) ## A. Hành vi Responsive *(chỉ web)* | Breakpoint | Width | Thay đổi layout | |------------|------------|----------------------------------------------------| | Mobile | < 768px | {1 cột, bottom navigation bar, CTA full-width} | | Tablet | 768–1279px | {grid 2 cột, sidebar thu gọn, tab navigation} | | Desktop | ≥ 1280px | {layout đầy đủ, sidebar hiển thị, max-width 1440px}| ## B. Hover / Focus / Keyboard *(chỉ web)* | Phần tử | Trạng thái Hover | Trạng thái Focus | Phím tắt | |----------------|-------------------------------|---------------------------------|-------------------| | Primary button | Background → {color.hover} | Outline 2px {color.focus} | Enter / Space | | Text input | Border → {color.border.hover} | Border → {color.primary}, label nổi | Tab to focus | | Dropdown | Highlight nền | Giống hover + ring | Phím mũi tên điều hướng | ## C. Cử chỉ & Điều hướng *(chỉ app)* | Cử chỉ | Màn / Phần tử | Hành vi | |-------------------|---------------------------|-------------------------------------------------------| | Cử chỉ back (iOS swipe-right / Android back) | Mọi màn | {Quay lại màn trước / Hiện dialog "Discard changes?"} | | Pull-to-refresh | {Tên màn} | Refresh dữ liệu, spinner ở trên cùng | | Swipe trái trên row | {Tên list item} | Hiện action {Delete / Archive} | | Long press | {Tên phần tử} | {Context menu / chế độ chọn} | | Pinch / zoom | {Image viewer} | Scale ảnh, double-tap để reset | ### Navigation Pattern *(chỉ app)* ``` {Vẽ navigation stack cho feature này, vd: BottomTab(Home) → FeatureListPage → FeatureDetailPage → EditPage BottomTab(Home) → FeatureListPage ↘ (modal) CreatePage } ``` Entry: {người dùng vào feature này thế nào — tab / deeplink / push từ màn khác} Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink out} ### Platform Conventions *(chỉ app)* | Khía cạnh | Hành vi iOS | Hành vi Android | |--------------------------|-----------------------------------------|-----------------------------------------| | Navigation bar | {Nút back trên-trái, title canh giữa} | {Mũi tên Up trên-trái, title canh trái} | | Sheet / bottom modal | {UISheetPresentation, hiện grabber} | {BottomSheet, drag handle} | | Alert / confirm dialog | {UIAlertController, action canh phải} | {Material AlertDialog, action canh trái}| | Loading indicator | {UIActivityIndicatorView, center} | {CircularProgressIndicator} | | Toast / snackbar | {Custom toast, bottom center} | {Material Snackbar, bottom} | --- # 4. Cân nhắc theo Platform (Platform Considerations) ## A. Accessibility *(chỉ web)* - [ ] Mọi phần tử tương tác tới được bằng phím Tab — không có keyboard trap - [ ] Focus trap bên trong modal dialog (Tab chỉ chạy vòng trong modal) - [ ] Nút chỉ-icon có `aria-label` mô tả hành động - [ ] Cập nhật nội dung động (loading → loaded) thông báo qua `aria-live` - [ ] Tương phản màu đạt WCAG AA: text ≥ 4.5:1, text lớn ≥ 3:1 - [ ] Input form có label hiển thị (không chỉ placeholder) - [ ] Message lỗi liên kết với input qua `aria-describedby` ## B. Thiết bị & OS *(chỉ app)* - [ ] Áp dụng safe area insets ở mọi màn — trên (status bar) và dưới (home indicator) - [ ] Touch target tối thiểu: 44×44pt (iOS) / 48×48dp (Android) - [ ] Đã test trên màn nhỏ: rộng 375pt (iPhone SE) / rộng 360dp (Android phổ biến) - [ ] Deep link entry: `{scheme}://{host}/{path}` → vào {tên màn} với {param} đã điền sẵn - [ ] Permission gate: {liệt kê permission cần — Camera / Location / Notification} - {Permission}: yêu cầu ở {tên màn} với copy lý do: "{copy TBD}" - [ ] Hành vi offline / không mạng: - {Tên màn}: hiện dữ liệu cache + banner offline - {Tên action}: disable nút, hiện tooltip "Requires connection" - [ ] Dark mode: mọi màn đã test dark mode — không có màu hardcode --- # 5. AC-UI — Tiêu chí chấp nhận về Design > Được **PO + Designer** cùng review và sign off trước khi sinh BDD. > Bổ sung cho (không thay thế) AC mức nghiệp vụ trong [Business PRD]({prd-path}). | ID | Tiêu chí chấp nhận | Verified by | |--------|--------------------------------------------------------------------------------|-----------------| | AC-UI1 | Mọi màn khớp frame Figma đã duyệt trong dung sai design-system | Designer | | AC-UI2 | Trạng thái đang tải xuất hiện gần như tức thì (≤200ms) khi màn bắt đầu tải dữ liệu | QA | | AC-UI3 | Mọi message lỗi đều hiển thị, rõ ràng, và kèm action khôi phục | PO | | AC-UI4 | Empty state có illustration và call-to-action rõ ràng | PO + Designer | | AC-UI5 | {Riêng platform — vd web: "Mọi màn pass kiểm tra tương phản WCAG AA"} | QA | | AC-UI6 | {Riêng platform — vd app: "Cử chỉ back ở mọi màn quay về đúng màn trước"} | QA | | AC-UI7 | {Tiêu chí UI riêng của feature từ section wireframe của Business PRD} | PO | --- # Appendix ## Tóm tắt Figma | Màn hình | Figma Frame | Trạng thái Link / Fetch | |-----------------|--------------------------------------|--------------------------------------| | {Màn hình 1} | [Link]({figma_frames[Screen 1]}) | ✅ Đã link & fetch | | {Màn hình 2} | — | ❌ Missing — không có link node-id | ## Design Token đã tham chiếu | Token | Value | Dùng ở | |-----------------------|---------------|---------------------------------| | `color.primary` | {#hex} | Primary button, link, active state | | `color.surface` | {#hex} | Nền card | | `spacing.md` | {16px / 4} | Khoảng cách dọc tiêu chuẩn | | `typography.heading2` | {font/size} | Title màn hình | ## Tài liệu tham khảo - [{TICKET-ID}]({prd-path}) — Business PRD (nguồn của AC, UC, BR) - {[Design Spec khác](./other-ds.md) — nếu feature này dùng chung màn} ## Giả định AI > Mỗi giả định dưới đây được đưa ra vì input PO chưa đầy đủ. > PO phải review và confirm trước khi sign-off. - {Giả định 1 — [AI DRAFT]} - {Một dòng cho mỗi màn ❌ Missing: "Không có Figma frame đọc được cho {screen} — draft chỉ-text; chặn sign-off cho tới khi thêm link node-id."} --- ## Changelog | Version | Date | Changes | |---------|--------------|-----------------| | 1.0 | {YYYY-MM-DD} | Initial version | ```` --- ## Self-Review Gate *(cổng tự-rà — bắt buộc chạy trước khi ghi)* - [ ] Mọi màn trong Screen Inventory có Screen Spec đầy đủ ở Section 2 - [ ] Mọi màn có tối thiểu các state: default, loading, error - [ ] Mọi component Figma đã map trong Component Inventory — chưa map thì gắn cờ `[NEW]` hoặc `[TODO]` - [ ] Chỉ sinh section liên quan platform ở Section 3 (không có section web trong doc app, và ngược lại) - [ ] Chỉ sinh section liên quan platform ở Section 4 - [ ] Các mục AC-UI testable (pass/fail rõ ràng, không phải "looks good") - [ ] Link cross-reference Business PRD là relative path hợp lệ - [ ] Mọi màn có link Figma frame node-level (`?node-id=`) — và các màn có link đã được fetch qua Figma MCP và dùng để ground spec - [ ] Mỗi màn ❌ Missing được gắn cờ trong spec (`> [DRAFT — no Figma frame...]`), liệt kê trong Figma Summary, và có một AI Assumption - [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` (generate-bdd FE/App cảnh báo mềm, không chặn cứng) - [ ] **Ngôn ngữ Tầng A sạch:** không tên layer/variant Figma, mã token/hex/px, hay ẩn dụ dữ liệu (cờ/giá trị/đọc-ghi khi là artifact) lọt vào §1, Layout, Screen States, Actions, AC-UI — định danh kỹ thuật chỉ ở Component Inventory / Design Token / cột Figma. Backtick không bọc giá trị nghiệp vụ. Khái niệm đã có trong business-dictionary dùng đúng term chuẩn. > **Đây là CỔNG, không phải nhắc nhở:** chạy từng mục trên TRƯỚC khi ghi file. Mục nào **FAIL** → **bắt buộc**: > 1. ghi một dòng `⚠️ {mục thiếu — màn/section cụ thể}` vào section **"Giả định AI"** của file (đừng để lọt im lặng), VÀ > 2. giữ `| **Status** | draft |` (chưa đủ điều kiện để PO+Designer sign-off `approved`). > KHÔNG xuất design-spec như "hoàn chỉnh" khi còn mục fail chưa gắn cờ. --- ## Output {{include:steps/report-footer.md}} {Nếu missing_frames rỗng}: ``` /generate-design-spec Hoàn tất — {TICKET-ID} [{active_platform}] --- Status : ✅ Complete — cả {N} màn đã link & fetch từ Figma Output Artifacts: created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md (v1.0) Next : Chia sẻ với Designer → PO + Designer sign-off (Status: approved) → /generate-bdd {prd-file} (sinh BDD theo service; đọc AC-UI từ Design Spec) ``` {Nếu missing_frames khác rỗng}: ``` /generate-design-spec Hoàn tất (DRAFT) — {TICKET-ID} [{active_platform}] --- Status : ⚠️ Warnings — {count} màn không có link Figma frame đọc được: {missing_frames ngăn cách bởi dấu phẩy} Output Artifacts: created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md (v1.0, draft) Next : 🔒 Khuyến nghị hoàn tất sign-off trước (đủ link Figma node-id); /generate-bdd FE/App sẽ cảnh báo nếu design-spec chưa approved. 1. Trong Figma: chọn mỗi frame còn thiếu → chuột phải → Copy link to selection 2. Chạy lại /generate-design-spec {prd-file} → AI fetch & ground các frame mới ```