interface:
  display_name: "Three.js Game UI Designer"
  short_description: "Design premium Three.js game UI"
  default_prompt: "Load threejs-game-ui-designer/SKILL.md (try ~/.codex/skills/threejs-game-ui-designer/SKILL.md, then ~/.claude/skills, ~/.agents/skills, or repo skills/) and follow it exactly. Non-negotiables: load the UI patterns reference first; report the reference ledger plus UI state, text-fit, safe-area, and touch-target evidence."

# Game UI Quality Checklist

- The first screen is the playable game or a deliberate modal state, not a landing page.
- HUD hierarchy matches gameplay priority: survival/status, objective, feedback, secondary flavor.
- UI visual language matches the game's genre, world materials, color, and motion.
- Menus include expected states: pause, resume, restart, settings, win/lose when relevant.
- Buttons and controls have stable dimensions plus hover, pressed, focus, and disabled states.
- Icons are used for compact tool/actions when recognizable; ambiguous icons have labels or tooltips.
- UI does not use nested cards, marketing-page layout, or generic dashboard styling.
- UI does not block player, threats, goals, interactables, or near-future path unless intentionally modal.
- Dynamic values such as score, time, health, combo, and ammo do not shift layout.
- Reduced-motion and flash risk is considered for intense UI animation or damage feedback.
- UI state is driven by the game state model and does not duplicate simulation rules.
- Desktop and mobile screenshots show coherent composition and no clipped or overlapping controls.

# HUD Readability Checklist

- Player health/status is readable during normal movement and high-action moments.
- Objective/progress information is visible without competing with threats or pickups.
- Text contrast remains legible over bright, dark, and moving scene backgrounds.
- Critical status changes have at least two feedback channels when useful: shape, color, motion, sound, or text.
- Meters, timers, and counters have fixed-width or stable containers.
- HUD placement avoids the player focal area and likely spawn/threat lanes.
- HUD scale is appropriate for desktop, laptop, and mobile viewports.
- Touch controls and HUD elements do not overlap each other.
- UI transitions do not delay input response or hide the next player decision.
- Screenshot review confirms HUD readability before and after interaction.

# Mobile Input Checklist

- Include `<meta name="viewport" content="width=device-width, initial-scale=1.0">`.
- Set canvas and touch overlays to `touch-action: none` only where needed.
- Use Pointer Events when possible.
- Keep controls reachable with thumbs and away from safe-area edges.
- Avoid tiny text or buttons below practical touch size.
- Verify portrait and landscape if both are supported.
- Check high-DPR canvas scaling and cap DPR if performance suffers.
- Prevent page scroll/zoom gestures from stealing gameplay input.
- Test virtual joystick/button release paths when the pointer leaves the control.
- Verify with Playwright mobile emulation and real hardware when available.

# Responsive UI Fit Checklist

- Desktop, laptop, narrow, and mobile viewports have been checked.
- Safe-area padding is applied for mobile edges and notches when controls sit near edges.
- No text clips, overflows, overlaps, or becomes unreadably small.
- Long labels wrap or compress intentionally without breaking button height.
- Controls keep stable hit targets and do not shift during score/time/state changes.
- Layout uses grid/flex/container-aware constraints instead of viewport-only guesses where practical.
- Menu content remains reachable without hidden offscreen controls.
- Touch controls are large enough, separated enough, and do not trigger page scroll.
- Canvas resizing does not desynchronize HUD placement from gameplay framing.
- Screenshots or Playwright artifacts prove fit at the tested sizes.

# Three.js Game UI Prompt Templates

Reusable prompt templates packaged with this skill. Use only templates relevant to the current request, and adapt placeholders to the game/project context.

---

# Premium HUD/UI Pass Prompt

Use `threejs-game-ui-designer` to make this Three.js game's HUD and in-game UI feel premium, readable, and genre-specific.

Context to gather:
- Current screenshots at desktop and mobile sizes.
- Game genre, core verb, target mood, and player decisions the HUD must support.
- Current HUD/menu files, game state sources, input model, and touch controls.

Design goals:
- Keep the playable game as the first screen.
- Make survival/status/objective information readable during motion.
- Use stable dimensions for counters, buttons, meters, and labels.
- Use icons where they reduce clutter, with labels where meaning is ambiguous.
- Match the game's world materials, color, typography, and feedback language.

Constraints:
- Do not add marketing-page hero sections or explanatory feature copy.
- Do not nest cards inside cards.
- Do not let UI cover critical gameplay at desktop or mobile sizes.
- Avoid text overflow, clipped controls, layout shift, and generic dashboard styling.

Verification:
- Build and run locally.
- Capture desktop and mobile screenshots.
- Check console/page errors.
- Verify text fit, no overlap, no clipped controls, and at least one UI state change from real input.

---

# Responsive Game Menu Pass Prompt

Use `threejs-game-ui-designer` to design or improve this Three.js game's pause, start, settings, win, lose, or restart menus.

Menu states needed:
- 

Target devices/orientations:
- 

Requirements:
- Menus must feel like part of the game, not a website overlay.
- Modal menus may pause or dim gameplay, but should not look like marketing cards.
- Buttons need clear hover, pressed, focus, disabled, and touch states.
- Settings must use appropriate controls: toggles, sliders, segmented controls, icon buttons, and select menus.
- Layout must respect safe-area insets and remain usable on mobile.

Implementation notes:
- Prefer semantic HTML/CSS over canvas-rendered UI unless 3D placement is required.
- Keep UI state driven by the game state model.
- Keep dimensions stable so labels and counters do not shift layout.

Verification:
- Test every menu state.
- Capture desktop and mobile screenshots.
- Check keyboard/mouse and touch paths when both are supported.
- Confirm no text overflow, overlap, clipping, or unreachable controls.

# Game UI Patterns

Use this when designing HUDs, menus, overlays, pause/fail/win states, touch controls, typography, responsive layout, and UI/world cohesion.

## UI Principles

- Build the game interface, not a web dashboard.
- Prioritize gameplay hierarchy: survival/status, objective/progress, immediate feedback, then flavor.
- Use meters, icons, reticles, badges, alert strips, cooldown rings, inventory slots, minimaps, diegetic labels, and compact clusters before generic stat cards.
- Keep UI outside the play path and away from threats, pickups, the player, and the next decision.
- UI should reinforce the world art direction through material cues, color roles, icon shapes, and motion language.
- Do not use visible text to explain obvious controls when an icon, affordance, or direct interaction can do the job.

## Required States

Inventory states before designing:

- Gameplay HUD.
- Pause/resume.
- Settings or audio/accessibility controls when useful.
- Fail/retry.
- Win/milestone/level complete when relevant.
- Loading/empty/error when async assets exist.
- Mobile/touch controls when target includes mobile.
- Debug/tuning UI gated separately from player UI.

Premium games should not have only one HUD state.

## HUD Composition

Use intentional zones:

- Top or top-left: objective, wave, distance, timer, route/progress.
- Top or top-right: score, currency, combo, inventory, pause.
- Bottom left/right: touch movement/action controls when needed.
- Center top or near player: short event banners, combo, warnings.
- Near-world labels: diegetic prompts, target markers, offscreen indicators.

Rules:

- Use fixed-width numeric containers for score, timer, ammo, speed, health, and best values.
- Use icons plus short labels for unfamiliar resources.
- Use meter fills for quantities the player must read quickly.
- Use alert colors consistently: danger, reward, shield, boost, objective, disabled.
- Animate state changes briefly: count-up, meter fill, pulse, slide/fade, snap, ring cooldown.
- Do not stack multiple large banners over the play path.

## Menus And Overlays

Pause/fail/win overlays should support quick action:

- Primary action first: resume, retry, continue, next.
- Secondary actions: settings, quit, restart, level select.
- Avoid marketing-page hero layouts inside a game.
- Keep menu panels stable and readable across desktop/mobile.
- Use icon buttons for pause, sound, restart, fullscreen, settings when familiar.
- Provide focus/hover/pressed/disabled states.
- Gate debug panels behind a dev flag or query param.

## Touch Controls

When mobile is in scope:

- Use pointer events where possible.
- Ensure controls emit the same game intents as keyboard/mouse.
- Handle `pointerup`, `pointercancel`, `lostpointercapture`, blur, and visibility change.
- Use safe-area insets.
- Avoid controls overlapping HUD warnings or the play path.
- Keep touch targets at least roughly 44 CSS pixels where practical.
- Separate adjacent controls enough to prevent accidental presses.
- Use `touch-action` to prevent unwanted page scrolling only in control regions or the game surface.

## Responsive Constraints

- Define stable dimensions with CSS variables, `clamp`, grid tracks, fixed icon slots, and fixed-width numbers.
- Do not scale text purely with viewport width.
- Avoid negative letter spacing.
- Check desktop, laptop, tablet/narrow, and phone viewports.
- Test longest likely values: high score, long labels, multi-digit timers, localized-ish text if relevant.
- No clipped text, overlapping controls, unreadably small labels, or layout shift from changing values.
- Menus must remain reachable without offscreen controls.

## Visual Style

- Match the genre: arcade racers need speed/status readability; fighters need health/round/impact hierarchy; exploration games need inventory/objective clarity.
- Prefer restrained panels with meaningful geometry, borders, ticks, glow accents, and material cues over nested cards.
- Use a limited status palette plus neutral surfaces.
- Avoid one-note purple/blue gradient UI unless it is strongly justified by the game world.
- Connect UI motifs to world decals, faction marks, vehicle panels, pickups, or hazards.

## 2D Asset Generation

Use `threejs-image-generator` for 2D interface assets when hand-coded CSS/icons are not enough:

- Faction logos, team crests, title marks.
- Pickup, ability, weapon, inventory, achievement, and objective icons.
- Hazard signs, decals, lane glyphs, cockpit labels, item badges.
- Menu/loading/background plates, illustrated map panels, world-style UI textures.
- GUI material references: glass panels, metal frames, holographic strips, paper/parchment, tactical screens.

Use `threejs-3d-generator` only when the UI needs a 3D object: rotating character preview, vehicle garage, weapon inspect model, trophy, diorama, or diegetic 3D menu prop.

## State Wiring

- UI reads game state from a single source of truth.
- UI events dispatch game intents; they should not mutate unrelated simulation internals directly.
- UI should update on pause, restart, resize, mobile orientation, mute, fail/win, score, health, boost, combo, inventory, and accessibility settings.
- Avoid stale values after restart.

## Verification

Capture evidence:

- Gameplay HUD desktop screenshot.
- Gameplay HUD mobile screenshot when in scope.
- Pause/fail/retry state screenshot if changed.
- Text-fit and overlap check with high values.
- Touch target and safe-area check when mobile is in scope.
- Interaction test for UI buttons and touch controls.
- Console/page error check after UI events.
- Generated 2D asset path and prompt when `threejs-image-generator` was used.
- Imported 3D preview model path and renderer diagnostics when `threejs-3d-generator` was used.

## Common Failures

- Generic dashboard/stat-card HUD.
- Nested cards and oversized decorative panels.
- UI covers threats, pickups, player, or next decision.
- Text explains obvious controls instead of designing affordances.
- Mobile safe areas ignored.
- Touch controls look correct but do not emit intents.
- Values change width and shift layout during play.
- Debug UI ships as player UI.