polish-improvements

# Space Strategy Game - Comprehensive Polish Improvements

**Generated**: 2026-02-09 **Status**: Audit Complete - Ready for Implementation
**Overall Polish Score**: ~55% complete

---

## Executive Summary

8 specialized agents audited every major game slice. The game has **excellent
foundational architecture** with Framer Motion, audio system hooks, and particle
systems - but these systems are **underutilized**. The primary gap is
**integration** - connecting existing polish systems to game components.

### Critical Finding: Audio Files Missing

The audio system is fully configured with 50+ sound definitions in
`/apps/web/src/lib/audio/config.ts`, but **no actual audio files exist** in
`/public/audio/`. This is the #1 blocker for audio polish.

---

## Priority Matrix

| Priority | Category               | Est. Effort | Impact                   |
| -------- | ---------------------- | ----------- | ------------------------ |
| **P0**   | Audio Files Creation   | 4-8 hrs     | Enables all audio polish |
| **P1**   | Combat Audio/Particles | 3-4 hrs     | Core gameplay feel       |
| **P1**   | Core UI States         | 4-6 hrs     | Fundamental UX           |
| **P2**   | Fleet Management Audio | 2-3 hrs     | Selection feedback       |
| **P2**   | Turn Phase Transitions | 3-4 hrs     | Game flow clarity        |
| **P2**   | Economy Animations     | 2-3 hrs     | Resource feedback        |
| **P3**   | Galaxy Map Polish      | 5-7 hrs     | Strategic visuals        |
| **P3**   | Tech Tree Integration  | 3-4 hrs     | Progression feel         |
| **P3**   | Diplomacy UI           | 5-7 hrs     | Feature completeness     |

---

## P0: Critical Blockers

### 1. Create Audio Asset Directory Structure

**Files to create**: `/apps/web/public/audio/`

```
public/audio/
├── ui/
│   ├── button-click.wav
│   ├── button-hover.wav
│   ├── form-success.wav
│   ├── form-error.wav
│   ├── modal-open.wav
│   ├── modal-close.wav
│   ├── notification-alert.wav
│   ├── achievement.wav
│   └── menu-select.wav
├── combat/
│   ├── laser-fire.wav
│   ├── missile-launch.wav
│   ├── shield-hit.wav
│   ├── hull-impact.wav
│   ├── explosion-small.wav
│   ├── explosion-medium.wav
│   ├── explosion-large.wav
│   └── critical-hit.wav
├── fleet/
│   ├── ship-select.wav
│   ├── fleet-confirm.wav
│   ├── warp-jump.wav
│   └── engine-thrust.wav
├── technology/
│   ├── research-complete.wav
│   ├── tech-unlock.wav
│   └── discovery.wav
├── victory/
│   ├── victory-fanfare.wav
│   ├── achievement-unlock.wav
│   ├── turn-advance.wav
│   └── defeat.wav
└── ambient/
    ├── deep-space.wav
    └── combat-zone.wav
```

**Options**:

- Use AI-generated sounds (ElevenLabs SFX, Stable Audio)
- License from freesound.org (many CC0 options)
- Use placeholder sounds initially

---

## P1: Core Polish (High Impact)

### 2. Combat UI Audio & Particles Integration

**Files**: `/apps/web/src/components/game/CombatUI.tsx`

```typescript
// Add imports
import { useCombatSounds } from '@/lib/hooks/useAudio';
import { useParticles } from '@/components/game/ParticleSystem';

// In component
const { laserFire, shieldHit, explosionMedium, criticalHit } =
  useCombatSounds();
const { spawn } = useParticles();

// On weapon fire
const handleWeaponFire = (weapon: Weapon) => {
  if (weapon.type === 'laser') laserFire();
  if (weapon.type === 'missile') missileLaunch();
  spawn('energy-burst', { position: weapon.position });
};

// On damage received
const handleDamage = (damage: number, isCritical: boolean) => {
  if (isCritical) {
    criticalHit();
    spawn('explosion-large', { color: '#fbbf24' });
  } else {
    shieldHit();
    spawn('shield-impact', { color: '#3b82f6' });
  }
};
```

**Also add screen shake**:

```typescript
import { ErrorShake } from '@/components/ui/ErrorShake';
// Wrap combat panel, trigger on damage
```

### 3. Combat Preview Panel Audio

**File**: `/apps/web/src/components/game/CombatPreviewPanel.tsx`

```typescript
import { useUISounds } from '@/lib/hooks/useAudio';

const { success, error } = useUISounds();

// Play based on recommendation
useEffect(() => {
  if (recommendation === 'engage') success();
  if (recommendation === 'avoid') error();
}, [recommendation]);
```

### 4. Core UI Component States

**Files to fix**:

| Component          | Issue                      | Fix                               |
| ------------------ | -------------------------- | --------------------------------- |
| `Dialog.tsx`       | No enter/exit animations   | Add framer-motion AnimatePresence |
| `Textarea.tsx`     | No hover/focus states      | Mirror Input.tsx styling          |
| `Input.tsx`        | Placeholder contrast 3.8:1 | Change to `placeholder-gray-400`  |
| `Select.tsx`       | No hover border            | Add `hover:border-primary-400`    |
| `Slider.tsx`       | No keyboard support        | Add arrow key handlers            |
| `DropdownMenu.tsx` | Instant open/close         | Add slide animation               |
| `Accordion.tsx`    | Instant expand             | Add height animation              |

**Animation timing standardization** - Replace all `duration-200` with
constants:

```typescript
import { ANIMATION_DURATIONS } from '@/constants/animations';
// Use ANIMATION_DURATIONS.fast (150ms) consistently
```

---

## P2: Enhanced Polish

### 5. Fleet Management Audio

**File**: `/apps/web/src/components/game/FleetPanel.tsx`

```typescript
import { useFleetSounds, useUISounds } from '@/lib/hooks/useAudio';

const { shipSelect, fleetConfirm, warpJump } = useFleetSounds();
const { click } = useUISounds();

// On fleet selection
const handleSelectFleet = (fleet: Fleet) => {
  shipSelect();
  setSelectedFleet(fleet);
};

// On movement order
const handleMoveOrder = (destination: System) => {
  fleetConfirm();
  // If warp jump
  if (isWarpDistance(destination)) warpJump();
};

// On formation change
const handleFormationChange = (formation: Formation) => {
  click();
  setFormation(formation);
};
```

**Add hover effects to ship cards** (lines 596-614):

```tsx
<motion.div
  whileHover={{ scale: 1.02, backgroundColor: 'rgba(30, 41, 59, 1)' }}
  whileTap={{ scale: 0.98 }}
  transition={{ duration: 0.15 }}
>
```

### 6. Turn Phase Transitions

**File**: `/apps/web/src/components/game/TurnControls.tsx`

Add phase transition overlay:

```typescript
// New component: PhaseTransitionOverlay.tsx
export const PhaseTransitionOverlay = ({ phase, prevPhase }) => (
  <AnimatePresence>
    {phase !== prevPhase && (
      <motion.div
        className="fixed inset-0 bg-black/80 flex items-center justify-center z-50"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
      >
        <motion.h1
          className="text-6xl font-bold text-primary-500"
          initial={{ scale: 0.5, y: 50 }}
          animate={{ scale: 1, y: 0 }}
        >
          {phase.toUpperCase()} PHASE
        </motion.h1>
      </motion.div>
    )}
  </AnimatePresence>
);
```

Add multiplayer waiting states:

```typescript
// PlayerStatusGrid showing ready/waiting indicators
<div className="grid grid-cols-4 gap-2">
  {players.map(player => (
    <div className={cn(
      "p-2 rounded-lg border",
      player.isReady ? "border-green-500 bg-green-500/10" : "border-yellow-500 animate-pulse"
    )}>
      <span>{player.name}</span>
      {player.isReady ? <Check /> : <Clock className="animate-spin" />}
    </div>
  ))}
</div>
```

### 7. Economy Resource Animations

**File**: `/apps/web/src/components/game/ResourcePanel.tsx`

Add animated number counters:

```typescript
import { useSpring, animated } from '@react-spring/web';

const AnimatedNumber = ({ value }) => {
  const { number } = useSpring({
    number: value,
    from: { number: 0 },
    config: { tension: 300, friction: 20 }
  });

  return <animated.span>{number.to(n => n.toFixed(0))}</animated.span>;
};
```

Add change indicators:

```typescript
// Show +/- delta with color flash
const ResourceDelta = ({ change }) => (
  <motion.span
    initial={{ opacity: 0, y: change > 0 ? 10 : -10 }}
    animate={{ opacity: 1, y: 0 }}
    exit={{ opacity: 0 }}
    className={change > 0 ? 'text-green-400' : 'text-red-400'}
  >
    {change > 0 ? '+' : ''}{change}
  </motion.span>
);
```

---

## P3: Feature Polish

### 8. Galaxy Map Improvements

**File**: `/apps/web/src/features/game/components/GalaxyMapEnhanced.tsx`

**Smooth zoom/pan**:

```typescript
// Add easing to viewport transforms
const animatedViewport = useSpring({
  x: viewport.x,
  y: viewport.y,
  scale: viewport.scale,
  config: { tension: 200, friction: 25 },
});
```

**Fleet movement interpolation**:

```typescript
// Smooth fleet position updates between turns
const fleetPosition = useSpring({
  x: fleet.position.x,
  y: fleet.position.y,
  config: { duration: 2000 },
});
```

**Territory visualization** (new feature):

```typescript
// Voronoi regions for controlled territory
// Supply line visualization between owned systems
// Contested system pulsing effect
```

**Create Minimap component** (missing):

```typescript
// /apps/web/src/components/game/Minimap.tsx
// Shows overview with viewport indicator
// Click-to-navigate functionality
```

### 9. Tech Tree Audio Integration

**File**: `/apps/web/src/components/game/TechTree.tsx`

```typescript
import { useMilestoneCelebration } from './MilestoneCelebration';
import { useAudio } from '@/lib/hooks/useAudio';

const { celebrateTechBreakthrough } = useMilestoneCelebration();
const { playTechnologySound } = useAudio();

// On tech completion
const handleTechComplete = (tech: Technology) => {
  playTechnologySound('tech-unlock');
  if (tech.tier >= 4) {
    celebrateTechBreakthrough(tech.name);
  }
  // Spawn particles at node position
  spawn('energy-burst', { position: techNode.position, color: '#10b981' });
};
```

**Fix broken Tailwind dynamic classes** (lines 211, 237, 253):

```typescript
// Replace template literals with clsx conditionals
className={clsx(
  'base-class',
  isActive && 'active-class',
  isDisabled && 'disabled-class'
)}
```

### 10. Diplomacy UI Enhancements

**File**: `/apps/web/src/features/diplomacy/AllianceMap.tsx`

**Add audio feedback**:

```typescript
// Add to GameEventAudio.ts
onAllianceFormed: () => playSound('treaty-signed'),
onWarDeclared: () => playSound('war-declared'),
onTrustChange: (delta) => delta > 0 ? playSound('success') : playSound('warning'),
```

**Create faction theme system**:

```typescript
// /apps/web/src/lib/constants/factionThemes.ts
export const FACTION_THEMES = {
  terran: { primary: '#3b82f6', emblem: TerranEmblem, pattern: 'grid' },
  imperial: { primary: '#a855f7', emblem: ImperialEmblem, pattern: 'diagonal' },
  // ... more factions
};
```

**Add treaty negotiation modal** (new component):

```typescript
// /apps/web/src/features/diplomacy/TreatyNegotiationModal.tsx
// Multi-step wizard: Select type → Define terms → Review → Send
```

---

## Quick Wins (<1 hour each)

1. **Add audio to fleet selection** - Import hook, call on selection
2. **Add hover scale to ship cards** - `whileHover={{ scale: 1.02 }}`
3. **Add pulsing to selection overlay** - Animate boxShadow
4. **Fix Input placeholder contrast** - Change `gray-500` to `gray-400`
5. **Add Dialog animations** - Copy Modal's AnimatePresence pattern
6. **Add ripple to action buttons** - `whileTap` with inset shadow
7. **Achievement celebrations** - Already done ✅
8. **Button audio** - Already done ✅

---

## Architecture Strengths (Keep These)

- **Framer Motion** - Excellent animation primitives throughout
- **Audio System** - Well-architected with categories, spatial audio, hooks
- **Particle System** - Comprehensive effects library ready to use
- **Animation Constants** - Centralized timing in `/constants/animations.ts`
- **Component Patterns** - Button is gold standard for polish (ripple, audio,
  states)

---

## Metrics After Full Implementation

| Metric                  | Current | Target |
| ----------------------- | ------- | ------ |
| Audio Integration       | 20%     | 90%    |
| Particle Effects        | 40%     | 85%    |
| Loading States          | 70%     | 95%    |
| Animation Consistency   | 60%     | 95%    |
| Accessibility (WCAG AA) | 70%     | 100%   |
| Overall Polish          | 55%     | 90%    |

---

## Implementation Approach

### Wave 1: Foundation (Week 1)

- Create audio file directory structure
- Generate/license placeholder sounds
- Fix core UI component states
- Standardize animation timings

### Wave 2: Core Gameplay (Week 2)

- Combat audio + particles
- Fleet management audio
- Turn phase transitions
- Economy animations

### Wave 3: Feature Polish (Week 3)

- Galaxy map improvements
- Tech tree integration
- Diplomacy UI enhancements
- Multiplayer waiting states

### Wave 4: Accessibility (Week 4)

- ARIA labels across all components
- Keyboard navigation
- Color contrast fixes
- Reduced motion alternatives

---

_Generated by J.A.R.V.I.S. Multi-Agent Audit System_