| 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 & 注意事項
- 截圖品質: 提供越清晰的截圖，Codex 實作越精準
- Design Token: 如果專案有 CSS variables，告訴 Codex 使用它們
- Playwright 驗證: 自動截圖比手動比對更可靠
- 常見陷阱: 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 & 注意事項
- PLAN.md 先行: 不先規劃就寫程式碼會浪費大量迭代
- 引擎選擇: Phaser 有內建 physics → 適合平台/碰撞；PixiJS 更輕量
- $imagegen: 可以用 AI 生成 sprite，但風格一致性需要注意
- 效能: 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 & 注意事項
- Figma MCP: 必須安裝 Figma MCP server 才能使用
- 截斷處理: 大型設計檔案會被截斷，需用 get_metadata 分批取
- SVG 處理: Figma 返回的 localhost SVG 直接使用，不要替換
- 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 |
