echoes-of-the-ash/docs/development/UI_UX_IMPROVEMENTS.md

UI/UX Improvements - Visual Clarity & Consistency

Date: October 20, 2025
Status: ✅ Complete

Overview

Improved visual clarity and consistency across all game interfaces with better alignment, turn indicators, and status bar visibility.

Changes Implemented

1. Aligned Status Bars

Problem: HP and Stamina labels had different lengths, causing misalignment:

❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
          ^ Not aligned

Solution: Added label padding in format_stat_bar():

def format_stat_bar(label: str, emoji: str, current: int, maximum: int, 
                    bar_length: int = 10, label_width: int = 7) -> str:
    padded_label = f"{label}:".ljust(label_width + 1)
    return f"{emoji} {padded_label} {bar} {percentage}% ({current}/{maximum})"

Result:

❤️ HP:      ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
            ^ Perfectly aligned!

2. Clear Combat Turn Indicators

Problem: Combat messages could be confusing - couldn't tell whose turn it was.

Solution: Added visual separators for turns:

Player Attack:

━━━ YOUR TURN ━━━
⚔️ You attack the Feral Dog for 15 damage!
💥 CRITICAL HIT!
🌟 You stunned the Feral Dog!
━━━━━━━━━━━━━━━━━━━━
🐕 Feral Dog: ███░░░░░░░ 30% (15/50)

Enemy Attack:

━━━ ENEMY TURN ━━━
💥 The Feral Dog attacks you for 8 damage!
🩸 You're bleeding!
━━━━━━━━━━━━━━━━━━━━
❤️ Your HP:    ████████░░ 82% (82/100)
🐕 Feral Dog:  ███░░░░░░░ 30% (15/50)

3. HP/Stamina Bars in Inventory

Problem: Couldn't see current HP/Stamina when using items - had to back out to check.

Solution: Added status bars to inventory views:

Inventory Menu:

🎒 Your Inventory:
❤️ HP:      ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
📊 Weight: 15/50 kg
📦 Volume: 30/100 vol

After Using Item:

🎒 Your Inventory:
❤️ HP:      ██████████ 100% (100/100)  ← Updated!
⚡ Stamina: ████████░░ 75% (75/100)     ← Updated!
📊 Weight: 14/50 kg
📦 Volume: 28/100 vol
━━━━━━━━━━━━━━━━━━━━
✨ Used 💊 Bandage
❤️ HP: +30

4. Item Effect Preview

Item details now show what effects they'll have:

💊 Bandage
First aid supplies for treating wounds

Weight: 0.2 kg | Volume: 1 vol
Effects: ❤️ +30 HP

[Use] [Drop] [Back]

5. Consistent Section Separators

Used ━━━━━━━━━━━━━━━━━━━━ (20 chars) consistently to separate:

• Status from description (main menu)
• Status from action results (inventory use)
• Turn actions from combat status (combat)

Files Modified

bot/utils.py

• Updated format_stat_bar() to add label_width parameter
• Labels are now padded for consistent alignment
• Default width: 7 characters (fits "Stamina:")

bot/combat.py

• Added "━━━ YOUR TURN ━━━" header to player attacks
• Added "━━━ ENEMY TURN ━━━" header to NPC attacks
• Added separator line before combat status display
• Improved HP bar display after each turn

bot/inventory_handlers.py

• Added HP/Stamina bars to handle_inventory_menu()
• Added HP/Stamina bars to handle_inventory_use()
• Added separator line between status and usage result
• Refreshed player data after item use to show updated stats

bot/action_handlers.py

• Fixed separator placement in get_player_status_text()
• Now separates equipment/stats from location description

Visual Examples

Before & After: Main Menu

Before:

📍 Location: Downtown Plaza
❤️ HP: 70/100 | ⚡️ Stamina: 50/100
🎒 Load: 15/50 kg | 30/100 vol
⚔️ Equipped: 🔧 Wrench, 🎒 Backpack
━━━━━━━━━━━━━━━━━━━━A desolate plaza...

After:

📍 Location: Downtown Plaza
❤️ HP:      ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
🎒 Load: 15/50 kg | 30/100 vol
⚔️ Equipped: 🔧 Wrench, 🎒 Backpack
━━━━━━━━━━━━━━━━━━━━
A desolate plaza, once bustling with life...

Before & After: Combat

Before:

⚔️ You attack the Feral Dog for 15 damage!
💥 CRITICAL HIT!
🐕 Feral Dog: 15/50 HP

After:

━━━ YOUR TURN ━━━
⚔️ You attack the Feral Dog for 15 damage!
💥 CRITICAL HIT!
━━━━━━━━━━━━━━━━━━━━
🐕 Feral Dog: ███░░░░░░░ 30% (15/50)

Before & After: Inventory Use

Before:

🎒 Your Inventory:
📊 Weight: 14/50 kg
📦 Volume: 28/100 vol

Used 💊 Bandage

❤️ HP: +30

After:

🎒 Your Inventory:
❤️ HP:      ██████████ 100% (100/100)
⚡ Stamina: ████████░░ 75% (75/100)
📊 Weight: 14/50 kg
📦 Volume: 28/100 vol
━━━━━━━━━━━━━━━━━━━━
✨ Used 💊 Bandage
❤️ HP: +30

Benefits

✅ Better Alignment - All status bars line up perfectly
✅ Clear Turn Indication - Always know whose turn it is in combat
✅ Visible Stats - See HP/Stamina without leaving inventory
✅ Consistent Separators - Visual hierarchy is clear
✅ Better Feedback - See immediate effects of item usage
✅ Professional Look - More polished, game-like interface

Testing

All changes tested and verified:

• ✅ Status bars align correctly
• ✅ Combat turn headers display properly
• ✅ Inventory shows current HP/Stamina
• ✅ Item usage updates stats correctly
• ✅ Separators display consistently
• ✅ No errors in any module

Future Enhancements

Possible improvements:

• Color-coded bars (red for low HP, yellow for medium)
• Animated transitions (Telegram doesn't support this natively)
• Sound effects on critical hits (also not supported)
• Status effect icons (🩸 🌟 etc already implemented)

---

Implementation Complete! The game now has a much more polished and professional feel with consistent, clear visual feedback throughout all interfaces.