Auto Warz — UI/UX Design Document¶

Document Type: System Design — UI/UX Version: 0.6 Status: In Progress Last Updated: 2026-03-31 Vault destination: 01_Design Documents Author: Solo Developer Parent Document: [01_Master GDD](<./01_Master GDD.md>) Related Documents: [01_Technical Architecture Document](<../02_Technical Documents/01_Technical Architecture Document.md>) · [04_Factory & Resource System Design](<./04_Factory & Resource System Design.md>) · [01_Art Direction Document](<../03_Art & Audio/01_Art Direction Document.md>) · [16_HUD Layout Design](<./16_HUD Layout Design.md>) · [17_HUD Panel Flap](<./17_HUD Panel Flap.md>) · [18_Notifications](<./18_Notifications.md>)

Table of Contents¶

#Purpose of This Document
#Design Philosophy
#UI Themes
#Screen Flow Map
#HUD Layout
#The Two Flaps
#Genesis Status & Task Queue
#Mini-Map
#Build Menu
#Building Detail Panel
#Module Stack UI
#Research Tree Overlay
#Session Menu
#Multiplayer Panels
#Notification System
#Supply Chain Diagnostic Overlay
#Global Factory Overview
#Blueprint Library
#Settings Screen
#Typography & Iconography
#UI Component Library
#Mobile UI Considerations (Phase 3)
#Implementation Notes (Godot 4)
#Revision History

Purpose of This Document¶

This document defines every screen, panel, and UI element in Auto Warz Phase 1. It is the reference for all UI implementation work — designed in collaboration with Claude.ai, implemented in Godot 4.

For detailed HUD layout specification see [16_HUD Layout Design](<./16_HUD Layout Design.md>). For detailed flap tab specifications see [17_HUD Panel Flap](<./17_HUD Panel Flap.md>). For notification system specification see [18_Notifications](<./18_Notifications.md>).

Design Philosophy¶

The world comes first — UI never obscures more of the game world than necessary
One click to anything important — nothing needed regularly is more than one click away
Colour is communication — Green = good, Yellow = warning, Red = problem, Blue = info. Never decorative.
Readable at a glance — icons carry meaning without labels; labels appear on hover
Forgiving interactions — nothing destructive happens without confirmation
Symmetric layout — two flaps, one on each side, mirror each other structurally
Always running — the factory never pauses when UI panels are open

UI Themes¶

Players toggle between themes via Settings. Persists across sessions.

Theme 1 — Dark (Default)¶

Element	Colour
Panel background	`#1A1E2E`
Panel border	`#2E3A5C`
Primary text	`#E8EAF0`
Secondary text	`#8A9BB8`
Accent	`#4FC3F7`
Success	`#66BB6A`
Warning	`#FFA726`
Danger	`#EF5350`
Button primary	`#2979FF`

Theme 2 — Light¶

Element	Colour
Panel background	`#F0F4FF`
Panel border	`#C5D0E8`
Primary text	`#1A1E2E`
Secondary text	`#5A6A8A`
Accent	`#1565C0`
Success	`#388E3C`
Warning	`#E65100`
Danger	`#C62828`
Button primary	`#1565C0`

Screen Flow Map¶

MAIN MENU
├── New Session → Session Setup Screen → Game (HUD)
├── Load Session → Session Browser → Game (HUD)
├── Join Session → Join by IP → Lobby → Game (HUD)
├── Settings → Settings Screen
└── Quit

GAME (HUD)
├── [Left flap handle / ESC] → Left flap (session management)
├── [Right flap handle] → Right flap (factory information)
├── [T] Research Tree (full screen — pauses if solo)
├── [O] Supply Chain Overlay (world overlay)
├── [M] Full Planet Map (full screen)
├── Click Building → Building Detail Panel (right side)
├── Click Module Cube → Module Detail / Remove
└── Notification toast → Click → Jump to issue / open Log tab

HUD Layout¶

Full specification in [16_HUD Layout Design](<./16_HUD Layout Design.md>). Summary below.

┌──────────────────────────────────────────────────────────────────────┐
│ [AW] [Solo · 1P]          KERATH-IV 🌍          12:34:56  00:14:32  │  ← Top bar
├──────────────────────────────────────────────────────────────────────┤
│◀                           GAME WORLD                              ▶│  ← Flap handles
│                                                                      │
│                                                         ┌──────────┐ │
│                                                         │  MINIMAP │ │
│                                                         └──────────┘ │
├──────────────────────────────────────────────────────────────────────┤
│ [GNS][▶card][card][card][+2]   [Drill][Smelt][Chest][Belt][Conn]    │  ← Bottom bar
└──────────────────────────────────────────────────────────────────────┘

Top Bar Zones¶

Zone	Top Row	Bottom Row
Left	Logo mark (AW)	Session type + player count
Centre	Planet icon + Planet name	—
Right	Real-world clock	Session timer

Bottom Bar¶

Single row. Three sections: - Left — Genesis avatar button + horizontal task queue. Anchored left, queue grows right. - Centre — Build toolbar. Absolutely centred, never moves regardless of queue length. - Right — Minimap. Floating, anchored bottom-right corner, twice the height of the bar.

The Two Flaps¶

Full specification in [17_HUD Panel Flap](<./17_HUD Panel Flap.md>). Summary below.

The flap system replaces the old right column and session menu modal. Two persistent handles sit on the left and right edges of the screen below the top bar.

Left Flap — Session Management¶

Default: Collapsed. Opened by ESC or clicking the handle.

Tabs: Save · Load · Settings · Session Info · Exit

Right Flap — Factory Information¶

Default: Expanded. Player can collapse and set collapsed as new default.

Tabs: Inventory · Power · Analytics · Production · Contributions · Log

Attention System¶

Collapsed: Handle glows/pulses if any tab needs attention. Handle bounces/prods out from screen edge for critical alerts.
Expanded: Individual tab icons glow/pulse. Handle stays neutral.

Genesis Status & Task Queue¶

Genesis status and the task queue live in the bottom bar left section — not in a right column panel. This is a significant change from v0.5.

Genesis Avatar Button (GNS-1)¶

Leftmost element of the bottom bar. Always visible.
Click or press G to toggle Genesis selection.
Status dot: blue = idle, green = active/selected.
When queue is empty, this is the only element in the left section.

Task Queue — Horizontal Timeline¶

Cards flow to the right of the avatar button.

Active card — larger, leftmost, fixed width. Never compresses.
Queued cards — smaller. Compress if space runs out. Cap with +N overflow badge if still too many.

Card Anatomy¶

Large subject icon — coloured by building category
Small badge top-right — task type:
Hammer = BUILD
Pickaxe = MINE
Wrench = REPAIR
Arrow = MOVE TO
Hourglass = WAITING AT CHEST
Material stacks — bright cubes = deposited, ghost cubes = still needed
Progress bar — active card only, bottom strip
Border colour = status: Green / Yellow / Red
Cancel button (✕) — on hover, top-left corner

Fetch tasks have no card — internal Genesis operation only.

Drag to reorder — research-gated, unlocked in M3.x.

Genesis is the player's embodiment — wherever the player's focus is (planet or space), Genesis is there. The planet factory runs autonomously when Genesis is in the space layer.

Mini-Map¶

Position: Floating, anchored bottom-right corner. Overlaps world upward. Twice the height of the bottom bar. Square proportions.

Always shows a viewport indicator rect — the exact area the camera currently sees
Buildings shown as coloured dots (category colour)
Resource nodes shown as category-colour dots
Genesis position — blue pulsing dot
Click anywhere on minimap → camera jumps to that location
Press M → opens Full Planet Map (full screen)

Full Planet Map (`M`)¶

┌──────────────────────────────────────────────────┐
│  🗺️ PLANET MAP — Kerath-IV              [M / X]  │
│  [🏭 Buildings] [⚡ Power] [🚂 Rail] [☠️ Aliens] │
│                                                  │
│         [full planet top-down view]              │
│                                                  │
│  Legend: 🟤 Extract  🟠 Process  🔵 Assembly     │
└──────────────────────────────────────────────────┘

Layer toggles show/hide building types, power ranges, rail, alien zones
Click anywhere → jump camera and close map
M or Escape to close without moving

Bottom bar centre section. Always visible. Absolutely centred — never moves.

Category Groups¶

Buildings grouped by category with vertical category labels:

Category	Colour	Buildings (Phase 1)
Extract	`#E8871A`	Mining Drill
Process	`#D4431A`	Smelter
Storage	`#8B4FC8`	Storage Chest
Logistics	`#3A82C4` / `#2ABFBF`	Belt Segment, IO Connector

More categories added as milestones unlock them (Power, Research, Defence, Construction).

Building Buttons¶

Each button shows: - Building icon (clean line SVG, category colour) - Building name below - Keyboard shortcut top-right corner - Category colour bottom-edge indicator - Lock icon if not yet researched

Hover tooltip: name, grid size, power cost, output, research requirement.

Build Mode vs Plan Mode¶

Build Mode (default): - Click a building card → placement ghost appears (green = valid, red = invalid) - Left click to place → queued as Genesis task - Persistent build ghost remains until Genesis completes construction - Ghost blocks placement on those cells - As Genesis builds, ghost fills progressively bottom to top, transitions to solid asset on completion - Right-click ghost in world to cancel task

Plan Mode (toggle — bottom-left of build menu): - Place ghosts freely without queuing Genesis tasks - Screen border tints blue to indicate Plan Mode is active - Right-click a ghost to remove it - Switch back to Build Mode to commit planned ghosts as tasks

Building Detail Panel¶

Click any placed building → slides in from the right side. Clicking elsewhere closes it.

┌──────────────────────────────────┐
│ 🟠 SMELTER                   [X] │
│ Status: ⏳ Waiting for ore       │
│ ─────────────────────────────── │
│ INPUT   Metal Ore     ░░░░░ 3/10 │
│ OUTPUT  Metal Plates  ████░ 8/10 │
│ ─────────────────────────────── │
│ ⚡ Power    30 PU / 30 PU        │
│ 🔧 Modules  0 / 0 slots          │
│ ─────────────────────────────── │
│ Production: 1 plate / 40 ticks   │
└──────────────────────────────────┘

⚠️ This panel sketch predates several decisions and is tracked for rewrite as OI-305. Two things it is missing outright: recipe selection, specified in [04_Factory & Resource System Design](<./04_Factory & Resource System Design.md>) -> Recipe Selection, and port configuration, specified in [23_Port System Design](<./23_Port System Design.md>) §5.1b and §9a. Both are instant panel actions and both belong here. The rewrite must carry them; neither is restated in this document.

Status uses building state colours (green/yellow/orange — matches building mesh colour)
Input/output bars show current inventory vs capacity
Power shows actual draw vs maximum draw
Module slots show filled/available (greyed if no slots researched yet)
Click a filled module slot → opens Module Detail popup

Module Stack UI¶

Modules are physical cubes stacked on top of buildings. Each placed module adds one cube of height.

Click a module cube in the world or a slot in the Building Detail Panel:

┌─────────────────────────────┐
│ 🟦 Speed Module II      [X] │
│ Effect: +25% output rate    │
│ Stack position: 2 of 3      │
│ Combined effect: +45%       │
│ ─────────────────────────── │
│ [Remove Module]             │
└─────────────────────────────┘

Shows individual effect and combined stacked effect
Stack position matters — effects apply bottom to top
Remove costs nothing but module goes back to inventory, not refunded as resources

Research Tree Overlay¶

Press T → full screen overlay. Pauses simulation in solo. Does not pause in multiplayer.

┌──────────────────────────────────────────────────────────┐
│ 🔬 RESEARCH TREE                              [T / X]    │
│ [Basic] [Advanced] [Power] [Logistics] [Defence] [Faction]│
├──────────────────────────────────────────────────────────┤
│                                                          │
│   [Node]──[Node]──[Node]                                │
│       └──[Node]                                         │
│                                                          │
│ 📋 Science Drive: 240 banked  · 12.5 RP/min             │
└──────────────────────────────────────────────────────────┘

Nodes: unlocked (bright), available (dim with cost), locked (greyed, shows prerequisite)
Click available node → confirm → consume Science Drives → unlock
Faction Research tab appears only when Allied with a faction
T or Escape to close

Replaced by the Left Flap. ESC opens the left flap instead of a modal overlay.

The left flap contains: Save · Load · Settings · Session Info · Exit

See [17_HUD Panel Flap](<./17_HUD Panel Flap.md>) for full specification.

Note: SessionMenu.gd and its scene node will be replaced by LeftFlap.gd in M2.7.

Multiplayer Panels¶

Player List¶

Accessible via Session Info tab in the left flap.

┌──────────────────────────────┐
│ 👥 PLAYERS (3/8)         [X] │
│ 🟢 HostPlayer    [HOST]      │
│ 🟢 Player2                   │
│ 🟡 Player3 (connecting...)   │
│ [Copy Session IP]            │
└──────────────────────────────┘

Chat Panel¶

Accessible via a dedicated chat button (multiplayer sessions only)
Enter to open and type
System messages in italic
Max 100 messages, scrollable

Notification System¶

Full specification in [18_Notifications](<./18_Notifications.md>). Summary below.

Toast Notifications¶

Appear top-centre of screen, below the top bar
Chirper-style — brief, charming, non-intrusive
Slide in from above, pause, fade out and slide back up

Level	Border	Auto-fade	Acknowledgement
Info	Neutral	Yes — 3 seconds	No
Warning	Yellow	Yes — 5 seconds	No
Critical	Red	No	Yes — must click to dismiss

Max 3 toasts visible simultaneously — critical toasts take priority slots
Click any toast → jumps to issue in world or opens Log tab
Duplicate notifications within 10 seconds are grouped: "Belt blocked (×4)"

Log¶

Full notification history in the right flap Log tab. Filterable by level, system, and time.

Supply Chain Diagnostic Overlay¶

Toggle O. Overlays world without covering HUD. Game keeps running.

Belt Colours¶

🟢 Full · 🟡 Partial · 🔴 Stalled · ⚫ Empty

Building Colours¶

🟢 Running · 🟡 Waiting · 🟠 Output Full · 🔴 No Power · ⚫ Disabled

Additional¶

Animated directional arrows on belts
Bottlenecks pulse red
Power connection ranges shown as faint circles around buildings

Global Factory Overview¶

Deferred to right flap tabs. The information previously shown in the Factory Overview (F key full screen) is now distributed across the right flap:

Power → Right flap Power tab
Resource throughput → Right flap Inventory + Analytics tabs
Active alerts → Right flap Log tab + toast notifications
Production chain → Right flap Production tab

The F key and full-screen Factory Overview are removed. All factory data lives in the right flap.

Blueprint Library¶

P or last Build Menu tab.

Blueprint cards with thumbnail, name, [Place], [Share]
[+ New] → select area in world to save
Blueprints persist across sessions
Blueprint strings shareable via chat
Right-click card: Rename / Delete

Settings Screen¶

Accessible via the Settings tab in the left flap.

Display¶

Resolution · Display Mode · UI Theme · UI Scale · FPS counter

Audio¶

Master · Music · SFX · UI volume sliders

Controls¶

Full keybinding remapper · Mouse/scroll sensitivity · Invert camera pan Y

Gameplay¶

Auto-save interval
Confirm before delete (default ON)
Show belt throughput by default
Notification duration
Auto-dismiss error notifications (Off / 30s / 60s / 5min — default Off)

Accessibility¶

Colourblind mode · Large text mode · Reduce animations

Typography & Iconography¶

Primary font: Orbitron (display, titles, logo) — sci-fi, characterful
UI font: Rajdhani (labels, buttons, building names) — clean, readable
Data font: Share Tech Mono (numbers, stats, clocks) — monospace, prevents layout shift

Use	Font	Size
Logo / panel titles	Orbitron	13–20px
Building names / labels	Rajdhani	11–14px
Numbers / stats / clocks	Share Tech Mono	10–15px

Icons: clean line SVG, coloured by category or status. Single colour per icon. Colourblind fallbacks. Sources: Lucide / Phosphor open sets.

UI Component Library¶

Panel · Button (primary/secondary/danger) · IconButton · Label
ProgressBar · ResourceBadge · Tooltip · Toast
Tab Bar · ScrollContainer · Dropdown · TextInput · Slider
FlexCard (task queue card — active and queued variants)
ModuleChip (colour-coded module representation in building panel)
FlapHandle (left and right flap trigger)
MinimapDot (coloured dot per building/resource/Genesis)

Mobile UI Considerations (Phase 3)¶

All UI sized with anchors, not fixed pixels
No hover interactions — touch targets minimum 44×44px
Bottom bar translates naturally to mobile
Flap handles become swipe gestures on mobile
Building detail panel → bottom sheet on mobile
Genesis avatar button → tap to select/deselect

See: [[03_Cross-Platform Strategy]]

Implementation Notes (Godot 4)¶

Theme System¶

res://assets/ui/theme_dark.tres and theme_light.tres
Swap root Control node theme → all children update instantly
Font sizes and icon sizes defined in theme, not per-node

Viewport Scaling¶

Base resolution: 1920×1080
Stretch mode: canvas_items, aspect: expand
UI scales proportionally, game world fills extra space

Scene Structure¶

UI (CanvasLayer)
├── HUD
│   ├── TopBar
│   │   ├── LogoMark
│   │   ├── SessionInfo (type + player count)
│   │   ├── PlanetDisplay (icon + name)
│   │   ├── RealClock
│   │   └── SessionTimer
│   ├── BottomBar
│   │   ├── GenesisSection
│   │   │   ├── GenesisBtn (GNS-1)
│   │   │   └── QueueStrip (task cards)
│   │   ├── BuildToolbar (absolutely centred)
│   │   └── BarRightSpacer (reserves minimap space)
│   ├── Minimap (floating, anchored bottom-right)
│   ├── LeftFlapHandle
│   └── RightFlapHandle
├── LeftFlap
│   ├── SaveTab
│   ├── LoadTab
│   ├── SettingsTab
│   ├── SessionInfoTab
│   └── ExitTab
├── RightFlap
│   ├── InventoryTab
│   ├── PowerTab
│   ├── AnalyticsTab
│   ├── ProductionTab
│   ├── ContributionsTab
│   └── LogTab
├── Panels
│   ├── BuildingDetailPanel
│   ├── ModuleDetailPopup
│   └── PlayerListPanel
├── ToastManager
└── Overlays
    ├── ResearchTreeOverlay
    ├── SupplyChainOverlay
    ├── FullPlanetMapOverlay
    └── BlueprintLibraryOverlay

Animation¶

Flap expand/collapse: 0.2s ease-out Tween
Toasts slide in from above: 0.15s ease-out
Flap handle bounce: 0.3s ease-in-out, repeating until resolved
No animation exceeds 0.3s (except repeating attention bounce)

Signals¶

UI → game systems via signals only, never direct references
ToastManager.notify(message, level, system) — global notification entry point

Open items for this document are tracked in docs/open-items.md, area ui.

Revision History¶

Version	Date	Changes
0.1	2026-02-22	Initial draft
0.2	2026-02-22	HUD layout redesign, minimap top-right, alert panel, Planet Power Drawer, research tree solo pause, error manual dismiss, Defence tab
0.3	2026-02-22	Power bar removed from HUD (multiple grids), power per-grid in Overview, Module Stack UI added
0.4	2026-02-27	Genesis status chip + Task Queue moved to top-right panel
0.5	2026-02-27	Genesis fully autonomous, Plan mode toggle, War mode toggle, task reorder research-gated
0.6	2026-03-31	Major redesign — symmetric two-flap system replaces right column and session menu modal. Top bar rejig (logo/session left, planet centre, clocks right). Bottom bar single row (Genesis+queue left, toolbar centre, minimap floating right). Genesis queue horizontal timeline. Factory Overview full screen removed — data moved to right flap tabs. Session menu replaced by left flap. Typography updated to Orbitron/Rajdhani/Share Tech Mono. Scene tree updated. References added to new docs 16, 17, 18.
0.7	2026-08-30	Building Detail Panel flagged as missing recipe selection and port configuration, both now specified elsewhere and both belonging in this panel. Pointer only - the rewrite itself is OI-305.