Mana-Loop/docs/task3/ui_audit_report.md

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