eryao/.trellis/tasks/archive/2026-05/05-10-fix-mobile-divination-tutorial-overlay/prd.md

Fix mobile divination tutorial overlay

Goal

Fix the mobile web tutorial overlay on manual and auto divination pages so spotlight targets, tooltip placement, arrow direction, and overlay shadow match the intended mobile UX.

What I already know

• User reports mobile tutorial has an overly large dark/shadowed area.
• Step 3 should highlight the six yao area, not only the coin area. If the full coin + yao area is too large, highlight only the six yao rows and exclude the coins.
• Step 4 tooltip arrow should point down toward the spotlighted "start divination" button.
• Step 4 tooltip currently overlaps the spotlight region.
• Affected files are web/src/components/ManualDivinationPage.tsx and web/src/components/AutoDivinationPage.tsx.

Assumptions

• Keep desktop behavior visually equivalent unless the existing code already uses a different desktop target.
• Mobile behavior is the priority for this task.
• No backend or protocol changes are needed.

Requirements

• Mobile step 3 highlights the six yao rows/panel area and excludes the coin selector.
• Mobile step 4 places the tooltip above the submit/start button with enough gap to avoid overlap.
• Mobile step 4 arrow points downward toward the spotlighted button.
• Remove the excessive/double-shadow appearance caused by overlapping dimming strategies.
• Apply the same behavior to manual and auto divination tutorial overlays.

Acceptance Criteria

• In mobile viewport, manual step 3 spotlight excludes the coin selector.
• In mobile viewport, auto step 3 spotlight excludes the coin selector.
• In mobile viewport, manual step 4 tooltip does not overlap the highlighted submit button and arrow points down.
• In mobile viewport, auto step 4 tooltip does not overlap the highlighted submit button and arrow points down.
• Overlay dimming is visually consistent without large unintended dark blocks.

Definition of Done

• Local browser verification at a phone-sized viewport.
• git diff --check passes.
• Build/typecheck status documented if blocked by existing project configuration.

Out of Scope

• Redesigning the tutorial copy.
• Changing tutorial persistence/profile settings behavior.
• Backend auth/session changes.

Technical Notes

• Web spec applies: .trellis/spec/web/index.md.
• Existing mobile threshold uses window.innerWidth < 1280.
• App shell scroll container is the main vertical scrolling region.