---
description: 🎨 GUI Assets Workflow — Quy trình tạo bộ icon, nút bấm, HUD, và ghép atlas GUI đồng bộ chất lượng cao
alwaysApply: false
category: workflow
priority: medium
---
triggers:
  - "keywords: generate gui assets, gui icons, app icon set, icon atlas, ui icon pack"
  - "context: UI assets creation, icon generation, atlas assembly"
version: 1.0.0
track:
  - quick
  - method
---

# /generate-gui-assets — GUI Asset Pack Generation Workflow

Quy trình này hướng dẫn cách lập kế hoạch, tạo hàng loạt và hậu kỳ xử lý bộ GUI assets (nút, icon, status badges, HUD...) đồng bộ phong cách trên một canvas/atlas đồng nhất.

---

## 📋 Chuẩn Bị & Chọn Canvas Grid

Trước khi khởi chạy, xác định tổng lượng icon cần tạo để chọn kích thước lưới thích hợp. Lưới đồng nhất giúp AI căn giữa tốt và cho phép cắt ảnh tự động chính xác:

- **8x6** (48 slots): Lượng icon lớn nhất, tối ưu chi phí sau khi style đã được duyệt.
- **6x6** (36 slots): Canvas vuông, thoáng.
- **4x4** (16 slots): Lựa chọn ưu tiên chất lượng và độ tách biệt cao.
- **3x3** (9 slots): Phù hợp chạy thử (Preview) hoặc precision fallback.

Sử dụng tool gợi ý lưới:
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/suggest_grid_options.py \
  --icon-count <lượng_icon> \
  --strategy throughput
```

---

## ⚡ Các Bước Thực Hiện

### Bước 1: Chạy Thử Tạo Phong Cách (Preview Phase)
Luôn khởi chạy một pack nhỏ (Preview) để duyệt phong cách hình ảnh trước khi tạo hàng loạt (Bulk):
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/prepare_gui_asset_run.py \
  --run-id gui-v1-preview \
  --output-root "assets/ui/generated" \
  --phase preview \
  --style-notes "cozy mobile wellness garden icons, crisp rounded vector style, soft gradient" \
  --pack "ui_weather_core:3x3:sun,sunCloud,cloud,rain,wind,hot,mild,good,bad"
```

### Bước 2: Sinh Ảnh Preview & Nhận Phản Hồi
- Đọc file prompt tại `assets/ui/generated/gui-v1-preview/prompts/`.
- Thực thi `$imagegen` để tạo ảnh atlas thô. Save ảnh vào `raw/` và ghi nhận provenance.
- Tạo contact sheet để xem trước và QA:
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/build_gui_contact_sheet.py \
  --run-dir "assets/ui/generated/gui-v1-preview"
```
*(Trong Goal Mode, bước duyệt này sẽ tự động thông qua).*

### Bước 3: Tạo Hàng Loạt (Bulk Phase)
Sau khi style được chấp thuận, khóa ngôn ngữ mô tả style lại và khởi chạy bulk run cho các pack còn lại:
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/prepare_gui_asset_run.py \
  --run-id gui-v1-bulk \
  --output-root "assets/ui/generated" \
  --phase bulk \
  --style-notes "<approved preview style notes>" \
  --pack "ui_nav:4x3:home,garden,profile,settings,search,back,next,add,close,alert" \
  --pack "ui_health:4x3:heart,water,sleep,steps,mood,warning,aid,trend"
```
- Chạy sinh ảnh hàng loạt qua `$imagegen` và record kết quả.
- Xác thực catalog:
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/validate_gui_catalog.py \
  --run-dir "assets/ui/generated/gui-v1-bulk"
```

### Bước 4: Tách Icon & Khử Viền Màu Nền (Edge Cleanup)
Khi đã crop và phân tách các icon thành file ảnh PNG có alpha channel, chạy công cụ khử viền màu nền (thường là màu hồng `#FF00FF` hoặc xanh lá `#00FF00` được dùng làm chroma-key):
```bash
# 1. Chạy dry-run kiểm tra
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/clean_chroma_edges.py \
  "assets/ui/generated/gui-v1-bulk/final/icons" --edge-despill

# 2. Áp dụng làm sạch
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/clean_chroma_edges.py \
  "assets/ui/generated/gui-v1-bulk/final/icons" --edge-despill --apply
```

### Bước 5: Đưa Vào Dự Án (Promote)
Sao chép các icon sạch và manifest sang thư mục chính của dự án:
```bash
python ~/.gemini/antigravity/skills/generate-gui-assets/scripts/copy_approved_icons.py \
  --source-dir "assets/ui/generated/gui-v1-bulk/final/icons" \
  --run-dir "assets/ui/generated/gui-v1-bulk" \
  --mapping "assets/ui/generated/gui-v1-bulk/catalog.json"
```
Đưa các icon đã phân loại vào `assets/ui/icons/` và dọn dẹp các thư mục staging run.

---

## 🔍 QA Checklist

- [ ] Catalog.json hợp lệ và chứa đủ thông tin nguồn gốc.
- [ ] Không sử dụng shadow rời, glow loang lổ bên ngoài nét vẽ của icon.
- [ ] Mọi icon căn giữa tốt, không chạm viền cell, không bị cắt cụt.
- [ ] Nền trong suốt hoàn toàn, không bám viền màu nền cũ khi hiển thị trên cả nền sáng và tối.
- [ ] Code ứng dụng tham chiếu đúng đường dẫn canonical (`assets/ui/...`), không trỏ tới run staging.