The-Somnus-Project/docs/tui-visual-design.md

TUI Visual Design and Interaction

This document outlines the visual design and interaction patterns for the Somnus TUI application, focusing on the representation of the ship's map and core UI elements.

1. Ship Map Representation

The ship map is the central visual element of the TUI, displayed in the RoomMapView widget. It will be rendered using a grid of ASCII characters and potentially Unicode symbols/emoji for enhanced clarity and immersion.

1.1 Room Representation

• Unlocked & Functional Room: Green Square Emoji (🟩)
• Locked or Hazardous Room: Red Square Emoji (🟥)
• Selected Room: The currently selected room will be highlighted, for example, by inverting the background color or using a different border style.
• Room Detail View: When a room is selected, a RoomCard will be displayed in the RoomCardShelf, providing detailed information and interaction options for that specific room.

1.2 Door Representation

Each room can have up to four doors (North, South, East, West). Doors will be visually represented between adjacent rooms.

• Unlocked Door: A gap or a specific character (e.g., a single space , or a double pipe ║ for vertical, double dash ═ for horizontal) between two room squares.
• Locked Door: A distinct character or symbol (e.g., X, #, or a lock emoji 🔒) placed between two room squares to indicate the door is locked.
• No Door: Rooms without a connection on a specific side will simply be adjacent, with no gap or connecting character.

Example Grid Layout (Conceptual):

🟥 ═ 🟩 ═ 🟩
║    ║    ║
🟩    🟩    🟥
║    ║    ║
🟥 ═ 🟥 ═ 🟩

This example shows a simple grid with red and green rooms, connected by unlocked (═, ║) and locked (?) doors.

2. Core UI Elements

• Header: A Textual Header widget for the top of the screen, potentially displaying the game title or current status.
• Footer: A Textual Footer widget for the bottom of the screen, showing key bindings or status messages.
• Resource Panel: A vertical list or bar displaying current resource levels (e.g., Power: 100). This panel will update reactively as resources change.
• Crew Roster Panel: A scrollable list of awakened crew members, showing their names and perhaps a status icon (e.g., working, idle).

3. Interaction Patterns

• Navigation: The player will navigate the ship map using keyboard keys (e.g., arrow keys, WASD) or potentially mouse clicks if supported and preferred.
• Selection: A room is selected by navigating the cursor over it or clicking on it. This action triggers the display of the RoomCardShelf for that room.
• Actions: Actions related to a room (e.g., assigning a crew member, locking/unlocking a door) are performed through the RoomCard interface that appears when a room is selected.

4. Considerations

• Unicode/Emoji Support: Textual generally supports Unicode, including emoji. However, the actual display depends on the terminal's font. We should test with common terminals to ensure emoji render correctly. If emoji are unreliable, fallback ASCII characters can be used.
• Accessibility: Ensure that the visual design remains usable in terminals with different color capabilities (e.g., monochrome) and that alternative representations (ASCII only) are possible if needed.
• Scalability: The visual design should be adaptable if the ship map grows larger than initially anticipated.