DonchitosandClaude Opus 5
d05699707f
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
32 KiB
Interaction Pattern Library: [Game Title]
Authoring guidance: .claude/docs/templates/guidance/interaction-pattern-library-guide.md (load per-section as you author — do not read entirely).
Status: Draft | Stable | Under Revision Author: [ux-designer] Last Updated: [Date] Version: [1.0] Engine: [Godot 4.6 / Unity 6 / Unreal Engine 5] UI Framework: [Godot Control nodes / Unity UI Toolkit / Unreal UMG] Related Documents:
design/art/art-bible.md— visual standards (colors, typography, iconography)design/accessibility-requirements.md— accessibility commitments per featuredocs/ux/ux-spec-[screen].md— individual screen specs that reference patterns
Why this document exists: Every UI screen spec should be able to say "uses Button (Primary) pattern" rather than re-specifying hover states, press animations, focus behavior, keyboard handling, and screen reader announcements from scratch. This library is the single source of truth for reusable interaction behaviors. When a screen spec references a pattern name, the programmer looks it up here. When the behavior changes, it changes here and applies everywhere.
This is a living document. Patterns are added as new screens are designed — do not design a new interaction without checking here first. If a new pattern is needed, add it here (or propose it to the ux-designer) before writing the first screen spec that uses it.
Status definitions:
- Draft: Interaction specified but not yet implemented or validated
- Stable: Implemented, tested, and validated in at least one shipped screen
- Deprecated: Being phased out — existing uses will be migrated, do not use in new screens
How to Use This Library
If you are designing a screen: Browse the Pattern Catalog Index below before inventing new interactions. When a standard pattern fits, reference it by name in the screen spec (e.g., "The confirm button uses Button (Primary) pattern"). When no existing pattern fits, propose a new one — document it here alongside or before the screen spec that introduces it.
If you are implementing a screen: When a screen spec says "use [PatternName] pattern," find it in this document for the complete specification. The implementation notes section contains engine-specific guidance. The accessibility section contains the requirements that are non-negotiable.
If you are reviewing a screen spec: Verify that all interactive elements reference a pattern from this library or include their own full interaction specification. "Standard button" or "the usual way" is not a valid reference.
If you are updating a pattern: Changing a Stable pattern affects every screen that uses it. Before changing, audit all usages (search screen specs for the pattern name), determine the impact, get approval from the ux-designer, and update this document before or simultaneously with any implementation change.
Pattern Catalog Index
Add a row here every time a new pattern is added to this document. The "Used In" column is the usages audit trail — update it when new screens adopt the pattern.
| Pattern Name | Category | Description | Used In (Screens) | Status |
|---|---|---|---|---|
| Button (Primary) | Input | Main call-to-action. High visual weight. One per screen. | [Main Menu, Pause Menu, Settings] | Draft |
| Button (Secondary) | Input | Alternative action or cancel. Lower visual weight than Primary. | [All modal dialogs, settings screens] | Draft |
| Button (Destructive) | Input | Irreversible action. Requires confirmation before execution. | [Delete Save, Reset Settings] | Draft |
| Toggle | Input | Binary on/off state selection. | [Accessibility settings, audio settings] | Draft |
| Slider | Input | Continuous value selection. | [Volume controls, brightness, text size] | Draft |
| Dropdown / Select | Input | Selection from a discrete list of options. | [Resolution, language, key binding] | Draft |
| List Item | Layout / Input | Selectable row in a vertical scrollable list. | [Achievements, quest log, settings list] | Draft |
| Grid Item | Layout / Input | Selectable cell in a two-dimensional grid. | [Inventory, ability select, item shop] | Draft |
| Modal Dialog | Feedback / Layout | Blocking overlay requiring explicit player decision. | [Confirmation dialogs, error prompts] | Draft |
| Confirmation Dialog | Feedback / Layout | Specific modal for destructive action confirmation. | [Delete Save, Leave Match, Reset] | Draft |
| Toast / Notification | Feedback | Non-blocking temporary message in a screen corner. | [Achievement unlock, autosave notification] | Draft |
| Tooltip | Feedback | Contextual information on hover or focus. | [Inventory items, ability descriptions, settings] | Draft |
| Progress Bar | Feedback / Layout | Linear progress indicator. | [Loading screen, XP bar, quest progress] | Draft |
| Input Field | Input | Text entry control. | [Player name, search, key binding entry] | Draft |
| Tab Bar | Navigation | Tabbed section navigation within a single screen. | [Character sheet, settings, crafting] | Draft |
| Scroll Container | Layout | Scrollable content region with visible scroll indicator. | [Inventory, lore entries, credits] | Draft |
| Inventory Slot | Game-Specific | Item container in inventory grid (empty, filled, equipped, locked). | [Inventory screen, equipment screen] | Draft |
| Ability / Skill Icon | Game-Specific | Ability button with cooldown, charges, and locked states. | [HUD ability bar, skill tree] | Draft |
| Health / Resource Bar | Game-Specific | Value bar with threshold states and damage flash. | [HUD] | Draft |
| Minimap | Game-Specific | Overview map with player marker and points of interest. | [HUD] | Draft |
| Quest / Objective Tracker | Game-Specific | Active objective display with proximity and completion states. | [HUD] | Draft |
| Dialogue Box | Game-Specific | NPC conversation UI with speaker identification. | [All dialogue sequences] | Draft |
| Context Action Prompt | Game-Specific | Contextual "Press X to [action]" prompt near interactable objects. | [World interaction] | Draft |
| Damage Number | Game-Specific | Floating combat feedback number. | [Combat HUD] | Draft |
| Status Effect Icon | Game-Specific | Buff/debuff indicator with duration. | [HUD status bar, enemy health display] | Draft |
| Notification Banner | Game-Specific | Achievement, level up, item acquired notifications. | [Global overlay] | Draft |
| Screen Push | Navigation | Forward navigation with directional animation. | [All menu navigation] | Draft |
| Screen Pop (Back) | Navigation | Back navigation with reversed animation. | [All menu navigation] | Draft |
| Screen Replace | Navigation | Replace current screen without stacking history. | [Main Menu to Loading Screen] | Draft |
| Modal Open / Close | Navigation | Overlay that dims background screen. | [All modal dialogs] | Draft |
| Tab Switch | Navigation | Same-screen content switch between tabs. | [All tabbed screens] | Draft |
| Focus Management | Navigation | Rules for where focus goes when screens open, close, or change. | [All screens] | Draft |
| Escape / Cancel | Navigation | Universal back behavior across platforms and input methods. | [All screens] | Draft |
| Loading State | Feedback | How screens and components indicate loading in progress. | [All loading states] | Draft |
| Empty State | Feedback | How empty lists and grids are presented. | [Empty inventory, no quests, no saves] | Draft |
| Error State | Feedback | How errors are communicated. | [Save failed, network error, invalid input] | Draft |
| Success Confirmation | Feedback | How completed actions are confirmed. | [Settings saved, item crafted, quest turned in] | Draft |
| Optimistic UI | Feedback | Showing assumed success before system confirmation. | [If online features are present] | Draft |
Standard Control Patterns
Full reference specifications for every pattern in this section (state tables with timing/audio values, accessibility requirements, implementation notes) are in
.claude/docs/templates/guidance/interaction-pattern-library-guide-standard-controls.md— load only the pattern(s) currently being specified.
Button (Primary)
Category: Input Status: Draft When to Use: [The single most important action on a screen — at most one visible at a time] When NOT to Use: [Alternative/secondary actions; destructive actions; anything not the screen's primary intent]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Default / Hovered / Focused / Pressed / Disabled / Loading] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Keyboard, gamepad, screen reader, colorblind, and touch-target requirements]
Implementation Notes: [Engine-specific guidance]
Button (Secondary)
Category: Input Status: Draft When to Use: [Alternative or cancel action — lower visual weight than Primary] When NOT to Use: [Destructive actions; the screen's most important action]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Same baseline as Button (Primary); note cancel-input mapping in dialogs]
Implementation Notes: [Engine-specific guidance; consistent Primary/Secondary positioning]
Button (Destructive)
Category: Input Status: Draft When to Use: [Irreversible actions causing loss of player data or progress] When NOT to Use: [Actions that can be undone or are merely consequential]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Critical rule: A Button (Destructive) NEVER executes its action directly. It always triggers a Confirmation Dialog. There are no exceptions.
Accessibility: [Screen reader must announce the destructive nature]
Implementation Notes: [Engine-specific guidance]
Toggle
Category: Input Status: Draft When to Use: [Binary on/off settings where current state must be visible at a glance] When NOT to Use: [More than two options; one-shot actions; choices needing explanation]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Activation inputs, screen reader switch role/state rules, state label requirements]
Implementation Notes: [Engine-specific guidance; motion-reduction behavior]
Slider
Category: Input Status: Draft When to Use: [Continuous value selection where range and relative position matter] When NOT to Use: [Precise value entry; short discrete lists; binary state]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Keyboard step/large-step/min-max inputs, screen reader value announcements, numeric value display requirement]
Implementation Notes: [Engine-specific guidance]
Dropdown / Select
Category: Input Status: Draft When to Use: [Selection from a discrete list of 3-15 options; only the selection visible at rest] When NOT to Use: [Binary choices; more than ~15 options; when comparing options matters]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [List navigation, combobox role, expanded/collapsed announcements, positioning rules]
Implementation Notes: [Engine-specific guidance]
List Item
Category: Layout / Input Status: Draft When to Use: [A selectable row in a vertically scrollable list] When NOT to Use: [Two-dimensional grids; non-selectable content rows]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [State] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Focus cycling rules, listitem role and position announcements, minimum row height]
Implementation Notes: [Engine-specific guidance; scroll-into-view on focus]
Grid Item
Category: Layout / Input Status: Draft When to Use: [A selectable cell in a two-dimensional grid] When NOT to Use: [Single-column content; non-selectable display cells]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Empty / Populated / Hovered / Focused / Selected / Pressed / Locked / Drag source / Drop target] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Grid dimensions and row/column position announcements, keyboard-reachable tooltips]
Implementation Notes: [Engine-specific guidance; custom D-pad cell navigation]
Modal Dialog
Category: Feedback / Layout Status: Draft When to Use: [A decision or acknowledgment that must be resolved before continuing] When NOT to Use: [Non-blocking notifications; information that can wait; dialogs that should allow play behind them]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Opening / Active / Dismissing (confirmed) / Dismissing (cancelled) / Cannot dismiss] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Focus trap rule: While a modal dialog is open, focus navigation must cycle within the dialog only, and focus must return to the trigger element on close.
Accessibility: [Dialog role and required title, Escape/Enter mappings, motion-reduction overrides]
Implementation Notes: [Engine-specific guidance]
Confirmation Dialog
Category: Feedback / Layout Status: Draft When to Use: [Confirming a destructive action — always triggered by Button (Destructive)] When NOT to Use: [Non-destructive confirmations; dialogs with more than two actions]
Label rule: The confirm button must be labeled with the specific action, not a generic "OK" or "Yes."
Structure:
- Title: [Brief, action-describing]
- Body: [One sentence stating the consequence]
- Confirm button: [Button (Primary) — labeled with the specific action]
- Cancel button: [Button (Secondary) — "Cancel"]
- Default focus: [Cancel — safer default]
Accessibility: [Inherits Modal Dialog; alert-dialog announcement; default focus on Cancel is required]
Implementation Notes: [Engine-specific guidance]
Toast / Notification
Category: Feedback Status: Draft When to Use: [Brief, non-blocking information requiring no player decision] When NOT to Use: [Decisions; errors requiring action; critical information the player must not miss]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Entering / Displayed / Auto-dismiss / Manual dismiss / Queue overflow] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Announcement without focus, motion-reduction fallback, minimum auto-dismiss timing, never sole channel for actionable info]
Implementation Notes: [Engine-specific guidance; queue management and layer ordering]
Tooltip
Category: Feedback Status: Draft When to Use: [Contextual information supplementing a visible label] When NOT to Use: [Information required to complete an action; touch-only platforms without hover]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Hidden / Hover trigger / Focus trigger / Appearing / Displayed / Hiding] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Content accessible without hover, required appearance delay, contrast requirements]
Implementation Notes: [Engine-specific guidance; screen-edge repositioning]
Progress Bar
Category: Feedback / Layout Status: Draft When to Use: [Linear progress toward a defined endpoint] When NOT to Use: [Radial progress; rapidly fluctuating values; values with no endpoint]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Default / Value increasing / At maximum / At zero / Indeterminate] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Progressbar role, numeric value + percentage announcements, numeric label requirement, motion-reduction overrides]
Implementation Notes: [Engine-specific guidance; indeterminate-mode implementation]
Input Field
Category: Input Status: Draft When to Use: [Text entry — player name, search, precise numeric values, key binding capture] When NOT to Use: [Selecting from known options; console-primary flows where virtual keyboards add friction]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Default / Hovered / Focused / Typing / Value present / Limit reached / Clear / Validation error / Validated / Disabled] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Standard editing shortcuts, textbox role, visible label requirement (placeholder is not a label)]
Implementation Notes: [Engine-specific guidance; virtual keyboard handling]
Tab Bar
Category: Navigation Status: Draft When to Use: [Dividing one screen's content into discrete sections, one visible at a time — max 5-6 tabs] When NOT to Use: [More than 6 tabs; content needing simultaneous visibility; navigation between screens]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Inactive / Active / Hovered / Focused / Activated / Shoulder-button switch] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [ARIA tab panel pattern (tab/tablist/tabpanel), active-tab distinction beyond color]
Implementation Notes: [Engine-specific guidance; shoulder-button shortcut handling]
Scroll Container
Category: Layout Status: Draft When to Use: [Content exceeding the visible area of its container] When NOT to Use: [Content better paginated; infinite scroll without loading/end states]
Interaction Specification:
| State | Visual | Input | Response | Duration | Audio |
|---|---|---|---|---|---|
| [Content fits / Scrollable / Scrolling / Scrollbar drag / Keyboard scroll / Gamepad scroll / Boundary / Focus follows scroll] | [Visual treatment] | [Input trigger] | [Response] | [Duration + easing] | [Sound category] |
Accessibility: [Auto-scroll to keep focused items in view, scroll position announcements, scrollbar as required indicator]
Implementation Notes: [Engine-specific guidance; ensure-visible on focus change]
Game-Specific UI Patterns
Full reference specifications for every pattern in this section are in
.claude/docs/templates/guidance/interaction-pattern-library-guide-game-specific.md— load only the pattern(s) currently being specified.
Inventory Slot
Category: Game-Specific Status: Draft When to Use: [Every item container in the inventory grid — empty, populated, equipped, locked]
States:
| State | Visual | Notes |
|---|---|---|
| [Empty / Populated / Focused / Selected / Drag source / Locked / Highlighted / Cooldown overlay] | [Visual treatment] | [Behavioral notes] |
Accessibility: [Non-color alternatives for stack counts and quality tiers; keyboard-reachable tooltip; locked-state announcement]
Implementation Notes: [Engine-specific guidance]
Ability / Skill Icon
Category: Game-Specific Status: Draft When to Use: [HUD ability bar buttons, skill tree nodes, any availability-state ability display]
States:
| State | Visual | Notes |
|---|---|---|
| [Available / On cooldown / Charges remaining / Out of resource / Locked / Active / Just activated] | [Visual treatment] | [Behavioral notes] |
Accessibility: [Numeric alternatives for cooldown/charge information; names and descriptions exposed to screen readers]
Implementation Notes: [Engine-specific guidance]
Health / Resource Bar
Category: Game-Specific Status: Draft When to Use: [Any continuously varying critical player resource in the HUD]
States and behaviors:
| Event | Visual | Audio | Duration |
|---|---|---|---|
| [Decrease / Increase / Below threshold / At zero / Maximum / Overflow] | [Visual treatment] | [Sound category] | [Duration] |
Accessibility: [Numeric value access; non-color backups for threshold states]
Implementation Notes: [Engine-specific guidance; ghost-bar technique]
Dialogue Box
Category: Game-Specific Status: Draft When to Use: [All dialogue that has a speaker — NPC conversation, voiced narrative, character-delivered tutorial text]
Structure: [Speaker identification, dialogue text body, advance prompt, optional skip/voice/subtitle indicators]
States and behaviors:
| State | Visual | Input | Response | Duration |
|---|---|---|---|---|
| [Line entering / Revealing / Line complete / Advancing / Choices appearing / Closing / Skipping all] | [Visual treatment] | [Input trigger] | [Response] | [Duration] |
Accessibility: [Subtitles on by default, configurable typewriter speed, no auto-advance, navigable choices with position announcements]
Implementation Notes: [Engine-specific guidance; dialogue data format]
Context Action Prompt
Category: Game-Specific Status: Draft When to Use: [A prompt near an interactable object indicating what the player can do]
States:
| State | Visual | Notes |
|---|---|---|
| [Appearing / Idle / Holding / Cannot interact / Disappearing] | [Visual treatment] | [Behavioral notes] |
Accessibility: [Text label alongside button icon; positioning must not overlap critical HUD]
Implementation Notes: [Engine-specific guidance; input-method-aware icon swapping]
Damage Number
Category: Game-Specific Status: Draft When to Use: [Floating feedback numbers above combat participants]
Variants:
| Variant | Visual | Notes |
|---|---|---|
| [Normal / Critical / Healing / Miss / Status damage] | [Visual treatment] | [Behavioral notes] |
Behavior: [Float trajectory, fade timing, overlap staggering, maximum simultaneous numbers]
Accessibility: [Supplementary-only feedback; disable option; game fully playable when disabled]
Implementation Notes: [Engine-specific guidance; object pooling]
Navigation Patterns
Full reference specifications for this section and the next are in
.claude/docs/templates/guidance/interaction-pattern-library-guide-navigation-feedback.md— load only the pattern(s) currently being specified.
Screen Push / Pop / Replace
Category: Navigation Status: Draft
These three patterns define how screens enter and exit the navigation stack.
| Pattern | Trigger | Animation | Stack Behavior | Focus Behavior |
|---|---|---|---|---|
| [Push / Pop / Replace] | [Trigger] | [Animation] | [Stack behavior] | [Focus behavior] |
Animation durations: [Push/Pop and Replace durations + easing]
Motion reduction: [Fallback behavior]
Implementation Notes: [Engine-specific guidance; screen stack manager and return-focus storage]
Focus Management
Category: Navigation Status: Draft
Focus management is the most common keyboard and gamepad accessibility failure in game UIs. These rules must be implemented consistently.
| Rule | Description |
|---|---|
| [Screen open / close, modal open / close, element disabled / destroyed, Tab order, D-pad spatial navigation, focus visibility] | [Rule description] |
Escape / Cancel
Category: Navigation Status: Draft
The "go back" action is the most-used navigation input in all menu systems. It must be consistent across every screen with no exceptions.
| Platform | Input | Behavior |
|---|---|---|
| [Platform] | [Input] | [Behavior] |
Rules: [Never override "go back / cancel"; every screen defines its Escape behavior explicitly in its UX spec]
Feedback and Loading Patterns
Loading State
Category: Feedback Status: Draft
| Scope | Pattern | Notes |
|---|---|---|
| [Full screen (initial) / Full screen (transition) / Component inline / Background async] | [Pattern] | [Notes] |
Accessibility: [Screen reader loading/loaded announcements; loading screens navigable]
Empty State
Category: Feedback Status: Draft
Every empty list and grid must have a designed empty state. The empty state is not an error — it is a starting point.
| Location | Empty State Content | Notes |
|---|---|---|
| [Location] | [Icon + message + sub-message or action] | [Notes] |
Rule: Every empty state must include an icon, a message, and either a sub-message or an action button.
Error State
Category: Feedback Status: Draft
| Error Type | Pattern | Tone |
|---|---|---|
| [Input validation / Operation failed / System error / Soft error] | [Pattern] | [Tone guidance] |
Principle: Error messages are never the player's fault. They tell the player what happened and what to do next.
Animation Standards
These timing values apply to ALL patterns in this library. When a pattern says "150ms ease-out," the easing function is defined here. Consistency in timing makes the UI feel like a single designed system rather than a collection of individual decisions.
| Animation Type | Duration (ms) | Easing Function | Notes |
|---|---|---|---|
| Button hover / focus enter | 80 | ease-out | Fast — snappy, not sluggish |
| Button hover / focus exit | 60 | ease-in | Slightly faster exit than entry |
| Button press scale down | 60 | ease-in | Immediate feedback |
| Button press scale up (release) | 80 | ease-out | Slightly bouncy feel |
| Screen push (enter) | 250 | ease-in-out | Screen slides in from right |
| Screen pop (exit) | 250 | ease-in-out | Screen slides out to right |
| Modal open | 200 | ease-out | Expands from center |
| Modal close | 150 | ease-in | Collapses faster than it opens |
| Toast enter | 200 | ease-out | Slides in from screen edge |
| Toast exit | 200 | ease-in | |
| Tab switch | 150 | ease-in-out | Content cross-fades or slides |
| Tooltip appear | 120 | ease-out | After 300-400ms delay |
| Tooltip disappear | 80 | ease-in | |
| Progress bar fill | 300 | ease-out | Value changes animate smoothly |
| Value flash (damage, gain) | 100ms on + 100ms off | linear | Brief, attention-catching |
| Dialogue text reveal (per character) | 30ms per character | linear | Configurable in accessibility settings |
| HUD damage flash | 80 | linear | White or red overlay, immediate |
Motion reduction overrides: When motion reduction mode is enabled (see accessibility-requirements.md), all slide and scale animations are replaced with fades. Fade durations are reduced by 50%. Looping animations (indeterminate spinners, pulsing indicators) are replaced with static equivalents.
Sound Standards
Every interactive event should have audio feedback. Sound is a primary feedback channel, not a decoration. The sounds defined here are event categories — the specific audio assets are defined in
docs/sound-bible.md. This table maps interaction events to sound categories so the sound designer and UI programmer use the same vocabulary.
| Interaction Event | Sound Category | Notes |
|---|---|---|
| Button hover / focus | UI Hover | Subtle, short (< 80ms), non-fatiguing on rapid navigation. Hades uses a very quiet, high-frequency click that disappears into background on rapid nav. |
| Button (Primary) confirm | UI Confirm — Primary | Slightly more prominent than secondary confirm. The "yes, let's go" sound. |
| Button (Secondary) cancel / back | UI Cancel | Subtly downward in pitch. The "going back" sound. Mass Effect uses a clean, distinct swoosh for back navigation. |
| Button (Destructive) — opening confirmation | UI Warning | Distinct from standard confirm. Brief attention-catching sound. |
| Confirmation dialog — confirm destructive | UI Confirm — Destructive | Final, slightly weighted. The action is being taken. |
| Toggle ON | UI Toggle On | Brief, snappy, slightly bright. Celeste's accessibility toggles have a satisfying click-on sound. |
| Toggle OFF | UI Toggle Off | Same click family, slightly flatter. |
| Slider adjust | UI Slider | Subtle continuous sound while dragging. A single click per D-pad step. Never fatiguing. |
| Dropdown open | UI Expand | Brief, directional (opening feel). |
| Dropdown close / select | UI Select | Confirmation feel. |
| Tab switch | UI Tab | Horizontal movement feel. Distinct from vertical navigation. |
| Modal open | UI Modal Open | More prominent than standard navigation — draws attention. |
| Modal close (cancel) | UI Modal Close | Returns to previous context. |
| Toast — informational | UI Notification | Background-level, non-intrusive. |
| Toast — achievement | UI Achievement | Celebratory but not overlong. The player should feel rewarded, not interrupted. |
| Toast — warning | UI Warning — Toast | Distinct from error. Alert, not alarming. |
| Error state | UI Error | Friendly but clear. Not a harsh buzzer. Dark Souls uses a subtle dull thud for failed actions — communicates "no" without being harsh. |
| Success confirmation | UI Success | Clean and satisfying. |
| Ability activate | Gameplay — Ability Activate | In-world feel, distinct from pure UI. Part of game feel, not menu feel. |
| Damage received | Gameplay — Damage | See sound-bible.md for full specification. |
| Item pickup | Gameplay — Item Acquire | Brief, rewarding. |
| Level up / rank up | Gameplay — Progression | Celebratory, appropriately prominent. |
| Dialogue advance | UI Dialogue | Subtle, matches typewriter rhythm if typewriter is active. |
Open Questions
| Question | Owner | Deadline | Resolution |
|---|---|---|---|
| [Does the engine's accessibility node system support screen reader announcements for toast notifications without requiring focus? Verify against engine-reference/godot/ for Godot 4.6.] | [ux-designer] | [Before first menu implementation] | [Unresolved] |
| [What is the platform-correct confirm/cancel button mapping for Nintendo Switch release? Nintendo first-party convention differs from Xbox/PlayStation.] | [producer] | [Before platform certification submission] | [Unresolved] |
| [Should damage numbers be pooled as Label3D nodes or rendered in a SubViewport? Verify performance budget in coordination with technical-director.] | [lead-programmer, ux-designer] | [Before combat HUD implementation] | [Unresolved] |
| [What is the maximum number of simultaneous toast notifications before the queue becomes visually overwhelming? Needs playtesting.] | [ux-designer] | [First playtesting session] | [Unresolved] |
| [Add question] | [Owner] | [Deadline] | [Resolution] |