GUI Development Plan

Development roadmap for The Fall of Babylon’s graphical user interface, based on the constructivist/brutalist design principles defined in Visual Design Guidelines.

Design Philosophy

Visual Language

Soviet Constructivist/Avant-garde aesthetics
Brutalist/Industrial design elements
Propaganda poster-inspired compositions
Geometric shapes and dynamic diagonals

Color Scheme

PRIMARY_COLORS = {
    "soviet_red": "#D40000",   # Main accent, alerts
    "near_black": "#1A1A1A",   # Primary backgrounds
    "off_white": "#F5F5F5",    # Secondary text
    "gold": "#FFD700",         # Achievements
}

SECONDARY_COLORS = {
    "dark_red": "#8B0000",     # Shadows, depth
    "dark_gray": "#404040",    # Interface borders
    "silver": "#C0C0C0",       # Inactive elements
}

Interface Structure

Main Window Layout

The interface is divided into four primary panels:

Left Panel: Contradiction Map

Network visualization of dialectical relationships
Interactive graph using matplotlib
Dark background (#1A1A1A)
Soviet red (#D40000) for critical relationships
Geometric node shapes
Grid overlay in dark gray (#404040)

Center Panel: Detail View

Primary information display
Clear typography hierarchy (Headers: Futura Bold, Body: Univers, Data: Roboto Mono)
High contrast text on dark background
Constructivist-inspired section dividers

Right Panel: Status Indicators

Economic and social metrics display
Monospace font for data
Soviet-inspired header styling
Industrial/mechanical appearance
Clear data visualization elements

Bottom Panel: Event Log & Command Line

Console-style interface
Soviet red prompt symbol
Monospace font for commands
Industrial/terminal styling

Interactive Elements

Buttons

Sharp geometric shapes
Clear hover states
Soviet red accents
Mechanical click feedback
Distinct active/inactive states

Input Fields

Industrial styling
Minimal borders
Soviet red text cursor
Clear focus states
Monospace font for input

Scrollbars

Thin, geometric design
Dark gray track
Soviet red thumb
Minimal but functional

Data Visualization

Graphs and Charts

Geometric shapes
Strong grid systems
Soviet-inspired color scheme
Clear data hierarchies
Industrial styling

Status Indicators

Mechanical/gauge-like displays
Binary state indicators
Progress bars with geometric styling
Numerical displays in monospace font

Implementation Phases

Phase 1: Core Layout

Implement main window frame
Set up four primary panels
Configure basic styling
Establish color scheme

Phase 2: Panel Development

Contradiction Map

Set up matplotlib integration
Implement network visualization
Add interaction handlers
Style graph elements

Detail View

Implement text display system
Set up typography hierarchy
Add content formatting
Style scrolling and selection

Status Panel

Create metric displays
Implement data updating
Style indicators
Add tooltips

Command Interface

Implement command input
Set up event logging
Style console elements
Add command history

Phase 3: Interactive Elements

Implement button system
Create input field handlers
Add hover and click effects
Implement scrolling behavior

Phase 4: Data Visualization

Set up chart rendering
Implement real-time updates
Add interaction handlers
Style visualization elements

Phase 5: Polish and Optimization

Refine animations
Optimize performance
Add accessibility features
Implement error handling

NiceGUI Mode Selection

NiceGUI has mutually exclusive modes. Choose ONE pattern and stick to it.

Warning

Never mix @ui.page decorator with global-scope UI elements. This causes RuntimeError at startup.

Root Function Pattern (Recommended)

For single-page applications like Babylon MVP:

from nicegui import ui

def main_page() -> None:
    """Root function - all UI defined here."""
    ui.dark_mode().enable()

    with ui.column().classes("w-full items-center p-4"):
        ui.label("BABYLON v0.3").classes("text-green-400 font-mono")
        # ... more UI elements ...

    # Timer MUST be inside root function
    ui.timer(interval=1.0, callback=run_loop)

if __name__ == "__main__":
    ui.run(main_page, title="Babylon v0.3", port=6969)

Key rules:

No @ui.page decorator for single-page apps
All UI elements inside the root function
ui.timer() must be inside root function, not global scope
Pass root function as first positional argument to ui.run()

Page Decorator Pattern (Multi-page Only)

Only use this for multi-page applications:

from nicegui import ui

@ui.page("/")
def index():
    ui.label("Home")

@ui.page("/settings")
def settings():
    ui.label("Settings")

# NO global UI elements allowed!
ui.run()

Note

See ai-docs/decisions.yaml:ADR026_nicegui_root_function_pattern for the full architectural decision record.

Technical Considerations

Typography System

FONTS = {
    "header": ("Futura", 14, "bold"),
    "body": ("Univers", 11),
    "mono": ("Roboto Mono", 10),
}

Styling Constants

STYLE = {
    "bg": "#1A1A1A",
    "fg": "#F5F5F5",
    "accent": "#D40000",
    "border_width": 1,
    "padding": 10,
}

Layout Management

Use ui.row() and ui.column() for flex layouts
Apply Tailwind CSS classes via .classes() method
Use with context managers for nested containers
Maintain consistent spacing via Tailwind utilities (p-4, gap-4)

Performance Optimization

Lazy loading for complex visualizations
Efficient event handling
Memory management for large datasets

Accessibility Features

High contrast color options
Keyboard navigation support
Screen reader compatibility
Configurable text sizing
Alternative text for visualizations

Testing Strategy

Unit tests for UI components
Integration tests for panel interactions
Performance testing under load
Cross-platform compatibility testing
Accessibility compliance testing

Future Enhancements

Theme customization system
Advanced visualization options
Additional data display modes
Enhanced interaction patterns
Expanded keyboard shortcuts