Pebble Improvement Roadmap

This roadmap turns the Visual Audit into ordered work. It favors the smallest changes that restore hierarchy before adding new decoration.

Phase A — remove the visual failures

1. Verify the deployed games/pebble/build/ identity against the intended source before styling further.
2. Replace the game-over gradient stack with a single card bg-base-100 border border-base-300 shadow-xl result surface.
3. Replace the level-clear overlay with the same surface contract and a clear Continue action.
4. Remove the play-mode navbar shadow-[var(--shadow-2)]; use a border or shadow-sm.
5. Remove GamePill hover lift and default shadow; use a restrained Daisy semantic badge/context state.
6. Establish page base-200, board base-300, and HUD base-100 surfaces.
7. Make the canvas letterbox intentional and remove unexplained blank mobile space.

Phase B — compose the game

1. Build a unified HUD rail containing labeled Score, Level, Balls, Orange left, and Multiplier values.
2. Move readability-critical metrics outside the canvas while retaining canvas feedback for immediacy.
3. Rework FREE BALL as a clearly identifiable moving gameplay target, not a tiny button-like label.
4. Use one feedback lane for Multiball, Free Ball, Lucky Bucket, and Level Clear notifications.
5. Reduce trajectory styling to a subtle prediction line with a clear aim/release distinction.
6. Keep peg semantics aligned with Daisy roles: warning orange, accent/secondary specials, primary launcher, success clear.
7. Redesign mobile around a compact header, two-row HUD, 16:9 board, and deliberate action/status dock.

Phase C — theme and accessibility hardening

1. Resolve the Funday theme once and pass it through the existing ViewportPool/GameViewport/FundayBridge boundary.
2. Ensure the iframe does not paint a bright fallback surface before theme variables are ready.
3. Test fresh browser, stored light, stored dark, system light, system dark, SPA navigation, and iframe reload.
4. Add DOM/live-region equivalents for score, level, remaining orange pegs, multiplier, bonuses, and terminal states.
5. Make overlay actions keyboard reachable with correct focus return.
6. Add reduced-motion behavior for confetti, score popups, bucket flash, launcher recoil, and overlay transitions.
7. Test all supported Daisy themes and ensure special pegs are distinguishable without color alone.

Phase D — platform and performance hardening

1. Keep canvas references and rendering outside Svelte $state() proxies.
2. Preserve stable iframe identity through ViewportPool; do not recreate the iframe for ordinary state changes.
3. Keep shell/iframe communication on the FundayBridge contract; do not add raw postMessage to GameViewport.svelte.
4. Avoid giant blur filters, stacked shadows, and large gradient layers on low-end mobile.
5. Add shell and iframe build identifiers so stale-artifact drift is diagnosable.

Priority matrix

Definition of done

• No giant generic shell shadow in play mode.
• No gradient-heavy game-over or level-clear screen.
• No unexplained blank mobile letterbox.
• All gameplay metrics have labels and hierarchy.
• Shell and iframe use one resolved semantic theme.
• Public route screenshots prove desktop, mobile, gameplay feedback, game-over, and level-clear states.