Mana-Loop/docs/task4/orient.md

Task 4 - Sub-task 1: Orientation Findings

Date: 2024-04-27

1. Game Briefing Summary

The Mana Loop is a browser-based incremental/idle game with:

• Theme: Ancient arcane magic, mysterious 100-floor spire, mana weaving, time loops
• Core Loop: 30-day time loop with actions: Gather Mana → Study Skills → Climb Spire → Craft Gear
• Mana Types: 14 types (Fire, Water, Air, Earth, Light, Dark, Death, Transference, Metal, Sand, Lightning, Crystal, Stellar, Void)
• Attunements: 3 classes (Enchanter, Invoker, Fabricator)
• Key Systems: Skills (T1-T5 with milestone upgrades), Equipment & Enchantment, Golemancy, Prestige/Loop

2. Lint Results (Pre-existing Errors)

Running npm run lint revealed 5 pre-existing errors:

File	Line	Error
src/app/page.tsx	294:22	'ScrollArea' is not defined (react/jsx-no-undef)
src/components/game/tabs/AttunementsTab.tsx	198:69	Comments inside children section should be in braces
src/components/game/tabs/AttunementsTab.tsx	249:56	Comments inside children section should be in braces
src/components/game/tabs/StatsTab.tsx	188:22	'Badge' is not defined (react/jsx-no-undef)
src/hooks/use-mobile.ts	14:5	Calling setState synchronously within an effect

Note: These are pre-existing and should NOT be fixed as part of this task.

3. Component Mapping (src/components/game/)

Tab Components (in src/components/game/tabs/):

Component	File	Purpose
CraftingTab	tabs/CraftingTab.tsx	Crafting interface
SpireTab	tabs/SpireTab.tsx	Spire climbing UI
SpellsTab	tabs/SpellsTab.tsx	Spell management
LabTab	tabs/LabTab.tsx	Laboratory/research
SkillsTab	tabs/SkillsTab.tsx	Skills study interface
StatsTab	tabs/StatsTab.tsx	Statistics display
AttunementsTab	tabs/AttunementsTab.tsx	Attunement selection/management

Game UI Components (in src/components/game/):

Component	File	Purpose
ActionButtons	ActionButtons.tsx	Main action buttons (Gather, Study, etc.)
CalendarDisplay	CalendarDisplay.tsx	Time/calendar display
CraftingProgress	CraftingProgress.tsx	Crafting progress bar
ManaDisplay	ManaDisplay.tsx	Mana resource display
StudyProgress	StudyProgress.tsx	Study progress indicator
TimeDisplay	TimeDisplay.tsx	Time display
UpgradeDialog	UpgradeDialog.tsx	Upgrade selection dialog
AchievementsDisplay	AchievementsDisplay.tsx	Achievements list
GameContext	GameContext.tsx	Game state context
LootInventory	LootInventory.tsx	Loot/inventory display

Debug Components (in src/components/game/debug/):

Component	File	Purpose
GameStateDebug	GameStateDebug.tsx	Main debug panel
AttunementDebug	AttunementDebug.tsx	Attunement debugging
ElementDebug	ElementDebug.tsx	Element debugging
GolemDebug	GolemDebug.tsx	Golem debugging
PactDebug	PactDebug.tsx	Pact debugging
SkillDebug	SkillDebug.tsx	Skill debugging

4. Current Design Token Set (src/app/globals.css)

Existing CSS Custom Properties:

Background Colors:

• --background: #060811 (dark navy/black)
• --card: #0C1020 (slightly lighter dark)
• --popover: #111628 (medium dark)
• --muted: #181f35 (lighter panel bg)
• --secondary: #1e2a45 (border/secondary color)

Text Colors:

• --foreground: #c8d8f8 (light blue-white)
• --muted-foreground: #7a92c0 (muted blue-gray)

Border Colors:

• --border: #1e2a45
• --input: #1e2a45

Interactive Colors:

• --primary: #3B6FE8 (blue)
• --primary-foreground: #ffffff
• --accent: #2a3a60 (darker accent)
• --accent-foreground: #c8d8f8
• --destructive: #C0392B (red)

Game-Specific Colors (already defined):

• --game-bg: #060811
• --game-bg1: #0C1020
• --game-bg2: #111628
• --game-bg3: #181f35
• --game-border: #1e2a45
• --game-border2: #2a3a60
• --game-text: #c8d8f8
• --game-text2: #7a92c0
• --game-text3: #4a5f8a
• --game-gold: #D4A843
• --game-gold2: #A87830
• --game-purple: #7C5CBF
• --game-purpleL: #A07EE0
• --game-accent: #3B6FE8
• --game-accentL: #5B8FFF
• --game-danger: #C0392B
• --game-success: #27AE60

Fonts:

• Heading: 'Cinzel', serif (fantasy-adjacent)
• Body: 'Crimson Text', Georgia, serif
• Mono: 'JetBrains Mono', monospace

Border Radius:

• --radius: 0.625rem

Existing UI Components (src/components/ui/):

• alert-dialog.tsx
• badge.tsx
• button.tsx
• card.tsx
• dialog.tsx
• input.tsx
• label.tsx
• progress.tsx
• scroll-area.tsx
• select.tsx
• separator.tsx
• sheet.tsx
• skeleton.tsx
• switch.tsx
• tabs.tsx
• toast.tsx
• toaster.tsx
• toggle.tsx
• tooltip.tsx

5. AGENTS.md Status

✅ docs/AGENTS.md EXISTS (size: 17486 bytes, modified: 2024-04-26)

6. Component Name Labels Investigation

Found references to showComponentNames in:

• src/components/game/debug/GameStateDebug.tsx (lines 23, 76, 81, 82)

The toggle exists in the debug UI, but need to find where component names are actually rendered in the UI. This will be searched and removed in Step 3.

7. Key Observations

1. Visual Identity: Current design uses dark theme with blue/purple/gold accents - aligns with "arcane grimoire" aesthetic but needs more polished mana type colors
2. Typography: Already has good fantasy font stack (Cinzel for headings, Crimson Text for body)
3. Need to implement: All 9 primitive components listed in Step 2e
4. CSS Variables: Currently uses Tailwind + some custom properties; need to add all required semantic tokens
5. No framer-motion: Project doesn't appear to use framer-motion (good, as per requirements)

Next Steps

1. Create docs/task4/design_system.md with all design decisions
2. Update src/app/globals.css with all required CSS custom properties
3. Implement 9 primitive components in src/components/ui/
4. Remove component name labels
5. Create all sub-task documentation files
6. Run final lint verification