# 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