The-Somnus-Project/docs/front-end-spec.md

Stasis Warden UI/UX Specification (ASCII/TUI Edition)

This document defines the user experience goals, information architecture, user flows, and interaction design specifications for Stasis Warden's ASCII-based Terminal User Interface (TUI). It serves as the foundation for interface design and frontend development using the Textual library for Python, ensuring a cohesive and user-centered experience that embraces the ASCII aesthetic.

1. Introduction

1.1. Overall UX Goals & Principles

1.1.1. Target User Personas

• Retro Computing Enthusiast: Players who appreciate the nostalgia and unique challenge of ASCII interfaces.
• Strategy Game Enthusiast: Players who enjoy deep, strategic gameplay with emergent narratives. They value complex systems that interact in meaningful ways.
• Narrative-Focused Gamer: Players who are drawn to story-rich experiences where the narrative unfolds through gameplay mechanics rather than cutscenes.
• Indie Game Supporter: Players who appreciate unique, creative games that push boundaries and offer something different from mainstream titles.

1.1.2. Usability Goals

• Immersive Experience: Create a seamless diegetic interface that reinforces the narrative of being the ship's AI, now presented through an ASCII terminal.
• Intuitive Expansion: Make the room expansion and crew management systems easy to understand and execute via keyboard.
• Clear Feedback: Provide immediate, understandable feedback for all player actions through text and simple ASCII animations.
• Strategic Depth: Offer meaningful choices in room selection and crew assignment that impact gameplay.

1.1.3. Design Principles

1. Diegetic Design: All interface elements should feel like part of the ship's systems, presented through an ASCII terminal output.
2. Functional Aesthetic: Embrace the clean, functional beauty of ASCII characters to create a unique atmosphere.
3. Tactile Interaction: Make keyboard interactions feel responsive and satisfying, reinforcing the direct control of the ship's systems.
4. Progressive Complexity: Start with a simple interface but allow for deeper layers of information and control as the player progresses.
5. Narrative Integration: Every UI element should contribute to the story of rediscovering the AI's identity through the lens of a terminal interface.

2. Information Architecture (IA)

2.1. Screen Inventory

The game will primarily operate within a single, dynamic TUI screen managed by Textual. Key conceptual areas include:

• Main Ship View/Map: A central area displaying the ASCII representation of the ship layout.
• Resource Panel: A dedicated section (e.g., left side) to track key resources like Power.
• Crew Roster: A dedicated section (e.g., right side) listing all crew members.
• Status/Log Panel: A section (e.g., bottom) for game messages, prompts, and feedback.
• Room Card Selection Area: A temporary, modal-like area that appears to present room choices.
• Main Menu: Accessible via a key command (e.g., Esc or M), presenting options like Save/Load/Options.

2.2. Navigation Structure

Primary Navigation:

• Keyboard-driven navigation and commands. Core gameplay actions (selecting rooms, assigning crew) will be performed via key presses and text commands.

Secondary Navigation:

• Temporary UI elements (like the Room Card Selection Area) for specific choices.
• Contextual commands that appear based on the selected game object or current state.

Focus Strategy:

• Use Textual's focus management to highlight the currently active panel or element (e.g., the selected room on the map, the highlighted crew member in the roster).

3. User Flows

3.1. Primary Gameplay Loop

User Goal: Progress through the core gameplay loop of generating power, expanding the ship, awakening crew members, and assigning tasks, all via an ASCII TUI.

Entry Points:

• Starting a new game
• Loading a saved game

Success Criteria:

• Player successfully generates power through a keyboard command.
• Player unlocks a new room using power.
• Player selects a room type from the Room Card Selection Area.
• Player awakens a crew member.
• Player assigns a crew member to generate power automatically.

graph TD
    A[Start Game] --> B[View Power Core Room]
    B --> C[Press Key/Button to Generate Power]
    C --> D[Accumulate Sufficient Power]
    D --> E[Select Adjacent Locked Door]
    E --> F[Confirm Unlock Cost]
    F --> G[Unlock New Room Space]
    G --> H[Room Card Selection Area Appears]
    H --> I[Select Room Card via Key]
    I --> J[Build New Room]
    J --> K[Enter Cryo Stasis Room]
    K --> L[Select Stasis Pod]
    L --> M[Confirm Awakening Cost]
    M --> N[Awaken Crew Member]
    N --> O[Assign Crew to Power Core]
    O --> P[Automatic Power Generation]
    P --> C

Edge Cases & Error Handling:

• Player attempts to unlock a door without sufficient power.
• Player attempts to awaken a crew member without sufficient power.
• Player tries to assign a crew member to a task they're already assigned to.
• Invalid keyboard input.

Notes: This flow represents the core loop that players will engage with repeatedly. Each cycle should feel satisfying and progress the narrative of rebuilding the ship and rediscovering the AI's identity.

4. Interface Design & Layout

4.1. Primary Design Approach

Development will be done directly in Python using the Textual library. The interface will be built using Textual's widget system and layout engine, which are based on CSS-like concepts but adapted for terminal environments.

4.2. Key Screen Layouts

4.2.1. Main Game View

Purpose: Display the ASCII map of the ship with integrated panels for resource management, crew roster, and game messages.

Key Elements (Conceptual Layout):

+----------------------------------------------------------+
| Resource Panel             | Ship Map           | Crew   |
|                            |                    | Roster |
| Power: 100                 | [###][###][###]    | John   |
|                            | [###][ P ][###]    | Mary   |
|                            | [###][###][###]    | ...    |
+----------------------------------------------------------+
|                         Status/Log Panel                 |
|                                                          |
| > Power generated.                                       |
| > Select a room to unlock.                               |
+----------------------------------------------------------+

Interaction Notes: Players will primarily interact via keyboard. The ship map area will be the primary focus for selection. Panels will update dynamically. A status/log area will provide continuous feedback.

4.2.2. Room Card Selection Area (Modal)

Purpose: Present the choice of new room types when unlocking a space.

Key Elements (Conceptual Layout):

+----------------------------------------------------------+
|                   Room Card Selection                    |
|                                                          |
| (A) Engineering Bay    (B) Hydroponics Bay   (C) Quarters|
| +----------------+     +----------------+   +-----------+|
| |Eff: +Power Gen |     |Eff: +Food Prod |   |Eff: +Morale||
| |Desc: ...       |     |Desc: ...       |   |Desc: ...    ||
| +----------------+     +----------------+   +-----------+|
|                                                          |
|                 Press A, B, or C to select               |
+----------------------------------------------------------+

Interaction Notes: This area will appear as a focused overlay or a distinct section within the main view when a room unlock is confirmed. Players will select an option via a single key press.

5. Component Concepts / Design System

5.1. Design System Approach

We will create a simple, focused design approach using Textual's capabilities for styling and layout, tailored for an ASCII aesthetic.

5.2. Core Component Concepts

5.2.1. Ship Map Grid

Purpose: Display the ASCII representation of the ship's layout and rooms.

Variants:

• Locked Room ([###])
• Unlocked Empty Space ([ ])
• Built Room ([PWR], [ENG], [CRY])

States:

• Normal (default)
• Selected (highlighted border or inverse video)
• Hover/Focus (if applicable, though keyboard focus is primary)

Usage Guidelines: Should be the central visual element. Selection should be clear and intuitive via keyboard navigation.

5.2.2. Resource Panel

Purpose: Display and manage key game resources like Power.

Variants:

• Simple numeric display (Power: 100)
• Bar graph using ASCII characters (Power: [=====-----] 50%)

States:

• Normal display
• Low resource warning (e.g., color change or ! prefix)
• Resource gain animation (simple text flash or change)

Usage Guidelines: Should be clearly visible but not distract from the central ship map.

5.2.3. Crew Roster Panel

Purpose: List all awakened crew members and provide access to their details.

Variants:

• Compact list view (Name (Stat: Value, Trait))
• Detailed view (accessible via selection, showing full stats and traits)

States:

• Idle
• Crew member selected
• New crew member added (highlight or animation)

Usage Guidelines: Should update in real-time as crew members are awakened and assigned to tasks.

5.2.4. Status/Log Panel

Purpose: Provide continuous feedback, game messages, and prompts.

Variants:

• Single line message (> Power generated.)
• Multi-line log (> Error: Insufficient power.\n> Action cancelled.)

States:

• Idle
• Receiving new message
• Scrolling (if it becomes a multi-line scrollable log)

Usage Guidelines: Should be the primary source of feedback. Important messages should be persistent until acknowledged or replaced.

6. Branding & Style Guide (ASCII Edition)

6.1. Visual Identity

The visual identity is defined by a clean, functional ASCII art style. The game will use a monospace font and primarily rely on text characters and simple layout to convey information and atmosphere.

6.2. Color Palette (Conceptual)

While the core is ASCII, limited color can be used effectively in terminals.

Color Type	Usage Concept
Primary	Main text, default UI elements
Secondary	Highlighted text, selected items
Accent	Important notifications, interactive elements
Success	Positive feedback
Warning	Cautions
Error	Errors
Neutral	Background, less important text

Note: Color usage will be kept simple and functional, respecting common terminal color schemes.

6.3. Typography

Font Families

• Primary: Monospace font (default terminal font). The experience is defined by the characters themselves.
• Secondary: Not applicable in a pure ASCII context.

Type Scale / Emphasis

• Bold/Inverse Video/Underline: Used via ANSI escape codes (supported by Textual) for emphasis (e.g., headers, selected items).
• Size: Not variable in a terminal, but layout and spacing will create visual hierarchy.

6.4. Iconography

Icons will be simple ASCII characters or small combinations.

• Power: *, ⚡
• Crew: @, &
• Locked Room: #
• Unlocked Room: . or space

6.5. Spacing & Layout

Grid System: Textual's layout engine will be used for consistent spacing. Spacing Scale: Managed by Textual's layout properties (margin, padding).

7. Accessibility Requirements

7.1. Compliance Target

Focus on fundamental accessibility principles for TUIs.

7.2. Key Requirements

Visual:

• High contrast is inherent in text-based interfaces.
• Clear visual indicators for focus (Textual handles this).
• Scalable text: Dependent on user's terminal settings.

Interaction:

• Keyboard Navigation: This is the only input method. All actions must be performable via keyboard.
• Screen Reader Support: Textual's output should be inherently screen-reader friendly.
• Logical tab order and clear focus states (handled by Textual).

Content:

• Alternative text: Not applicable in the same way, but clear, descriptive text labels are crucial.
• Heading structure: Use Textual's widgets to create a logical structure.

7.3. Testing Strategy

• Self-testing with different terminal emulators and color schemes.
• Ensuring all interactions are keyboard-accessible.
• Seeking feedback from the TUI/ASCII game community.

8. Responsiveness Strategy

8.1. Breakpoints

Terminal sizes are highly variable. The interface must be flexible.

8.2. Adaptation Patterns

Layout Changes:

• Textual's layout engine (Grid, Vertical, Horizontal) will dynamically adjust the arrangement of panels based on terminal size.
• On very small terminals, some panels might collapse or require toggling visibility (e.g., show map OR crew list, not both).
• The ship map grid itself might reduce the number of characters per cell or simplify its representation.

Navigation Changes:

• Keyboard navigation remains consistent.
• Commands might be abbreviated or context-dependent on smaller screens.

Content Priority:

• Core gameplay elements (map, resources, log) are prioritized.
• Less critical panels (detailed crew view) might be secondary or modal.

Interaction Changes:

• Key bindings should be logical and consistent.
• Complex interactions might be simplified or broken into steps for smaller screens.

9. Animation & Micro-interactions (Conceptual)

9.1. Motion Principles

1. Subtle Feedback: Use simple text effects for feedback.
2. Functional Timing: Animations should be quick and not impede gameplay.
3. Consistent Style: All effects should fit the ASCII/TUI aesthetic.

9.2. Key Animations/Effects

1. Power Generation Click

   • Description: Visual feedback when generating power.
   • Effect: Briefly highlight the Power value or the Power Core on the map.

2. Room Unlocking

   • Description: Feedback when unlocking a new room.
   • Effect: Change the room's display from [###] to [ ] with a brief highlight.

3. Crew Awakening

   • Description: Sequence when awakening a crew member.
   • Effect: Add the crew member to the roster with a brief highlight or a simple "Awakened!" message.

4. Resource Gain

   • Description: Feedback when resources are gained.
   • Effect: Briefly highlight the resource value.

5. Room Card Shelf Appearance

   • Description: Display when the room card selection appears.
   • Effect: Simply render the selection area with a clear prompt.

Note: These are conceptual effects achievable with text manipulation and color/style changes in Textual.

10. Performance Considerations

10.1. Performance Goals

Based on the TUI nature, performance targets are:

• Startup Time: Under 2 seconds on average hardware.
• Interaction Response: UI interactions should respond instantly.
• Refresh Rate: Aim for a smooth 30-60 FPS for any animations or frequent updates.

10.2. Design Strategies

1. Efficient Redraws: Textual is designed to be efficient, but minimizing unnecessary redraws is good practice.
2. Simple Elements: Using basic text and simple widgets will naturally be performant.
3. Asynchronous Operations: Offload any long-running game logic from the UI thread to keep the TUI responsive.
4. Smart Updates: Only update UI elements when their underlying data changes.

These strategies align well with the nature of a TUI and the capabilities of the Textual library.

11. Next Steps

11.1. Immediate Actions

1. Review this specification with the development team (or solo developer) to ensure alignment.
2. Begin creating simple ASCII mockups or prototypes for key views using Textual.
3. Plan the implementation approach for the main TUI application structure.
4. Define keybindings and command structure.
5. Set up a feedback loop with potential players interested in ASCII/TUI games.

11.2. Design Handoff Checklist

Let's make sure we've covered all the necessary elements:

1. ☐ All user flows documented
2. ☐ Component concepts defined
3. ☐ Accessibility requirements considered
4. ☐ Responsiveness strategy outlined
5. ☐ Performance goals established
6. ☐ Next steps defined

With these next steps, we're well-positioned to move from specification to implementation using Python and the Textual library, creating a unique ASCII/TUI experience.

12. Checklist Results

A formal UI/UX checklist has been created and can be found at ui-ux-checklist.md. This checklist should be used to review the implementation against the specification to ensure all critical elements have been addressed.

13. Change Log

• 2025-08-24:
  • Completely refactored the document to specify an ASCII/TUI interface using Python and the Textual library, replacing all previous Godot-based UI concepts.
  • Rewrote all sections to reflect the new technical direction and aesthetic.
  • Removed all references to visual assets like fonts, images, and complex color palettes.
  • Added conceptual sections for TUI-specific design considerations like animations and responsiveness.