Skip to content

POLISH.md

Latest commit

 

History

History
429 lines (350 loc) · 19.2 KB

POLISH.md

File metadata and controls

429 lines (350 loc) · 19.2 KB

DEFCON RED - UI/UX Polish Backlog

Quick Stats

  • Total Items: 45
  • High Priority: 12 items
  • Medium Priority: 22 items
  • Low Priority: 11 items

By Complexity:

  • Simple: 22 items
  • Medium: 19 items
  • Complex: 4 items

Quick Wins (High Impact + Simple)

These 6 items provide the biggest user experience improvements with minimal development effort:

  1. [HUD-1] Add DEFCON Status Display - Show current DEFCON level prominently on HUD
  2. [HUD-2] Uncomment Launch Origin Confidence - Display attribution confidence data
  3. [FEEDBACK-1] Order Submission Confirmation - Add toast notifications for player actions
  4. [FEEDBACK-2] Intercept Success/Failure Visualization - Dramatic visual feedback for intercept outcomes
  5. [TRANSITION-3] Game Phase Transitions - Visual overlays for phase changes
  6. [TUTORIAL-1] Tutorial/Onboarding - First-time guidance on controls and objectives

Critical Simulation Accuracy (High Priority)

These 2 items are essential for realistic gameplay and should be prioritized:

  1. [HUD-7] Missile Progress Based on Start Time - Missile should start partway along trajectory when game begins mid-scenario
  2. [HUD-8] Launch Origin Uncertainty Visualization - Show realistic intelligence uncertainty with region/circle instead of precise point

1. Missing HUD Elements

HUD-1: DEFCON Status Display ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Simple
  • Description: Current DEFCON level is only shown in ActionPanel status indicators at the bottom of the screen. Not prominently displayed in main HUD.
  • Suggested Fix: Add DEFCON status to Globe3D overlay alongside timer and tracking status. Should be highly visible with color coding (red for DEFCON 1, amber for 2-3, etc.)
  • File: src/client/components/Globe3D.tsx (lines 326-343)

HUD-2: Launch Origin Confidence Display ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Simple
  • Description: Launch origin data is commented out in Globe3D (lines 354-365). Players have no visibility into attribution confidence.
  • Suggested Fix: Uncomment and style the launch origin overlay. This is critical intelligence that affects decision-making.
  • File: src/client/components/Globe3D.tsx (lines 354-365)

HUD-3: US Nuclear Launch Status

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: No clear HUD element showing if US has launched retaliatory strikes and their targets.
  • Suggested Fix: Add a status indicator showing active US launches with target count and ETA.
  • File: src/client/components/Globe3D.tsx

HUD-4: Intercept Launch Count

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: No indicator showing how many intercepts have been launched or are in flight.
  • Suggested Fix: Add counter overlay showing "Intercepts: X/Y" (active/total).
  • File: src/client/components/Globe3D.tsx

HUD-5: Foreign Nuclear Alert Levels

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: Russia/China nuclear alert status exists in game state but not displayed to player.
  • Suggested Fix: Add small indicators showing foreign posture: Russia alert level, China alert level, hair-trigger risk levels.
  • File: src/client/App.tsx or new HUD component

HUD-6: Advisor Stress/Loyalty Indicators

  • Impact: LOW
  • Complexity: Medium
  • Description: Advisors have stress and loyalty metrics that affect behavior, but players can't see this.
  • Suggested Fix: Add subtle indicators in ParticipantsModal showing advisor state (icons or color coding).
  • File: src/client/components/ParticipantsModal.tsx

HUD-7: Missile Progress Based on Start Time ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Medium
  • Description: Missile progress doesn't account for when the game starts. If starting with 10 minutes remaining (halfway through a 20-minute scenario), the missile should already be halfway to target, not at launch origin.
  • Suggested Fix: Calculate initial missile position based on (initialTimeSeconds - currentTimeSeconds) / initialTimeSeconds and interpolate along trajectory arc. Missile should start at appropriate position on its flight path.
  • File: src/client/components/Globe3D.tsx (missile position calculation)

HUD-8: Launch Origin Uncertainty Visualization ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Medium
  • Description: Initial missile trajectory is too precise. Launch point should show uncertainty covering a huge area (parts of China, North Korea, Russia, and surrounding ocean). Trajectory line points to exact location when it should show uncertainty.
  • Suggested Fix:
    1. Replace precise launch point with uncertainty circle/region on globe
    2. Trajectory line should stop well above the uncertain origin area (not point to specific spot)
    3. Circle size should decrease as attribution confidence increases over time
    4. Visual should convey "missile came from somewhere in this region" not "exact launch coordinates"
  • File: src/client/components/Globe3D.tsx (threat track visualization)

2. Visual Feedback Gaps

FEEDBACK-1: Order Submission Confirmation ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Medium
  • Description: When player sends chat messages or uses DebugPanel, no clear loading state or success confirmation.
  • Suggested Fix: Add toast notifications or inline feedback for all player actions ("Order received", "Launching intercept...", etc.)
  • File: src/client/App.tsx, src/client/components/DebugPanel.tsx

FEEDBACK-2: Intercept Success/Failure Visualization ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Complex
  • Description: Intercept status changes (success/failure) happen with color change only. No dramatic visual feedback.
  • Suggested Fix: Add particle effects, flash, or explosion animation when intercept succeeds/fails.
  • File: src/client/components/Globe3D.tsx

FEEDBACK-3: Nuclear Launch Visual Feedback

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: US nuclear launches appear as green arcs but no dramatic "launch initiated" moment.
  • Suggested Fix: Add launch animation, screen flash, or dramatic overlay when nuclear order is executed.
  • File: src/client/components/Globe3D.tsx

FEEDBACK-4: Message Delivery Status

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: Chat messages disappear into feed with no acknowledgment that AI received them.
  • Suggested Fix: Add "typing" indicators when advisors are responding, or "delivered/read" receipts.
  • File: src/client/components/ChatFeed.tsx

FEEDBACK-5: Disabled Action Explanation

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: ActionPanel buttons disable but don't explain WHY they're disabled.
  • Suggested Fix: Add tooltips or hover states explaining why actions are unavailable ("Already at DEFCON 1", "No active threats to intercept").
  • File: src/client/components/ActionPanel.tsx

FEEDBACK-6: Hotline Connection Feedback

  • Impact: LOW
  • Complexity: Simple
  • Description: Opening hotline has no "connecting" animation or feedback.
  • Suggested Fix: Add "Establishing secure connection..." animation when hotline is opened.
  • File: src/client/components/HotlinePanel.tsx

FEEDBACK-7: Time Progression Indicator

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: Timer counts down but there's no visual sense of urgency as time runs out.
  • Suggested Fix: Add pulsing, color changes, or screen edge warnings as impact approaches (e.g., last 60 seconds).
  • File: src/client/components/Globe3D.tsx

3. Accessibility Issues

ACCESS-1: Keyboard Shortcut Discoverability

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: Backtick (`) for debug and ESC for closing panels are undocumented in UI.
  • Suggested Fix: Add keyboard shortcuts legend/help panel (accessible via "?" key) or show hints on first load.
  • File: src/client/App.tsx

ACCESS-2: Low Contrast Text

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: Many status texts use slate-400/500 on dark backgrounds, failing WCAG contrast ratios.
  • Suggested Fix: Audit and increase contrast ratios for all text elements to meet WCAG AA standards.
  • File: Multiple (Global CSS and all components)

ACCESS-3: Missing ARIA Labels

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: Interactive elements lack aria-labels (buttons, modals, inputs).
  • Suggested Fix: Add comprehensive aria-labels, aria-describedby, and role attributes for screen readers.
  • File: All component files

ACCESS-4: Focus Management in Modals

  • Impact: LOW
  • Complexity: Medium
  • Description: When modals open (DebugPanel, HotlinePanel, ParticipantsModal), focus doesn't trap.
  • Suggested Fix: Implement focus trap and focus management (first element on open, return focus on close).
  • File: src/client/components/DebugPanel.tsx, src/client/components/HotlinePanel.tsx, src/client/components/ParticipantsModal.tsx

ACCESS-5: Globe 3D Interaction for Non-Mouse Users

  • Impact: LOW
  • Complexity: Complex
  • Description: Globe requires mouse/touch for rotation. No keyboard controls.
  • Suggested Fix: Add keyboard controls for rotating globe (arrow keys) or provide alternative 2D view toggle.
  • File: src/client/components/Globe3D.tsx

ACCESS-6: Color-Only Information

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: Trajectory colors (red=threat, green=US, cyan=intercept) rely solely on color differentiation.
  • Suggested Fix: Add patterns, labels, or shapes to differentiate trajectory types for colorblind users.
  • File: src/client/components/Globe3D.tsx

4. Responsive Design Issues

RESPONSIVE-1: Mobile Globe Visibility

  • Impact: HIGH
  • Complexity: Medium
  • Description: Globe viewport is small on mobile (flex-1 md:w-3/5). Critical information may be hard to see.
  • Suggested Fix: Optimize Globe overlays for mobile - larger text, repositioned elements, or collapse some info into expandable panel.
  • File: src/client/components/Globe3D.tsx, src/client/App.tsx

RESPONSIVE-2: ActionPanel Button Grid Overflow

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: ActionPanel uses grid-cols-2 md:grid-cols-3. On very small screens, buttons may be cramped.
  • Suggested Fix: Test on actual mobile devices and adjust grid layout or use vertical stack on smallest screens.
  • File: src/client/components/ActionPanel.tsx

RESPONSIVE-3: Chat Feed Message Width

  • Impact: LOW
  • Complexity: Simple
  • Description: Messages max-w-[85%] on mobile may still be too wide for very small screens.
  • Suggested Fix: Adjust max-width breakpoints for ultra-small screens (max-w-[95%] sm:max-w-[85%]).
  • File: src/client/components/ChatFeed.tsx

RESPONSIVE-4: Modal Fullscreen on Mobile

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: Modals use max-w-2xl/4xl but may be too large on tablets.
  • Suggested Fix: Make modals full-screen or nearly full-screen on mobile with proper padding.
  • File: src/client/components/HotlinePanel.tsx, src/client/components/DebugPanel.tsx

RESPONSIVE-5: Timer Font Size Scaling

  • Impact: LOW
  • Complexity: Simple
  • Description: Timer uses text-2xl md:text-3xl. May be too small on large displays or too big on tiny screens.
  • Suggested Fix: Add more breakpoints (text-xl sm:text-2xl md:text-3xl lg:text-4xl).
  • File: src/client/components/Globe3D.tsx

5. Loading/Transition States

TRANSITION-1: Initial Game Load

  • Impact: LOW
  • Complexity: Simple
  • Description: "INITIALIZING SIMULATION..." screen is good but could be more informative.
  • Suggested Fix: Add progress steps ("Establishing secure connection...", "Loading scenario...", "Briefing advisors...").
  • File: src/client/App.tsx (lines 146-155)

TRANSITION-2: Chat Message Streaming

  • Impact: MEDIUM
  • Complexity: Complex
  • Description: Messages appear instantly. No sense of AI "thinking" or typing.
  • Suggested Fix: Add typing indicators or stream messages character-by-character for realism.
  • File: src/client/components/ChatFeed.tsx

TRANSITION-3: Game Phase Transitions ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Medium
  • Description: Transition from preImpact to postImpact to ended has no visual cue besides game state change.
  • Suggested Fix: Add dramatic transition animations/overlays ("IMPACT DETECTED", "POST-IMPACT PHASE").
  • File: src/client/App.tsx

TRANSITION-4: Outcome Screen Entrance

  • Impact: MEDIUM
  • Complexity: Simple
  • Description: GameOutcome appears with just animate-fade-in. Could be more dramatic for such a critical moment.
  • Suggested Fix: Add dramatic entrance animation with sound effect trigger point, or countdown before revealing outcome.
  • File: src/client/components/GameOutcome.tsx

TRANSITION-5: Hotline Message Send State

  • Impact: LOW
  • Complexity: Simple
  • Description: "Sending..." text appears but no visual progress indicator.
  • Suggested Fix: Add spinner or progress bar during message send.
  • File: src/client/components/HotlinePanel.tsx (line 201)

TRANSITION-6: Network Error Recovery

  • Impact: MEDIUM
  • Complexity: Medium
  • Description: Polling errors are logged but user gets no feedback if connection is lost.
  • Suggested Fix: Add connection status indicator and reconnection attempts notification.
  • File: src/client/App.tsx (lines 24-36)

6. Consistency Issues

CONSISTENCY-1: Inconsistent Button Patterns

  • Impact: LOW
  • Complexity: Simple
  • Description: Some buttons are px-3 py-2, others px-4 py-3, others px-6 py-2. No consistent sizing pattern.
  • Suggested Fix: Establish button size classes (sm, md, lg) and apply consistently across all components.
  • File: Multiple components

CONSISTENCY-2: Modal Close Patterns

  • Impact: LOW
  • Complexity: Simple
  • Description: Some modals use "Close" button, others "Close (ESC)", some just X icon.
  • Suggested Fix: Standardize modal header pattern with consistent close button placement and labeling.
  • File: src/client/components/DebugPanel.tsx, src/client/components/HotlinePanel.tsx, src/client/components/ParticipantsModal.tsx

CONSISTENCY-3: Border Color Variations

  • Impact: LOW
  • Complexity: Simple
  • Description: Borders use border-slate-800, border-slate-700, border-gray-700, border-cyan-900/50 inconsistently.
  • Suggested Fix: Define semantic border colors (primary-border, secondary-border, panel-border) in Tailwind config.
  • File: Tailwind config and all components

CONSISTENCY-4: Terminology Inconsistency

  • Impact: LOW
  • Complexity: Simple
  • Description: "Advisor" vs "Participant" vs "Core Team" used interchangeably.
  • Suggested Fix: Standardize on one term throughout UI ("Advisors" recommended).
  • File: src/client/components/ChatInput.tsx, src/client/components/ParticipantsModal.tsx

CONSISTENCY-5: Status Text Case

  • Impact: LOW
  • Complexity: Simple
  • Description: Some status text is UPPERCASE, some is Title Case, some is lowercase.
  • Suggested Fix: Establish case convention (UPPERCASE for critical alerts, Title Case for labels, sentence case for body).
  • File: Multiple components

CONSISTENCY-6: Color Scheme for Countries

  • Impact: LOW
  • Complexity: Simple
  • Description: Country colors defined in HotlinePanel and ChatFeed separately. Could drift out of sync.
  • Suggested Fix: Extract country color constants to shared config file.
  • File: src/client/components/HotlinePanel.tsx, src/client/components/ChatFeed.tsx

7. Additional Polish Items

POLISH-1: Error Toast Auto-Dismiss

  • Impact: LOW
  • Complexity: Simple
  • Description: Error toast requires manual dismissal. No auto-timeout.
  • Suggested Fix: Add 5-second auto-dismiss with optional manual close.
  • File: src/client/App.tsx (lines 209-216)

POLISH-2: Empty State Messages

  • Impact: LOW
  • Complexity: Simple
  • Description: When hotlines list is empty, shown in HotlinePanel but no similar treatment elsewhere.
  • Suggested Fix: Add empty states for chat feed when game starts, advisor list when filtered, etc.
  • File: Multiple components

POLISH-3: Missile Position Interpolation

  • Impact: LOW
  • Complexity: Medium
  • Description: Missile position updates every tick, may appear jumpy.
  • Suggested Fix: Add smooth interpolation between positions for fluid movement.
  • File: src/client/components/Globe3D.tsx

POLISH-4: Audio Cues

  • Impact: MEDIUM
  • Complexity: Complex
  • Description: No audio feedback for critical events (launch, intercept, messages).
  • Suggested Fix: Add subtle sound effects for high-stakes moments (optional/mutable).
  • File: New audio system

POLISH-5: Tutorial/Onboarding ⭐ PRIORITY

  • Impact: HIGH
  • Complexity: Complex
  • Description: Players dropped into crisis with no guidance on controls or objectives.
  • Suggested Fix: Add optional first-time tutorial overlay or help screen explaining interface.
  • File: New component

POLISH-6: Changelog/Version Display

  • Impact: LOW
  • Complexity: Simple
  • Description: No version number or changelog visible to players.
  • Suggested Fix: Add small version number in corner and link to changelog.
  • File: src/client/App.tsx

POLISH-7: Screenshot/Share Feature

  • Impact: LOW
  • Complexity: Medium
  • Description: No way to capture and share outcome screen or critical moments.
  • Suggested Fix: Add "Share Result" button on GameOutcome screen.
  • File: src/client/components/GameOutcome.tsx

Implementation Roadmap

Sprint 1: Critical HUD & Simulation Accuracy (3-4 days)

  • HUD-1: DEFCON Status Display
  • HUD-2: Launch Origin Confidence
  • HUD-7: Missile Progress Based on Start Time ⭐ NEW
  • HUD-8: Launch Origin Uncertainty Visualization ⭐ NEW
  • FEEDBACK-1: Order Submission Confirmation
  • FEEDBACK-5: Disabled Action Explanation
  • FEEDBACK-7: Time Progression Indicator

Sprint 2: Visual Polish (3-4 days)

  • FEEDBACK-2: Intercept Success/Failure Visualization
  • FEEDBACK-3: Nuclear Launch Visual Feedback
  • TRANSITION-3: Game Phase Transitions
  • TRANSITION-4: Outcome Screen Entrance

Sprint 3: Accessibility & Responsive (2-3 days)

  • ACCESS-1: Keyboard Shortcut Discoverability
  • ACCESS-2: Low Contrast Text
  • RESPONSIVE-1: Mobile Globe Visibility
  • RESPONSIVE-2: ActionPanel Button Grid
  • RESPONSIVE-4: Modal Fullscreen on Mobile

Sprint 4: Consistency & Additional Polish (2-3 days)

  • All CONSISTENCY items (6 items)
  • HUD-4: Intercept Launch Count
  • TRANSITION-6: Network Error Recovery
  • POLISH-1: Error Toast Auto-Dismiss
  • POLISH-6: Changelog/Version Display

Future Enhancements

  • POLISH-4: Audio Cues
  • POLISH-5: Tutorial/Onboarding
  • ACCESS-5: Globe Keyboard Controls
  • TRANSITION-2: Chat Message Streaming
  • POLISH-7: Screenshot/Share Feature

Notes

  • Items marked with ⭐ PRIORITY are recommended for immediate implementation
  • File paths are relative to project root
  • All items have been validated against current codebase structure
  • Consider creating GitHub issues from this backlog for team tracking