@design-ai/cli 4.55.0

package/knowledge/game-ui/game-ui-fundamentals.md

@@ -0,0 +1,281 @@
+<!-- hand-written -->
+---
+title: Game UI fundamentals (diegetic, non-diegetic, spatial, meta)
+applies_to: [game-ui, hud, game-design]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Game UI fundamentals
+
+Game UI follows different rules from product UI. Game UI exists *while* the player is doing something else (playing). It must convey information without breaking immersion, work with controllers / touch / keyboard, and adapt to genre conventions.
+
+This file is the foundation for [`hud-design.md`](hud-design.md), [`menu-systems.md`](menu-systems.md), [`korean-gaming-conventions.md`](korean-gaming-conventions.md), and [`game-accessibility.md`](game-accessibility.md).
+
+## Four UI categories (Mark Russell taxonomy)
+
+A canonical model for game UI. Every game UI element fits one quadrant:
+
+| | **Spatial** (in 3D world) | **Non-spatial** (overlay) |
+| --- | --- | --- |
+| **Diegetic** (exists in the fiction) | Spatial diegetic — Dead Space's hologram health on character's spine | Non-spatial diegetic — Far Cry 2's GPS held by the character |
+| **Non-diegetic** (exists for the player only) | Spatial non-diegetic — XCOM movement grid drawn on the world | Non-spatial non-diegetic — classic HUD (health bar in corner) |
+
+### Why this matters
+
+- **Diegetic UI** keeps players immersed. The character interacts with it; the player doesn't break frame.
+- **Non-diegetic UI** is faster + clearer but breaks immersion.
+- **Spatial UI** is more natural in 3D worlds; **non-spatial** is more readable.
+
+Most games mix all four. Pick the right tool per element:
+- Health: typically non-spatial non-diegetic (bar in corner).
+- Quest waypoint: often spatial non-diegetic (arrow in 3D world).
+- Inventory: usually non-diegetic menu, but Resident Evil 4's case is a famous diegetic inventory.
+
+## Reading distance — TV vs handheld vs mobile
+
+| Platform | Reading distance | Min text size |
+| --- | --- | --- |
+| **Mobile (handheld)** | 30-50cm | 14sp |
+| **PC monitor** | 50-100cm | 12-14pt |
+| **Console (TV, 10-foot UI)** | 2-4m | 28-32pt+ |
+| **VR headset** | (visual angle, not distance) | per platform spec |
+
+10-foot UI (TV gaming) requires bigger fonts than designers expect. PS5 / Xbox UI defaults to 28-32pt for body. Test on actual TV at distance.
+
+For Korean PC bang (PC방) culture: monitors at standard PC distance; designs for desktop monitor distance work.
+
+For Korean mobile gaming (huge market): same as global mobile; readable at 30-50cm.
+
+## Genre conventions
+
+Game UI follows genre. Players expect certain UI in certain genres; deviating without reason is friction.
+
+### FPS (first-person shooter)
+
+| Element | Position |
+| --- | --- |
+| Crosshair | Center |
+| Health | Bottom-left or bottom-right corner |
+| Ammo | Bottom-right corner |
+| Mini-map | Top-left or top-right corner |
+| Objective | Top center |
+| Score / killfeed | Right side or bottom-left |
+
+Examples: Call of Duty, CS, Valorant.
+
+### RPG / MMO
+
+| Element | Position |
+| --- | --- |
+| Health / mana / stamina | Bottom-left (player avatar) |
+| Quick action bars | Bottom center (1-9 keys) |
+| Mini-map | Top-right |
+| Quest log | Right side or top-right |
+| Chat | Bottom-left |
+| Target frame | Top-center or top-left |
+
+Examples: WoW, Lost Ark, Final Fantasy XIV. Korean MMOs (Lineage, MapleStory) inherit this layout heavily.
+
+### Mobile gacha / RPG
+
+| Element | Position |
+| --- | --- |
+| Currencies | Top of screen (3-5 of them) |
+| Energy / stamina | Top |
+| Battle controls | Bottom (large, thumb-reachable) |
+| Skill buttons | Right side (thumb zone) |
+| Auto-battle / 2x speed | Bottom-right (essential for gacha) |
+| Quest indicators | Around character or floating |
+
+Examples: 원신 (Genshin), 명일방주 (Arknights), Korean genres like 리니지M, 오딘.
+
+### Casual / puzzle
+
+| Element | Position |
+| --- | --- |
+| Score / lives | Top |
+| Pause | Top-corner |
+| Power-ups | Bottom |
+
+Examples: Candy Crush, anipang, 카카오프렌즈게임.
+
+### Strategy (RTS / 4X)
+
+| Element | Position |
+| --- | --- |
+| Mini-map | Bottom-left or bottom-right |
+| Resource counters | Top |
+| Selected unit panel | Bottom-center |
+| Build menu | Bottom-right |
+| Tech tree / overlays | Modal full-screen |
+
+Examples: Starcraft, Civilization. Korean Starcraft heritage means competitive RTS UI culture is strong.
+
+## HUD vs menu vs in-world
+
+| Type | Use |
+| --- | --- |
+| **HUD (Heads-Up Display)** | Always visible during gameplay; status / context |
+| **Menu** | Navigated to; not visible during gameplay |
+| **In-world / spatial** | Embedded in 3D world (waypoints, dialogue bubbles) |
+| **Modal interrupt** | Pauses gameplay (death screen, inventory full) |
+
+Avoid putting too much in HUD — visual noise during play. Prefer menus for detailed views.
+
+## Information density
+
+| Genre | HUD density |
+| --- | --- |
+| FPS | Low (focus on aim) |
+| Racing | Medium (speed, position, lap) |
+| RPG / MMO | High (player chose this complexity) |
+| Casual | Low (don't overwhelm) |
+| Strategy | Very high (resources + units + tech) |
+
+For Korean MMORPG (Lost Ark, BDO, Lineage M): players accept very dense HUDs. Western audiences sometimes find these "cluttered."
+
+## Visual language
+
+### Color coding
+
+Universal:
+- **Red**: damage, danger, enemy, low health.
+- **Green**: friendly, healthy, success, nature.
+- **Yellow / orange**: warning, neutral, special.
+- **Blue**: mana, ally, info.
+- **Purple / gold**: rare / legendary item rarity.
+
+Korean inversion alert: in **stock charts**, Korean convention has red=up, blue=down (opposite of Western). But in games, red=damage / blue=mana follows global convention.
+
+### Item rarity color tiers (canonical)
+
+```
+Common      → Gray / White
+Uncommon    → Green
+Rare        → Blue
+Epic        → Purple
+Legendary   → Orange / Gold
+Mythic      → Red / Rainbow
+```
+
+Most games use this. Players read rarity instantly via color. Don't invent your own without good reason.
+
+### Iconography
+
+- **Currency icons**: gold coin (yellow), gem (purple/blue), special (varies).
+- **Stats icons**: heart (HP), drop (mana / blood / poison), star (XP), shield (defense).
+- **Action icons**: standardized across genres (settings = gear, inventory = bag, map = globe).
+
+Icons in games are larger than product UI (24-32px common; 48-64px for action buttons). Mobile especially.
+
+## Animation in game UI
+
+Game UI animates more than product UI:
+- **Damage numbers** float up + fade.
+- **XP bar** fills smoothly (200-400ms ease-out).
+- **Item drops** bounce / glow.
+- **Notifications** slide in + auto-dismiss.
+- **Skill cooldowns** sweep around an icon.
+
+Style depends on genre:
+- **Realistic / cinematic**: subtle, fast.
+- **Anime / fantasy**: dramatic, longer durations, particle effects.
+- **Casual / cute**: bouncy, playful.
+
+See [`knowledge/motion/principles.md`](../motion/principles.md) for general motion rules; game UI extends with more dramatic motion.
+
+## Audio in game UI
+
+Sound effects are part of UI:
+- **Click**: every button press has audio feedback.
+- **Hover** (PC / console): subtle hover sound.
+- **Confirmation**: positive ding for success, negative buzz for error.
+- **Notifications**: distinctive sound per type (level-up vs damage vs achievement).
+
+For VR / immersive games: spatial audio matters even more; sounds should emit from where they appear.
+
+## Input methods
+
+Game UI must work with whatever input the platform supports:
+
+| Input | Constraint |
+| --- | --- |
+| **Mouse + keyboard (PC)** | Pointing precise; many keys available |
+| **Controller (console)** | D-pad / sticks; fewer buttons; needs focus management |
+| **Touch (mobile)** | Direct manipulation; thumb zones; no hover |
+| **VR controllers** | 6DOF pointing; raycast UI; physical gestures |
+
+### Cross-platform UI
+
+Many modern games ship on PC + console + mobile. UI must adapt:
+
+- **PC**: hover affordances, right-click context menus, keyboard shortcuts.
+- **Console**: focus rings, button prompts ("Press X to open"), tab nav.
+- **Mobile**: bigger tap targets (44pt+), thumb-zone bottom controls.
+
+Defer to platform conventions. Don't force PC-style mouse-driven UI on console; don't force controller-style on mobile.
+
+### Button prompts
+
+Console UI shows controller button icons:
+- Xbox: A, B, X, Y.
+- PlayStation: ✕ (X), ◯ (Circle), △ (Triangle), □ (Square).
+- Switch: A, B, X, Y (different positions from Xbox).
+- Generic: "Confirm", "Cancel", "Back".
+
+For cross-platform: detect controller type and swap icons. Don't assume Xbox.
+
+## State persistence
+
+Game UI persists state across:
+- Sessions (settings, progress).
+- Death + respawn (HUD state, current target).
+- Match transitions (lobby → game → results).
+
+Save state at meaningful checkpoints. Lose-progress-on-crash is the worst game UX.
+
+## Korean game market notes
+
+(Detail in [`korean-gaming-conventions.md`](korean-gaming-conventions.md).)
+
+Quick context:
+- **Mobile gacha + MMO** dominate Korean revenue.
+- **PC bang (PC방)** culture: PCs at low/free hourly rates; competitive games dominant.
+- **Major studios**: NEXON (메이플스토리, FIFA Online), NCSoft (리니지, 길드워), Krafton (배틀그라운드 / PUBG), Smilegate (크로스파이어, 로스트아크), Pearl Abyss (검은사막).
+- **Mobile-first audience**: heavy auto-battle, gacha, daily login rewards.
+
+## Accessibility intro
+
+(Detail in [`game-accessibility.md`](game-accessibility.md).)
+
+Game UI accessibility:
+- Subtitles + closed captions (always option).
+- Color-blind modes (color-coding redundant with shape / pattern).
+- Remappable controls.
+- Adjustable text size + UI scale.
+- High-contrast mode.
+- Reduced motion option.
+
+2024+: accessibility is increasingly expected; Last of Us Part II / Forza Horizon raised the bar.
+
+## Don't
+
+- Don't break genre conventions without strong reason. Players expect HP bottom-left in MMOs.
+- Don't ignore platform conventions (PC vs console vs mobile have different defaults).
+- Don't make HUD so dense it competes with gameplay attention.
+- Don't skip button prompts on console.
+- Don't use only color to encode meaning (color-blind exclusion).
+- Don't auto-advance dialogue. Player controls the pace.
+- Don't lock UI to one resolution. Scale for different screens.
+- Don't forget audio. Game UI is auditory + visual.
+
+## Cross-reference
+
+- [`knowledge/game-ui/hud-design.md`](hud-design.md) — HUD elements
+- [`knowledge/game-ui/menu-systems.md`](menu-systems.md) — main menu, pause, inventory
+- [`knowledge/game-ui/korean-gaming-conventions.md`](korean-gaming-conventions.md) — KR market
+- [`knowledge/game-ui/game-accessibility.md`](game-accessibility.md) — a11y in games
+- [`knowledge/motion/principles.md`](../motion/principles.md) — motion fundamentals
+- [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — focus / keyboard

package/knowledge/game-ui/hud-design.md

@@ -0,0 +1,324 @@
+<!-- hand-written -->
+---
+title: HUD design (in-game heads-up display elements)
+applies_to: [game-ui, hud, in-game]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# HUD design
+
+The HUD (Heads-Up Display) is the always-visible overlay during gameplay. It tells the player what they need to know without breaking the flow.
+
+Read [`game-ui-fundamentals.md`](game-ui-fundamentals.md) first.
+
+## What goes in HUD vs not
+
+In HUD (always visible during play):
+- Health / mana / stamina.
+- Crosshair / aim reticle.
+- Ammo / current weapon.
+- Currency / score.
+- Mini-map / radar (genre-dependent).
+- Cooldowns of active skills.
+- Critical alerts (low health, no ammo).
+
+NOT in HUD (open via menu):
+- Full inventory.
+- Stats / character sheet.
+- Settings.
+- Friends list.
+- Quest details (summary OK, details menu).
+
+The HUD competes with gameplay for attention. Less is more.
+
+## HUD layout patterns
+
+### FPS HUD
+
+```
+                                           [mini-map]
+[objective banner ───────────────────────]
+                                              [killfeed]
+                                              [ ... ]
+                                              [ ... ]
+                       [crosshair]
+                                              [target damage]
+
+
+[health bar] [armor]                          [ammo] [grenades]
+```
+
+Compact. Center stays clear for aim. Information clusters in corners.
+
+### MMO / RPG HUD
+
+```
+[player frame: HP / MP / stamina]               [mini-map]
+[buffs / debuffs]                               [target frame]
+[chat ────]                                     [quest tracker]
+                                                [...]
+                                                [combat log]
+[hotbar 1 (1-9 keys)]                           [hotbar 2 (F1-F9)]
+[hotbar 3 (Shift+1-9)]
+```
+
+Dense. Player has many concurrent inputs to track. Modular — players reposition / hide elements.
+
+### Mobile gacha HUD
+
+```
+[currency 1]  [currency 2]  [currency 3]  [stamina/energy] [profile]
+
+                  [main game area]
+                  [character / scene]
+
+
+[skill 1] [skill 2] [skill 3]   [auto] [2x speed] [pause]
+```
+
+Currencies prominent (gacha = always selling). Auto-battle + speed control essential. Skills in thumb zone.
+
+### Mobile casual HUD
+
+```
+[score]                         [pause]
+[lives ❤❤❤]                     [coins]
+
+
+            [game board]
+
+
+
+[power-ups: 3 buttons]
+```
+
+Minimal. Score + lives + power-ups; nothing else.
+
+## Health bars
+
+The single most-iterated UI element in games.
+
+### Bar types
+
+| Type | Use |
+| --- | --- |
+| **Linear bar** | Default; "X HP / Y HP" or just bar |
+| **Segmented bar** | Each segment is a hit (Zelda hearts) |
+| **Circular** | Cinematic; matches icon style |
+| **Layered** | Shield + health + barrier separately |
+| **Radial / context** | Gear of War's blood-vignetting |
+| **Diegetic** | Health on character body / vehicle (Far Cry, Forza) |
+
+### Health bar rules
+
+- **Damage delay** — when hit, bar drops to new value over 200-400ms (not instant). Player sees the damage happen.
+- **Recent damage indicator** — second bar showing damage taken in last 1-2s (Tekken-style). Helps player track combo damage.
+- **Color shift** — green→yellow→red as health drops. Color blind alt: shape / pattern change.
+- **Critical state** — visual emphasis when < 25% (pulse, screen edge red).
+- **Regen** — animated fill if regenerating.
+- **Permanent damage cap** — for games with overheal / shield: separate visual.
+
+### Korean MMO health bar tradition
+
+- Often labeled with exact numbers ("8420 / 12000 HP").
+- Multiple buffs / debuffs stacked underneath.
+- Frame heavy / decorated (gold leaf borders for high-tier characters).
+
+## Ammo / resource counters
+
+```
+[icon] 30 / 120
+       ▲    ▲
+   current  reserve
+```
+
+Counter rules:
+- Tabular numerals (digit alignment): `font-feature-settings: "tnum"`.
+- Reload state: visible animation / icon swap during reload.
+- Out of ammo: emphasis (red, pulse, "RELOAD" prompt).
+- Different ammo types: icon + count per type, or active-type only.
+
+## Crosshair / reticle
+
+For shooters:
+- **Static dot**: precision shooting (Valorant, CS).
+- **Dynamic spread**: expands during recoil (CoD, Apex).
+- **Hit marker**: brief X-shape on hit.
+- **Damage indicator**: outer ring pulses red when taking damage from a direction.
+
+Customizable:
+- Color (bright red, neon yellow, white).
+- Shape (dot, plus, T, custom).
+- Outline (for visibility on any background).
+
+Required for accessibility.
+
+## Mini-map
+
+| Element | Notes |
+| --- | --- |
+| Player marker | Center; rotates with view OR fixed-north |
+| Allies | Blue dots / icons |
+| Enemies | Red (when visible) |
+| Objectives | Yellow / gold marker |
+| POI / quest | Distinct icons |
+| Compass | N / E / S / W; or angle indicator |
+
+Rotation:
+- **Rotating mini-map**: easier for new players (always points the way they're facing).
+- **Fixed north**: better for spatial memory; competitive players prefer.
+
+Many games offer toggle.
+
+## Damage numbers
+
+Float-up text showing damage dealt:
+
+```
+Hit                       150
+Critical                 320!
+Heal              +84
+Miss                    Miss
+```
+
+Style:
+- White / yellow for damage.
+- Red for critical / huge damage.
+- Green for heal.
+- Float up + fade over 800-1500ms.
+- Stack to one side if many.
+
+For "loot games" like Diablo / Path of Exile / Lost Ark: damage numbers are core; players read DPS from these.
+
+For more cinematic games (RDR2, God of War): damage numbers off, hit feedback via animation / sound only.
+
+## Cooldowns
+
+Skill icons on hotbar with cooldown indicator:
+
+```
+┌──────┐
+│ ⚔    │   ← skill icon
+│      │
+│  3.2 │   ← seconds remaining
+└──────┘
+   ▒▒▒▒    ← sweep / fill animation
+```
+
+Animation:
+- **Radial sweep** (clock-face style): most common, intuitive.
+- **Vertical fill**: bar fills bottom-to-top.
+- **Desaturate + number**: icon grayed out + countdown number.
+
+Players need to read cooldowns at-a-glance during combat. Don't make sweep too detailed; readability > beauty.
+
+## Buffs / debuffs
+
+Icons showing active effects:
+
+```
+[⏳ Speed +20% — 12s] [☠ Poison — 8s] [✨ Shield — 30s]
+```
+
+Layout:
+- Row of icons; new buffs add to right.
+- Timer overlay (number or bar).
+- Color: green for buff, red for debuff, blue for neutral.
+- Click / hover (PC) for description.
+- Stacks: number badge "x3".
+
+For high-density combat: 5-15+ buffs / debuffs simultaneous. Group by type (offensive, defensive, status).
+
+## Floating quest markers
+
+3D world markers:
+- **Above NPCs**: ! (new quest), ? (turn-in), ... (in progress).
+- **On waypoints**: floating diamond / arrow.
+- **Compass markers**: indicator at top of screen for off-screen objectives.
+- **World waypoint**: pillar of light reaching skyward.
+
+Don't over-clutter. One active waypoint at a time, unless player explicitly multi-tracks.
+
+## Notifications
+
+Transient messages:
+
+| Type | Style |
+| --- | --- |
+| Item picked up | "+ 5 gold" / "Got: [Item icon] Sword" |
+| Quest update | "New quest: [Name]" with subtle banner |
+| Achievement | Larger banner, satisfying sound, often persistent for 3-5s |
+| Level up | Big celebration: particles, sound, persistent |
+| Death | Modal full-screen interrupt |
+
+Slide-in, hold, fade-out. Total duration:
+- Item pickup: 1-2s.
+- Quest update: 3-5s.
+- Achievement: 4-6s.
+- Level up: 5-10s with full effects.
+
+Stack notifications (if many fire fast); newer pushes older down or replaces with summary ("+5 items").
+
+## Subtitles / dialogue
+
+| Style | Use |
+| --- | --- |
+| Bottom-center overlay | Most action / cinematic |
+| Speech bubble (3D world) | Cute / cartoon |
+| Side panel | Visual novels |
+| Choice list | Branching dialogue |
+
+Subtitle config (always): on/off, size, background opacity, speaker name. WCAG-aligned options.
+
+For Korean: 자막 (subtitle) commonly bottom-center, white text + black outline + semi-opaque dark band, NanumSquare or Pretendard, larger than English equivalent.
+
+## Adapting to widescreen / ultra-wide
+
+Modern games support 16:9 / 21:9 / 32:9 ultra-wide. HUD must adapt:
+
+- **Anchor HUD elements to screen edges** (not center percentages).
+- **Stretch background** but anchor UI.
+- **Fix FOV** — don't let ultra-wide give competitive advantage in PvP (clip to standard FOV).
+
+For mobile: handle different aspect ratios (16:9 vs 18:9 vs 19.5:9 vs foldable).
+
+## Customization
+
+Modern games offer HUD customization:
+- **Move elements** (drag positions).
+- **Resize** (scale individual elements).
+- **Hide** (toggle elements off — minimalist play).
+- **Themes / skins** (purchased or unlocked).
+- **Color presets** (color-blind modes, brightness presets).
+
+Save customization per-player profile.
+
+## Performance
+
+HUD renders every frame. Performance matters:
+- Use sprite-based rendering (texture atlas) — minimize draw calls.
+- Update only when state changes (don't re-layout every frame).
+- Animations on GPU when possible.
+- Mobile: target 60fps; pre-budget UI overhead.
+
+## Don't
+
+- Don't put critical info in screen edges that get cropped on smaller TVs / mobile screens.
+- Don't make health bars subtle — players need fast read.
+- Don't auto-hide HUD with no opt-out.
+- Don't ignore color-blind alternatives (shape / pattern).
+- Don't over-decorate. Function over flourish.
+- Don't lock HUD to one resolution. Scale via UI scale option.
+- Don't put long text in HUD. Reserve text for menus / dialogue.
+- Don't ignore audio. UI sounds matter as much as visual.
+
+## Cross-reference
+
+- [`knowledge/game-ui/game-ui-fundamentals.md`](game-ui-fundamentals.md) — categories, genres
+- [`knowledge/game-ui/menu-systems.md`](menu-systems.md) — full menus
+- [`knowledge/game-ui/korean-gaming-conventions.md`](korean-gaming-conventions.md) — KR conventions
+- [`knowledge/game-ui/game-accessibility.md`](game-accessibility.md) — a11y in games
+- [`knowledge/motion/principles.md`](../motion/principles.md) — animation
+- [`examples/component-game-hud.md`](../../examples/component-game-hud.md) — HUD spec