codex-frontend

name	codex-frontend
description	Codex 前端類 Use Case 技能。涵蓋響應式 UI 實作、瀏覽器遊戲開發、 Figma 設計轉碼等工作流。觸發條件：當需要使用 Codex 進行前端 UI 開發、視覺驗證、遊戲建構、設計稿轉碼時啟用。

Front-end — Codex Use Cases Skill

概述

前端類包含 3 個 use case，覆蓋從 UI 實作到瀏覽器遊戲的完整前端開發場景。 核心特色是使用 Playwright 進行自動化視覺驗證。

本分類包含：

• frontend-designs — 從截圖/設計稿實作響應式 UI
• browser-games — 使用 Next.js + 遊戲引擎建構瀏覽器遊戲
• figma-designs-to-code — 透過 Figma MCP 將設計轉為程式碼

---

Use Case 1: Build responsive front-end designs

工作流程

步驟	動作	說明
1	檢查截圖	view_image 分析設計
2	提取設計系統	色彩、字型、間距
3	盤點元件	重用現有元件
4	建構 Layout	Mobile-first 響應式
5	細節實作	動畫、互動狀態
6	Playwright 驗證	多斷點截圖比對

推薦 Prompt

Role: You are a senior front-end engineer with pixel-perfect UI skills.
Context: Implementing the UI from {{screenshot_reference}} in the {{framework}} project.

Task:
1. Inspect the screenshot with `view_image`:
   - Extract the color palette (primary, secondary, accent, background, text).
   - Identify typography (font family, sizes, weights, line heights).
   - Map spacing system (padding, margin, gap patterns).
2. Audit existing project components — reuse before creating new ones.
3. Build the layout:
   - Start with mobile layout (min-width: 320px).
   - Add tablet breakpoint (768px).
   - Add desktop breakpoint (1024px+).
   - Use CSS Grid/Flexbox — no absolute positioning unless required.
4. Match visual details:
   - Exact border-radius, shadows, and opacity values.
   - Hover/focus/active states for interactive elements.
   - Smooth transitions (200-300ms ease).
5. Validate with Playwright:
   - Take screenshots at 375px, 768px, 1440px widths.
   - Visual regression test against the reference.

Constraints:
- Prefer existing design tokens/CSS variables over hardcoded values.
- All interactive elements must be keyboard accessible.
- Images must have alt text.
- No inline styles — use class-based styling.

Output Format:
- Implemented component(s) matching the reference.
- `screenshots/` — Playwright captures at 3 breakpoints.
- Brief diff notes if any deviation from reference was necessary.

Self-Verification:
Run Playwright screenshots at all 3 breakpoints.
Visually compare each against the reference.
Check Lighthouse accessibility score > 90.

Tips & 注意事項

1. 截圖品質: 提供越清晰的截圖，Codex 實作越精準
2. Design Token: 如果專案有 CSS variables，告訴 Codex 使用它們
3. Playwright 驗證: 自動截圖比手動比對更可靠
4. 常見陷阱: overflow hidden 會隱藏元素、不同字型的 line-height 差異

---

Use Case 2: Create browser-based games

工作流程

步驟	動作	說明
1	規劃	撰寫 PLAN.md
2	選引擎	Phaser 3 或 PixiJS
3	搭建專案	Next.js + 遊戲引擎
4	核心迴圈	輸入 → 更新 → 渲染
5	遊戲機制	計分、碰撞、進度
6	UI 層	HUD、選單、結算
7	打磨	粒子、震動、音效
8	測試	Playwright 里程碑驗證

推薦 Prompt

Role: You are a game developer specializing in browser-based games with Phaser/PixiJS.
Context: Building a {{game_genre}} game called "{{game_name}}".

Task:
1. Planning Phase:
   - Draft `PLAN.md` with: game concept, core mechanics, art style, technical architecture, milestone list.
   - Choose engine: Phaser 3 (2D with physics) or PixiJS (lightweight rendering).
   - Define the game loop: update → render → input handling cycle.

2. Setup Phase:
   - Scaffold Next.js project with chosen engine.
   - Configure asset pipeline (sprites, audio, fonts).
   - Set up hot-reload for rapid iteration.

3. Build Phase (iterate in this order):
   a. Core game loop — player input + basic rendering.
   b. Game mechanics — scoring, collision, progression.
   c. UI layer — HUD, menus, game over screen.
   d. Polish — particles, screen shake, sound effects.
   e. Use $imagegen to generate sprite assets when needed.

4. Test at each milestone:
   - Use Playwright to validate: game loads, input responds, score updates.
   - Performance check: 60fps on mid-range hardware.

Constraints:
- Target 60fps minimum for all animations.
- All game state must be serializable (for save/load).
- Use requestAnimationFrame — never setInterval for game loop.
- Assets must be < 5MB total for fast loading.

Output Format:
- Playable game at localhost:3000.
- PLAN.md with architecture decisions.
- README.md with play instructions and controls.

Self-Verification:
Open the game in browser, play through one complete cycle.
Use Playwright to take a gameplay screenshot for verification.

AGENTS.md 配置

# Browser Game Conventions

## Build & Run
- `npm run dev` — start dev server
- `npm run build` — production build
- `npm run test` — Playwright tests

## Conventions
- Source layout: `src/game/` for engine code, `src/components/` for UI
- Use ECS pattern for game entities
- All assets in `public/assets/`
- Game state must be serializable to JSON

## Testing
- Playwright E2E for each milestone
- Manual playtest after core loop changes

Tips & 注意事項

1. PLAN.md 先行: 不先規劃就寫程式碼會浪費大量迭代
2. 引擎選擇: Phaser 有內建 physics → 適合平台/碰撞；PixiJS 更輕量
3. $imagegen: 可以用 AI 生成 sprite，但風格一致性需要注意
4. 效能: 60fps 是底線，複雜場景注意 object pooling

---

Use Case 3: Turn Figma designs into code

工作流程

步驟	動作	說明
1	取得設計數據	get_design_context
2	映射 metadata	get_metadata（如需要）
3	截圖參考	get_screenshot
4	分析設計系統	Token 映射
5	實作 UI	Mobile-first
6	視覺驗證	Playwright 多斷點比對

推薦 Prompt

Role: You are a front-end engineer converting Figma designs to production code.
Context: Implementing Figma frame {{figma_node_id}} from file {{figma_file_key}} in this {{framework}} project.

Task:
1. Fetch Design Data:
   - Call `get_design_context` for the target node/frame.
   - If response is truncated, use `get_metadata` then re-fetch specific nodes.
   - Run `get_screenshot` for the exact variant before coding.

2. Analyze Design System:
   - Extract: colors, typography, spacing tokens.
   - Map to existing project design tokens / CSS variables.
   - Identify reusable components already in the codebase.

3. Implement:
   - Build mobile-first (320px → 768px → 1024px+).
   - Reuse existing design system components — do NOT create a parallel system.
   - Translate Figma auto-layout to CSS Grid/Flexbox.
   - Use Figma's localhost image/SVG sources directly — no placeholders.

4. Validate:
   - Side-by-side comparison: Playwright screenshot vs Figma reference.
   - Check at 3 breakpoints.
   - Iterate until visual match is satisfactory.

Constraints:
- Never invent new icon packages — use Figma-provided SVGs.
- All interactive elements must have hover/focus/active states.
- Keyboard accessibility required.
- Respect existing code conventions.

Output:
- Implemented component(s) matching the Figma design.
- `validation/` — Playwright screenshots at 3 breakpoints.
- `design_mapping.md` — How Figma tokens mapped to project tokens.

Tips & 注意事項

1. Figma MCP: 必須安裝 Figma MCP server 才能使用
2. 截斷處理: 大型設計檔案會被截斷，需用 get_metadata 分批取
3. SVG 處理: Figma 返回的 localhost SVG 直接使用，不要替換
4. 2px 容差: 間距允許 2px 偏差，顏色需精確

常見問題

Q: Playwright 截圖怎麼比對？

Codex 會自動產出不同斷點截圖，與 Figma get_screenshot 的結果並排比較。

Q: Phaser vs PixiJS 怎麼選？

• Phaser 3: 有 Arcade/Matter physics, scenes, cameras — 適合大部分 2D 遊戲
• PixiJS: 純渲染引擎，更小更快 — 適合需要自訂 physics 或非典型遊戲

技術棧速查

技術	用途	相關 Use Case
Playwright	視覺驗證	全部
React	UI 框架	frontend-designs
Next.js	遊戲專案框架	browser-games
Phaser 3	遊戲引擎	browser-games
PixiJS	渲染引擎	browser-games
Figma MCP	設計轉碼	figma-designs-to-code
CSS Grid/Flexbox	Layout	frontend-designs, figma-designs-to-code