fix: improve web auth refresh and mobile tutorials

2026-05-10 15:22:08 +08:00
parent 3f0942329d
commit 627454971c
8 changed files with 183 additions and 46 deletions
@@ -61,6 +61,13 @@ Login and public marketing/legal pages are not part of the authenticated app she
 - Mobile sidebar must be reachable through the menu button and must not hide the page content permanently.
 - Public header mobile navigation must expose feature, pricing, about, login, and language switching.

+### Mobile Guided Overlays
+
+- Keep one dimming strategy per viewport. Do not combine a full-screen dark overlay with a spotlight element that also uses an oversized outer shadow on the same mobile viewport.
+- Mobile spotlight targets should fit inside the phone viewport. If a desktop tutorial highlights a tall panel, use a smaller mobile-only target such as the rows or controls that the step actually explains.
+- Tooltip placement and arrow direction must match: a tooltip above the target uses a bottom arrow pointing down; a tooltip below the target uses a top arrow pointing up.
+- When the app shell owns scrolling, compute mobile overlay coordinates relative to the page component host and visible scroll container, not the document body.
+
 ## i18n Rules

 - Supported locales: `zh`, `zh_Hant`, `en`.
@@ -0,0 +1 @@
+{"file": ".trellis/spec/web/index.md", "reason": "Verify mobile overlay behavior and web layout constraints."}
@@ -0,0 +1 @@
+{"file": ".trellis/spec/web/index.md", "reason": "Web authenticated app layout, responsive behavior, and mobile guided overlay rules."}
@@ -0,0 +1,53 @@
+# 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
+
+* [x] In mobile viewport, manual step 3 spotlight excludes the coin selector.
+* [x] In mobile viewport, auto step 3 spotlight excludes the coin selector.
+* [x] In mobile viewport, manual step 4 tooltip does not overlap the highlighted submit button and arrow points down.
+* [x] In mobile viewport, auto step 4 tooltip does not overlap the highlighted submit button and arrow points down.
+* [x] 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.
@@ -0,0 +1,26 @@
+{
+  "id": "fix-mobile-divination-tutorial-overlay",
+  "name": "fix-mobile-divination-tutorial-overlay",
+  "title": "Fix mobile divination tutorial overlay",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "zl-q",
+  "assignee": "zl-q",
+  "createdAt": "2026-05-10",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "dev",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
				`@@ -0,0 +1 @@`
				`{"file": ".trellis/spec/web/index.md", "reason": "Verify mobile overlay behavior and web layout constraints."}`