Layout

🏗️ Layout Workflow — Text + Screen Spec → Layout Tree

Kích hoạt

Workflow này được kích hoạt khi:

• User gửi text prompt mô tả 1 screen cần build
• User gửi / reference file .md chứa screen spec (ví dụ screen-specs.md)
• User yêu cầu "build screen", "tạo layout", "sinh layout tree", "layout cho màn hình X"
• Bất kỳ yêu cầu nào liên quan đến chuyển mô tả → cấu trúc giao diện

📋 Input: Text prompt + (optional) screen consumer .md file 📤 Output: Layout Tree + Elevation Map + DS Component Mapping + HTML skeleton

Step 0: Reconcile Screen Spec — So sánh + mapping .md → chuẩn Prisma

LUÔN CHẠY — không skip.

• .md thô (chưa có Elevation Map) → tạo mapping mới từ đầu.
• .md đã có Elevation Map + DS Mapping → so sánh với DS hiện tại → sửa sai, bổ sung thiếu, cập nhật deprecated.

Reconciliation modes:

0a. Load DS Inventory

// turbo

SCAN: design-system/components md/*.md → danh sách 47 components
READ: knowledge/slot-manifest.json → slot contracts per component
READ: knowledge/stacking-design-methodology.md §2 → 4-tier rules

Component Inventory (auto-scan):

0b. Parse Raw Screen .md

Đọc file .md thô → trích xuất:

0c. Map Elements → DS Components

Cho mỗi UI element tìm được, match với DS component:

Quy tắc matching:
1. Keyword match   → "input", "search bar", "ô nhập" → input.md
2. Pattern match   → "[← Back]" → app-bar.md (with back action)
3. Behavior match  → "dropdown", "chọn" → select.md
4. Fallback        → Không match → đánh dấu ⚠️ UNMAPPED

0d. Assign Tier Hierarchy

Cho mỗi element, assign tier theo nesting depth + vai trò:

Page wrapper            → block    (--block-*)
  Content section       → section  (--section-*)  — optional, dùng khi có >1 group
    Card / Panel        → module   (--module-*)
      Button / Input    → item     (--item-*)

Decision rules:

0e. Generate Elevation Map Stub

Từ tier assignments, auto-generate Elevation Map:

0f. Output: Reconciled Screen Spec

Output LUÔN gồm 3 phần — dù input thô hay đã có mapping:

#### Elevation Map (Reconciled)

| Element | Layer | CSS Class | Token Contract | Status |
|---------|-------|-----------|----------------|--------|
| Page | Ground | `ground-page` | `bg: --background`, `fg: --foreground` | ✅ |
| App bar | Ground | `ground-appbar` | `bg: --background`, sticky top | 🔧 FIX: was `card-appbar` |
| ... | ... | ... | ... | ✅ / 🆕 / 🔧 |

#### UI Components — DS Mapping (Reconciled)

| # | Component | DS Spec | Variant / Size | Notes | Status |
|---|-----------|---------|----------------|-------|--------|
| 1 | Input SĐT | `input.md` | Default / lg | — | ✅ |
| 2 | OTP Input | `otp-input.md` | 6 digits | Was missing | 🆕 ADD |
| 3 | Alert | `alert.md` | Destructive | Was `toast.md` → sửa | 🔧 UPDATE |

#### Reconciliation Summary

| Action | Count | Details |
|--------|:-----:|---------|
| ✅ Unchanged | N | Mapping đúng chuẩn |
| 🆕 Created | N | Elements chưa có mapping |
| 🔧 Fixed | N | Sai tier / CSS prefix / component ref |
| 📦 Updated | N | Component spec outdated → remapped |
| ⚠️ Flagged | N | Không có DS component → cần quyết định |
| 🔄 Migrated | N | Token cũ → token mới |

[!IMPORTANT] Step 0 đảm bảo mọi .md đi vào pipeline đều chuẩn Prisma — không phân biệt input mới hay cũ. Reconciliation summary cho thấy rõ những gì thay đổi.

Step 1: Parse Intent — Trích xuất ý đồ

Đọc text prompt + file .md (nếu có) → trích xuất các thông tin sau:

Nếu input là screen spec .md:

Trích xuất từ format chuẩn 7 phần:

1. Layout (wireframe)
2. Elevation Map (nếu đã có)
3. DS Component Mapping (nếu đã có)
4. Data Binding
5. API Calls
6. Rules & Validation
7. Error States

Step 2: RAG Lookup — Truy vấn knowledge

2a. Problem Router (Layer 1)

// turbo

READ: knowledge/problem-taxonomy.json

• Match screen type → category (A/B/C/D/E/F) + subtype
• Lấy ra:
  • blueprint ID (PP-001 → PP-010)
  • decision_trees IDs (DT-001 → DT-020)
  • components list
  • stacking formula
  • ux_rules (critical + important)
  • source_files references

2b. Blueprint Registry (Layer 3)

// turbo

READ: knowledge/page-patterns.json[blueprint_id]

Từ blueprint lấy:

• Stacking structure (ASCII + detailed node tree)
• Token map (layout tokens, spacing tokens, typography tokens)
• UX checklist (critical + important rules)
• Responsive strategy (mobile/tablet/desktop)
• HTML skeleton (nếu có)

2c. Decision Engine (Layer 2) — nếu cần

// turbo

READ: knowledge/decision-trees.json[DT-xxx]

Walk decision tree khi cần quyết định:

• Tabs vs Accordion vs List-Group? → DT-001
• Bottom Nav vs Sidebar? → DT-002
• Breadcrumb vs Back? → DT-003
• Modal vs Dialog vs Drawer? → DT-005
• Card vs List vs Table? → DT-007
• etc.

Step 3: Apply Layout Rules — Áp dụng quy tắc

3a. 4-Tier Hierarchy

// turbo

READ: knowledge/stacking-design-methodology.md

Cho mỗi element, xác định:

3b. Layout Pattern

Cho mỗi tier container, chọn pattern:

3c. Elevation Mapping

// turbo

READ: knowledge/css-naming-convention.md

Map mỗi element → elevation prefix:

3d. Slot Anatomy (nếu có slotted components)

Xác định slot structure:

• slot-header / slot-header-clean
• slot-body / slot-body-flush / slot-body-compact
• slot-footer / slot-footer-clean / slot-footer-between

3e. Token Resolution

// turbo

READ: knowledge/token-recommender.json (nếu cần lookup token cụ thể)
READ: design-system/tokens/shared/layout.tokens.json (container/sidebar tokens)

Resolve tokens cho:

• Container: max-width, padding-inline
• Spacing: --{tier}-stack-gap-{size}, --{tier}-inline-gap-{size}
• Radius: --{tier}-radius-{size}
• Typography: --text-style-heading-{n}, --font-size-{size}

Step 4: Generate Layout Tree — Xuất cấu trúc

Output format BẮT BUỘC gồm 4 phần:

4a. ASCII Tree (Stacking Structure)

Block: .layout-{pattern}
├── Header: component (sticky/fixed)
├── Main: .container-block .layout-block-stack
│   ├── Section "Label": .layout-section-{pattern}
│   │   ├── Module: component-name (.container-module)
│   │   │   ├── Item: button/input
│   │   │   └── Item: button/input
│   │   └── Module: component-name
│   └── Section "Label": .layout-section-{pattern}
│       └── Module: component-name
└── Footer: component (fixed bottom)

4b. Elevation Map

4c. DS Component Mapping

4d. Token Resolution Table

Step 5: Render with Design System

5a. HTML Skeleton

Sinh HTML sử dụng:

• Utility classes: .layout-{tier}-{pattern}, .container-{tier}
• Elevation prefix: ground-, card-, surface-
• Slot classes: .slotted, .slot-header, .slot-body, .slot-footer
• Token references: var(--token-name)

5b. Responsive Strategy

Áp dụng density mode switching (KHÔNG media queries):

// Auto-switch density based on viewport
function adaptDensity() {
  const width = window.innerWidth;
  const mode = width < 640 ? 'compact' 
             : width < 1024 ? 'default' 
             : width < 1536 ? 'comfortable' 
             : 'spacious';
  document.documentElement.setAttribute('data-style-mode', mode);
}

5c. UX Checklist Validation

Từ blueprint ux_checklist, validate:

• Critical rules (PHẢI pass)
• Important rules (NÊN pass)

// turbo

READ: ux-research SKILL.md (nếu cần chi tiết rule)

5d. Icon Audit (IC-1/IC-2/IC-3 — MANDATORY)

Every icon element MUST use SVG. Scan generated HTML for text icons and replace:

• ✕ / × → <svg class="icon--sm" aria-hidden="true"><use href="#ic-x"/></svg>
• ▼ / ▾ → CSS transform: rotate(180deg) on chevron SVG, or <use href="#ic-chevron-down"/>
• → / › → <svg class="icon--sm"><use href="#ic-chevron-right"/></svg>
• ← / ‹ → <svg class="icon--sm"><use href="#ic-chevron-left"/></svg>
• ↑ / ↓ → <svg class="icon--sm"><use href="#ic-arrow-up"/></svg> / #ic-arrow-down
• + (as icon) → <svg class="icon--sm"><use href="#ic-plus"/></svg>

Gate: ux-review.js will now FAIL pipeline if text icons are found in HTML.

Cross-references

Run After

• /post-change — validate files changed
• /dev-journal — log layout generation activity