# UI Audit Report - Mana Loop Game UI

**Date:** 2025-01-26  
**Auditor:** Senior Next.js Developer / UI/UX Reviewer  
**Scope:** All game UI components in `src/components/game/` and tabs in `src/components/game/tabs/`

---

## 1. Visual Inconsistencies

### 1.1 Color Usage Inconsistencies

| Issue | Location | Details |
|-------|----------|---------|
| Inconsistent background opacity | Multiple files | `bg-gray-900/80` used in most cards, but some use `bg-gray-800/50` or `bg-gray-800/30` inconsistently |
| Border color variations | Multiple components | `border-gray-700` (most common), but also `border-gray-600`, `border-gray-800` in different contexts |
| Progress bar background inconsistency | `CraftingProgress.tsx:58,89,142`, `ManaDisplay.tsx:57`, `SpireTab.tsx:96` | Most use `bg-gray-800`, but `ActionButtons.tsx:33` uses `bg-gray-700` |
| Text color inconsistency for descriptions | `SpellsTab.tsx:126`, `EquipmentTab.tsx:104` | `text-gray-400` vs `text-gray-500` used inconsistently for similar content |

**Specific Examples:**
- `SpellsTab.tsx:72` - Card uses `bg-gray-900/80 border-gray-700` but `opacity-75` for unlearned spells
- `SkillsTab.tsx:227` - Category cards use `bg-gray-900/80 border-gray-700`
- `LabTab.tsx:101` - Element grid items use `bg-gray-800/50` while cards use `bg-gray-900/80`

### 1.2 Typography Inconsistencies

| Issue | Location | Details |
|-------|----------|---------|
| Card title sizing | Multiple files | `text-xs` used for `CardTitle` in most tabs, but some use `text-sm` or `text-lg` |
| Font weight inconsistency | `ActionButtons.tsx:127` vs others | Uses `font-semibold` while some places use `font-bold` |
| Game panel title class usage | Multiple | `game-panel-title` class applied inconsistently - some titles have it, others don't |

**Specific Examples:**
- `SpireTab.tsx:71` - Uses `text-xs` for CardTitle
- `LabTab.tsx:18,47,86,124` - All use `text-xs` for CardTitle
- `StatsTab.tsx` - Uses `text-xs` consistently for section titles
- `ManaDisplay.tsx:47` - Uses `text-sm` for "Max Mana" label (inconsistent)

### 1.3 Spacing/Padding Inconsistencies

| Issue | Location | Details |
|-------|----------|---------|
| Card padding variations | `EquipmentTab.tsx:228` vs `SpireTab.tsx:73` | `p-3` used in most, but some use `pt-4`, `pt-3`, `py-3` inconsistently |
| Gap spacing | Various grid layouts | `gap-3` (12px) vs `gap-2` (8px) vs `gap-4` (16px) used without clear pattern |
| Separator margins | Multiple | `my-3`, `my-2`, `mt-2 pt-2` used inconsistently |

### 1.4 Component Sizing Inconsistencies

| Issue | Location | Details |
|-------|----------|---------|
| Button sizing | Multiple | `size="sm"` used consistently, but some custom buttons use `h-6`, `h-7`, `h-8` |
| Progress bar heights | Multiple | `h-1.5`, `h-2`, `h-3` used without clear hierarchy |
| Badge sizing | Multiple | Some use `text-xs`, others default size |

**Specific Examples:**
- `CraftingProgress.tsx:58,89,142` - Uses `h-2` for progress bars
- `SpireTab.tsx:96` - Uses `h-3` for floor HP bar (visually prominent)
- `SkillsTab.tsx:199` - Uses `h-2` for study progress

---

## 2. UX Friction Points

### 2.1 Missing Tooltips on Interactive Elements

| Issue | Location | Impact |
|-------|----------|--------|
| No tooltip on enchantment badges | `EquipmentTab.tsx:217-230` | Users don't know what enchantments do without clicking |
| Limited tooltip usage on action buttons | `CraftingTab.tsx` | Buttons like "Start Design" lack explanatory tooltips |
| No tooltip on golem cards | `GolemancyTab.tsx:100-180` | Golem stats could benefit from tooltips explaining mechanics |

### 2.2 Inconsistent Button Placement and Actions

| Issue | Location | Details |
|-------|----------|---------|
| Delete button placement varies | `EquipmentTab.tsx:362-375` vs `LootInventory.tsx:283-290` | Equipment uses 🗑️ icon, Loot uses Trash2 icon with tooltip |
| Cancel button styling inconsistency | `CraftingProgress.tsx:49,80,114,132` | Some use `variant="ghost"`, others `variant="outline"` |
| Study cancel button | `StudyProgress.tsx:30-36` | Uses `variant="ghost"` with `h-6 w-6 p-0` |

### 2.3 Navigation and Flow Issues

| Issue | Location | Details |
|-------|----------|---------|
| Crafting tab stage navigation | `CraftingTab.tsx:13-30` | Tabs remember state but user can be confused about which equipment is selected where |
| No breadcrumb or progress indicator | `EnchantmentDesigner.tsx` | Multi-step process (Select Type → Select Effects → Name → Create) lacks visual progress |
| Equipment selection confusion | `EnchantmentPreparer.tsx:26-65` | Border-left indicators (red for enchanted, green for ready) not immediately obvious |

### 2.4 Interactive Element Feedback

| Issue | Location | Details |
|-------|----------|---------|
| Hover states missing on some clickable cards | `LootInventory.tsx:265,314,384` | Some cards have `group` class but hover effects not consistently applied |
| Selected state not always clear | `LabTab.tsx:30` | Uses `border-blue-500 bg-blue-900/20` but could be more prominent |
| No visual feedback on click | Multiple | Buttons and interactive elements don't have active/pressed states defined |

---

## 3. Missing Feedback / Empty States

### 3.1 Empty States Present (Good)

| Component | Location | Status |
|-----------|----------|--------|
| LootInventory materials | `LootInventory.tsx:157` | ✅ "No items collected yet..." |
| LootInventory blueprints | `LootInventory.tsx:303` (implicit) | ✅ Filter shows no results |
| Equipment inventory | `EquipmentTab.tsx:270-272` | ✅ "No unequipped items..." |
| Spell list | `SpellsTab.tsx:88-91` | ✅ "No spells known yet..." |
| Achievements | `AchievementsTab.tsx` (via AchievementsDisplay) | ✅ Handled in display component |
| Skill categories | `SkillsTab.tsx:224` | ✅ `if (skillsInCat.length === 0) return null` |
| Design list | `EnchantmentDesigner.tsx:241-243` | ✅ "No saved designs yet" |
| Golemancy unlocked | `GolemancyTab.tsx:99-102` | ✅ Locked golem cards shown |

### 3.2 Empty States Missing or Inadequate

| Component | Location | Issue |
|-----------|----------|-------|
| Pact Spells section | `SpellsTab.tsx:95-100` | Section renders but no content if `signedPacts.length > 0` but no pact spells exist |
| Active Golems | `GolemancyTab.tsx:67-79` | No empty state if `hasGolemancy && summonedGolems.length === 0` |
| Equipment Stats Summary | `EquipmentTab.tsx:337-358` | Shows "No active effects" but could be more helpful |
| Attunement Capabilities | `AttunementsTab.tsx:180-200` | Capabilities just show as badges, no explanation for new players |

### 3.3 Missing Loading States

| Component | Issue |
|-----------|-------|
| All tabs | No loading skeleton or spinner when tab content is loading |
| Study/Design/Preparation progress | Progress bars exist, but no initial loading state |
| Equipment instance loading | No feedback when equipment operations are in progress |

### 3.4 Missing Success/Error Feedback

| Issue | Location |
|-------|----------|
| No toast notifications | Throughout - actions like equip, unequip, delete, craft have no success/error toasts |
| No validation messages | `EnchantmentDesigner.tsx` - "Over Capacity!" is shown but not as a toast |
| Silent failures | `store.equipItem()` etc. - no user feedback if operation fails |

---

## 4. Suggested Improvements

### HIGH Priority

| ID | Improvement | Components Affected | Rationale |
|----|--------------|---------------------|-----------|
| H1 | **Add toast notification system** | All tabs | Critical for user feedback on actions (equip, craft, study, etc.). Users need confirmation of success/failure |
| H2 | **Standardize card styling** | All tab components | Define a standard game card class with consistent `bg-gray-900/80 border-gray-700 p-4` styling |
| H3 | **Add loading states/skeletons** | All tabs | Prevents UI jumps and provides feedback during async operations |
| H4 | **Standardize empty states** | SpellsTab, GolemancyTab, StatsTab | Consistent messaging and helpful guidance on what to do next |
| H5 | **Add confirmation dialogs for destructive actions** | EquipmentTab (delete), LootInventory (delete), Crafting (cancel) | Prevent accidental deletion of items, cancelation of progress |

### MEDIUM Priority

| ID | Improvement | Components Affected | Rationale |
|----|--------------|---------------------|-----------|
| M1 | **Standardize progress bar styling** | CraftingProgress, SpireTab, SkillsTab, StudyProgress | Define standard `h-2 bg-gray-800` for all progress bars with semantic colors for different types |
| M2 | **Improve tooltip coverage** | EquipmentTab, GolemancyTab, LabTab, SpellsTab | Add tooltips to enchantment badges, golem stats, element info for better discoverability |
| M3 | **Add visual progress indicator for multi-step processes** | EnchantmentDesigner, CraftingTab | Show which step the user is on (1. Select Type → 2. Select Effects → 3. Name → 4. Create) |
| M4 | **Standardize button variants and sizing** | All tabs | Define when to use `ghost`, `outline`, `default` variants and standard sizes |
| M5 | **Improve selected/hover states** | LabTab, EquipmentTab, LootInventory | More prominent visual feedback using `ring`, `shadow`, or border color changes |
| M6 | **Add capacity warnings** | EquipmentTab, EnchantmentDesigner | Warn when approaching capacity limit (yellow at 80%, red at 100%) |

### LOW Priority

| ID | Improvement | Components Affected | Rationale |
|----|--------------|---------------------|-----------|
| L1 | **Typography standardization** | All components | Define standard text sizes: `text-xs` for metadata, `text-sm` for body, `text-base` for titles |
| L2 | **Add subtle animations** | All interactive elements | Use `transition-all` and `hover:scale-105` for buttons, cards for polish |
| L3 | **Color code by mana type consistently** | SpellsTab, LabTab, ManaDisplay | Ensure element colors are used consistently for all mana-type UI |
| L4 | **Add keyboard navigation support** | CraftingTab, EquipmentTab, SkillsTab | Allow tab/arrow key navigation through selectable items |
| L5 | **Improve responsive grid layouts** | All tabs | Some grids use fixed column counts that may not work well on all screen sizes |
| L6 | **Add "New Player" tooltips/hints** | AttunementsTab, SkillsTab, SpellsTab | First-time user guidance with dismissible hints |
| L7 | **Standardize icon usage** | All tabs | Ensure same Lucide icons are used for same concepts (e.g., Trash2 vs 🗑️) |
| L8 | **Add sort/filter persistence** | LootInventory, EquipmentTab | Remember user's sort/filter preferences across sessions |

---

## Summary Statistics

- **Total Components Reviewed:** 28 files
  - Tab components: 12 (`SpireTab`, `SkillsTab`, `SpellsTab`, `LabTab`, `StatsTab`, `EquipmentTab`, `AttunementsTab`, `DebugTab`, `LootTab`, `AchievementsTab`, `GolemancyTab`, `CraftingTab`)
  - Shared components: 3 (`MemorySlotPicker`, `StudyProgress`, `UpgradeDialog`)
  - Crafting sub-components: 4 (`EnchantmentDesigner`, `EnchantmentPreparer`, `EnchantmentApplier`, `EquipmentCrafter`)
  - Stats sub-components: 5 (`CombatStatsSection`, `ManaStatsSection`, `ManaTypeBreakdown`, `StudyStatsSection`, `UpgradeEffectsSection`)
  - Other components: 4 (`ActionButtons`, `CraftingProgress`, `LootInventory`, `ManaDisplay`, `AchievementsDisplay`, `CalendarDisplay`, `GameContext`)

- **High Priority Issues:** 5
- **Medium Priority Issues:** 6
- **Low Priority Issues:** 8
- **Total Findings:** 19 + visual/spacing inconsistencies

---

## Files Requiring Updates (Priority Order)

1. **H1**: Create toast notification system - `src/components/game/` (new component or use existing toast library)
2. **H2**: Create standard card styling - Update all tab components to use consistent classes
3. **H3**: Add loading skeletons - All tab components
4. **H4**: Improve empty states - `SpellsTab.tsx`, `GolemancyTab.tsx`
5. **H5**: Add confirmation dialogs - `EquipmentTab.tsx`, `LootInventory.tsx`
6. **M1**: Standardize progress bars - Update `className` in multiple files
7. **M2**: Improve tooltips - `EquipmentTab.tsx`, `GolemancyTab.tsx`
8. **M3**: Add step indicators - `EnchantmentDesigner.tsx`
9. **M4**: Button standardization - All components with buttons

---

## Notes

- Debug components (`DebugTab.tsx` and `debug/` folder) were reviewed but given lower priority as they are developer tools
- `GameContext.tsx` is a provider/context component, not a UI component, so it was not included in UI audit
- The `game-panel-title` CSS class appears to be a custom class - review its definition to ensure it's being applied consistently
- Consider creating a `game-ui` CSS module or Tailwind component classes for commonly repeated patterns