Auto Warz — UI/UX Design Document¶

Document Type: System Design — UI/UX Version: 0.7 Status: In Progress Last Updated: 2026-09-11 Vault destination: 01_Design Documents Phase: Phase 1 — Launch release 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](<../Systems/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
#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 (War Update)
#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 interface has two jobs. Tell me what my factory is doing wrong, and mark the moments. Everything else is chrome.

Added 2026-09-11. The first job is why Analytics, Power, Production and Pollution exist. The second is why the game feels like anything. The principles below are how those two jobs are carried out; the sentence above is the test for whether a proposed panel, tab or readout should exist at all.

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.

This is the building's whole control surface. Recipe, ports, modules and upgrades are all configured here, and all of them apply instantly — none is a Genesis task. It is also the only screen that answers why is this building not working, which is a job it has to do deliberately rather than by accident (§Prerequisites, below).

┌───────────────────────────────────────────────┐
│ SMELTER                    Base Mk1 · Mk1  [X]│
│ ───────────────────────────────────────────── │
│ ⚠ NEEDS                                       │
│   No OUTPUT port set — nothing can leave       │
│ ───────────────────────────────────────────── │
│ RECIPE   Iron Plate               (only recipe)│
│ ───────────────────────────────────────────── │
│ IN    raw_metal_ore      ░░░░░      3 / 10     │
│ OUT   ref_metal_plate    ████░      8 / 10     │
│ ───────────────────────────────────────────── │
│ POWER    30 PU                                 │
│ ───────────────────────────────────────────── │
│ PORTS                              8 on 4 faces│
│   N  ▣ INPUT  any        E  ▣ INPUT  any       │
│   S  ○ closed            W  ◇ OUTPUT ref_metal…│
│ ───────────────────────────────────────────── │
│ ROOF SLOTS                                 2   │
│   1  Efficiency        −15% draw      [Upgrade]│
│   2  (empty)                          [Install]│
│ ───────────────────────────────────────────── │
│ Production  1 plate / 40 ticks                 │
└───────────────────────────────────────────────┘

Status¶

The panel carries the precise readout; the building itself carries the ambient one. The base ring and the machine body signal fault state in the world ([07_Art Direction Style Bible](<../../03_Art & Audio/07_Art Direction Style Bible.md>) §1.6–§1.7b), and this panel is where the exact figure lives.

Healthy is unlit. A working building shows nothing on the status channel, so the panel does not report a colour for "running" either — it reports the rate
Never tint the whole building. Fault state lives on the base ring, not on the body
Fault text mirrors the ring's meaning: amber for logistics, red for power, with the rhythm distinguishing states within each

Recipe¶

Per [04_Factory & Resource System Design](<../Systems/04_Factory & Resource System Design.md>) → Recipe Selection, and the presentation depends on the building:

Building	Shown as
Multi-recipe — Assembly Machine, Advanced Assembly, the presses	A selector
Single-recipe — Smelter, Refinery, Chemical Plant, Wire Extruder	A label, not a dead control
Extraction — drills, pumps, harvesters	What it extracts. No recipe concept applies

Changing a recipe warns first when a job is mid-production, and flags any explicit port filter the new recipe cannot use rather than clearing it.

Ports¶

Per [23_Port System Design](<../Systems/23_Port System Design.md>) §5.1b and §9a. Every port on every face is listed and configurable here, and configuration is an instant UI action — a port already exists, so opening or closing one places nothing and needs no bot.

Ports default to DISABLED, so a freshly placed building does nothing until this section is used. That is exactly the kind of silence the NEEDS block exists to break.

Roof slots¶

Per [24_Module System Design](<../Systems/24_Module System Design.md>) §2.2. Slot count is not researched. It comes from footprint size class plus Machine Mk, so every building has at least one slot the moment it is placed:

Size class	Mk1	Mk2	Mk3
Small	1	2	3
Medium	2	3	4
Large	3	4	5
Huge	4	5	6

Slots are fixed and independent. There is no stack, no order, and no adjacency
An empty slot reads (empty) with an [Install] action — never "greyed until researched"
A filled slot shows the module, its effect, and an [Upgrade] action

Installing and upgrading happen on this one screen. A module is upgraded where it sits, using the Upgrade Kit pattern — a crafted item applied by Genesis in place that changes level and nothing else. There is no craft-a-replacement-and-swap-it flow.

That is what delivers two functions in one slot — the outcome the removed stacking model was reaching for — without reviving stacking. Nothing stacks; a module gains capability.

Prerequisites — what this building still needs¶

The panel's job is not only to show state. It is to show what this building still needs in order to work.

A building can be placed, powered and entirely idle for reasons nothing announces. The NEEDS block at the top of the panel is the answer, and it is deliberately the first thing under the title.

Condition	Shown as
No recipe set on a multi-recipe building	No recipe selected
No `OUTPUT` port configured	No OUTPUT port set — nothing can leave
Input buffer holds stock the current recipe cannot use	Holding N unusable — set an OUTPUT filter to drain it
A module whose dependency does not exist anywhere	Drone module installed, but no packing anywhere on this planet

The last one generalises from a real trap: a drone module with no packing is a dead investment, and the player currently discovers that only when nothing moves. The same shape covers ports defaulting to DISABLED, and any future capability with an off-screen dependency.

When a building is working and needs nothing, the block is absent — not present and empty. Healthy is unlit here too.

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)
A node states what its unlock still needs to be useful, not only what it costs. A capability whose dependency does not exist yet says so on the node — the same rule the Building Detail Panel's NEEDS block applies one level down. Spending research on a dead investment and discovering it later is the trap this closes
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

Tier	Border	Auto-fade	Acknowledgement
Info	Neutral	Yes — 3 seconds	No
Warning	Yellow	Yes — 5 seconds	No
Critical	Red	No	Yes — must click to dismiss
Primer	Neutral, softer, wider	Yes — 8 seconds	No
Moment	Not a toast	—	—

Primer and Moment are not urgency, which is why they sit outside the ladder rather than above Critical. A Primer says something is new and teaches once, at the moment of first relevance. A Moment marks a beat from [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>), fires once as world state, and never takes input. ⚠️ A primer must never be given a warning colour — it is good news, and colouring it yellow would teach the player that learning something is a problem.

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 (War Update)¶

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: [04_Cross-Platform Strategy](<../../02_Technical Documents/04_Cross-Platform Strategy.md>)

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.
0.8	2026-08-30	Building Detail Panel rewritten and Module Stack UI deleted (OI-305, OI-306, OI-307). Six removed decisions were still specified here in the one document someone would implement the screen from: researched module slots, the whole stacking model, `Stack position`, `Combined effect`, a `Speed Module II` implying confirmed tiers, and a status line carrying both green-for-running and whole-building tint. Replaced with fixed roof slots from footprint plus Machine Mk, in-place upgrade via the Upgrade Kit pattern, and status that defers to the base ring with healthy unlit. The panel now also carries recipe selection and port configuration, which it never had, and a NEEDS block stating what a building still requires in order to work — generalised from the drone-module-without-packing trap to cover unset ports, unset recipes and stranded stock. Research tree overlay gains the same rule one level up.