GUI Development Plan
====================

Development roadmap for The Fall of Babylon's graphical user interface,
based on the constructivist/brutalist design principles defined in
:doc:`/concepts/aesthetics`.

Design Philosophy
-----------------

Visual Language
~~~~~~~~~~~~~~~

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

Color Scheme
~~~~~~~~~~~~

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~~~~

1. Implement main window frame
2. Set up four primary panels
3. Configure basic styling
4. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Implement button system
2. Create input field handlers
3. Add hover and click effects
4. Implement scrolling behavior

Phase 4: Data Visualization
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Set up chart rendering
2. Implement real-time updates
3. Add interaction handlers
4. Style visualization elements

Phase 5: Polish and Optimization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Refine animations
2. Optimize performance
3. Add accessibility features
4. 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:

.. code-block:: python

   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:

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

Page Decorator Pattern (Multi-page Only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Only use this for multi-page applications:

.. code-block:: python

   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
~~~~~~~~~~~~~~~~~

.. code-block:: python

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

Styling Constants
~~~~~~~~~~~~~~~~~

.. code-block:: python

   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
----------------------

1. High contrast color options
2. Keyboard navigation support
3. Screen reader compatibility
4. Configurable text sizing
5. Alternative text for visualizations

Testing Strategy
----------------

1. Unit tests for UI components
2. Integration tests for panel interactions
3. Performance testing under load
4. Cross-platform compatibility testing
5. Accessibility compliance testing

Future Enhancements
-------------------

1. Theme customization system
2. Advanced visualization options
3. Additional data display modes
4. Enhanced interaction patterns
5. Expanded keyboard shortcuts

See Also
--------

- :doc:`/concepts/aesthetics` - Visual design philosophy (Bunker Constructivism)
- :doc:`/reference/design-system` - Complete design tokens reference
- :doc:`/concepts/architecture` - System architecture
- :doc:`/reference/configuration` - Configuration system