cal/strat-gameplay-webapp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
64aa800672
strat-gameplay-webapp/.claude/implementation/04-spectator-polish.md
Cal Corum 5c75b935f0 CLAUDE: Initial project setup - documentation and infrastructure 
Add comprehensive project documentation and Docker infrastructure for
Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball
simulation platform replacing the legacy Google Sheets system.

Documentation Added:
- Complete PRD (Product Requirements Document)
- Project README with dual development workflows
- Implementation guide with 5-phase roadmap
- Architecture docs (backend, frontend, database, WebSocket)
- CLAUDE.md context files for each major directory

Infrastructure Added:
- Root docker-compose.yml for full stack orchestration
- Dockerfiles for backend and both frontends (multi-stage builds)
- .dockerignore files for optimal build context
- .env.example with all required configuration
- Updated .gitignore for Python, Node, Nuxt, and Docker

Project Structure:
- backend/ - FastAPI + Socket.io game engine (Python 3.11+)
- frontend-sba/ - SBA League Nuxt 3 frontend
- frontend-pd/ - PD League Nuxt 3 frontend
- .claude/implementation/ - Detailed implementation guides

Supports two development workflows:
1. Local dev (recommended): Services run natively with hot-reload
2. Full Docker: One-command stack orchestration for testing/demos

Next: Phase 1 implementation (backend/frontend foundations)
2025-10-21 16:21:13 -05:00

6.5 KiB
Raw Blame History

Phase 4: Spectator Mode & Polish

Duration: Weeks 10-11 Status: Not Started Prerequisites: Phase 3 Complete

Overview

Implement spectator mode for real-time game viewing, add UI/UX polish including animations, optimize mobile touch experience, and improve accessibility. Focus on production-ready user experience.

Key Objectives

By end of Phase 4, you should have:

  • ✅ Spectator mode fully functional
  • ✅ Dice roll animations working
  • ✅ Smooth transitions and loading states
  • ✅ Mobile touch optimization
  • ✅ Accessibility improvements (WCAG 2.1 AA)
  • ✅ Error handling and recovery UX
  • ✅ Performance optimizations
  • ✅ Production-ready polish

Major Components to Implement

1. Spectator Mode

Backend:

  • Spectator WebSocket events (read-only)
  • Spectator room management
  • Spectator count tracking
  • Permission enforcement

Frontend:

  • Spectator-specific game view
  • Read-only interface (no decision prompts)
  • Spectator count display
  • Join spectator link generation
  • Late join to active games

2. Animations & Transitions

Dice Roll Animation:

  • 3D dice roll effect or 2D animation
  • Suspenseful timing (1-2 seconds)
  • Synchronized across all clients
  • Sound effects (optional)

Play Outcome Transitions:

  • Runner movement animations
  • Score change animations
  • Smooth state transitions
  • Visual feedback for key moments

UI Transitions:

  • Page transitions
  • Modal animations
  • Accordion collapse/expand
  • Loading skeletons

3. Mobile Touch Optimization

Touch Interactions:

  • Swipe gestures (navigate play history)
  • Pull to refresh
  • Tap feedback (haptic if supported)
  • Touch target sizing (44x44px minimum)

Layout Refinements:

  • Safe area handling (iOS notch)
  • Keyboard avoidance
  • Scroll behavior optimization
  • Bottom sheet interactions

Performance:

  • Lazy loading images
  • Virtual scrolling for long lists
  • Debounced scroll handlers
  • Optimized re-renders

4. Accessibility Improvements

Screen Reader Support:

  • Semantic HTML elements
  • ARIA labels on interactive elements
  • Announcements for game events
  • Focus management in modals

Keyboard Navigation:

  • Tab order optimization
  • Keyboard shortcuts for actions
  • Focus indicators
  • Escape key handling

Visual Accessibility:

  • Color contrast validation (4.5:1 minimum)
  • Focus indicators
  • Text sizing options
  • Reduced motion support

Accessible Notifications:

  • Screen reader announcements for plays
  • Visual + auditory feedback options
  • Status updates in accessible format

5. Error Handling & Recovery

Connection Issues:

  • Graceful offline mode
  • Reconnection feedback
  • Action queue during disconnect
  • State sync on reconnect

Error States:

  • Friendly error messages
  • Recovery actions provided
  • Error boundaries (prevent crashes)
  • Fallback UI

Loading States:

  • Loading skeletons
  • Progress indicators
  • Timeout handling
  • Cancel operations

6. Performance Optimizations

Frontend:

  • Code splitting by route
  • Component lazy loading
  • Image optimization (WebP, lazy load)
  • Bundle size reduction
  • Memoization of expensive computations

Backend:

  • Response caching
  • Database query optimization
  • Connection pool tuning
  • Memory usage monitoring

WebSocket:

  • Message compression
  • Batch updates where possible
  • Efficient state diff broadcasts

Implementation Order

  1. Week 10: Spectator Mode + Animations

    • Spectator WebSocket events
    • Read-only game view
    • Dice roll animation
    • Play outcome transitions

  2. Week 11: Polish + Accessibility + Performance

    • Mobile touch optimization
    • Accessibility audit and fixes
    • Error handling improvements
    • Performance profiling and optimization

Testing Strategy

Spectator Mode Testing

  • Join as spectator during active game
  • Verify read-only constraints
  • Test late join (mid-game)
  • Multi-spectator scenarios

Animation Testing

  • Verify timing synchronization
  • Test on various devices/browsers
  • Performance impact measurement
  • Reduced motion preference

Accessibility Testing

  • Screen reader testing (NVDA, JAWS, VoiceOver)
  • Keyboard-only navigation
  • Color contrast validation tools
  • Automated accessibility audits (axe, Lighthouse)

Performance Testing

  • Lighthouse audits
  • Mobile device testing (real devices)
  • Network throttling tests (3G simulation)
  • Memory leak detection

Key Files to Create/Modify

Backend:

  • backend/app/websocket/handlers.py - Add spectator events
  • backend/app/api/routes/spectate.py - Spectator endpoints

Frontend:

  • shared-components/src/components/Display/DiceRoll.vue - Animation
  • shared-components/src/components/Common/LoadingStates.vue
  • frontend-{league}/pages/spectate/[id].vue - Spectator view
  • frontend-{league}/composables/useAccessibility.ts
  • frontend-{league}/utils/animations.ts

Styles:

  • frontend-{league}/assets/css/animations.css
  • frontend-{league}/assets/css/accessibility.css

Reference Documents

Deliverable

A production-ready game interface with:

  • Spectator mode allowing real-time viewing
  • Polished animations and transitions
  • Optimized mobile touch experience
  • WCAG 2.1 AA accessibility compliance
  • Robust error handling and recovery
  • Performance meeting target metrics

Performance Targets

  • Page load: < 3s on 3G
  • Action response: < 500ms
  • Lighthouse score: > 90
  • Accessibility score: 100
  • First contentful paint: < 1.5s
  • Time to interactive: < 3.5s

Accessibility Checklist

  • All interactive elements keyboard accessible
  • Focus indicators visible and clear
  • Color contrast meets WCAG AA standards
  • Screen reader announcements for game events
  • Alternative text for all images
  • Form labels and error messages
  • Skip navigation links
  • Semantic HTML structure
  • Reduced motion preference respected
  • ARIA attributes used correctly

Notes

  • Test spectator mode with multiple simultaneous spectators
  • Animation should enhance, not distract from gameplay
  • Mobile touch targets must be large enough for thumbs
  • Accessibility is not optional - it's a requirement
  • Performance directly impacts user retention

Status: Placeholder - to be expanded during implementation Next Phase: 05-testing-launch.md