Guide layer parity — the Tour guide.jsx actually designed (wayfinder map)

[maximsan]

Destination

A locked rebuild spec + build tickets for the app's guide layer, matching prototype/guide.jsx: the four-step Today tour (card callouts with "N of 4", Skip, dots, Next/Done; animated dim-and-highlight frame; no intro overlay — ruled 10 Sep on Does the Tour ask before it runs? The app does; the design does not and removed in PR #589; no tab navigation), the event-driven micro-tips (coach cards), and the Settings → Help → App Guide home. Urgent — the shipped tour is off-design; it stays on in the interim with stopgap controls (see Notes).

Notes

• Root cause on record: the prototype's guide layer landed 2026-08-22 00:05 in guide.jsx; the first Tour map (Tour — Learn-tab walking tour (wayfinder map) #191) was charted later that day without searching the prototype for a tour, and specified an invented design (intro overlay, spotlight package, own copy) that Tour: the tourSeen flag and its fate-sharing rules #251–Tour: replay from Profile #253 then faithfully built. Guardrail for this map: every spec statement cites guide.jsx / app.jsx; a prototype change re-opens the citing ticket.
• The design source: prototype/guide.jsx (TOUR_STEPS, TodayTour, micro-tips, App Guide) with state + triggers in prototype/app.jsx, behind the guide tweak.
• What survives from the old build: the tourSeen flag (its write moves to the run's end under Does the Tour ask before it runs? The app does; the design does not), fate-sharing with onboardingCompleted, device-local/no-snapshot rule — design-agnostic mechanics, decided on the old map and still good.
• Interim: the tour was not switched off in the end — Tour: the missing controls — Skip, end on tab change, App Guide in Settings was rewritten 28 Aug by product-owner ruling (pre-launch, one user, nobody to protect) and shipped Skip on every card, end-on-tab-change, and Settings → Help & Support → App Guide with Replay Today introduction, all on the existing tour. Only the frame-and-card look and dropping showcaseview wait for the rebuild.
• Grilling tickets consult the grilling + domain-modeling skills; decisions resolve per docs/agents/issue-tracker.md.
• Checked against the running app, 9 Sep — all four stops driven on a wiped iPhone 16. The copy, the frame's radius, ring and 320ms move, the card's padding, leading and controls, the scroll arithmetic, the seven micro-tips and the seven App Guide sections all match guide.jsx. One deliberate divergence stands and is recorded: the Streak section's first sentence, rewritten under #338's ruling. One defect was found — the card's side, below.
• Re-read against the 10 Sep drop (e914cf40): guide.jsx moved Skip into a pill and off the last step, and moved the frame onto the target's content box — The Tour follows the 10 Sep drop. Stops 1 and 2 each lost a sentence, recorded on The Tour's four stops say something the design does not. The bodies came back into line in PR #589, and the Skip control and the frame's edges in PR #593, so the layer matches guide.jsx again.

Decisions so far

• Can showcaseview draw the guide.jsx callout-and-frame design? — No: the accent ring and cutout radius are mutually exclusive, the 320ms frame move does not exist, and its singleton root-overlay entry cannot die with the screen — build the layer by hand as an in-tree Stack child of the shell and drop the dependency.
• The guide layer's home: App Guide in Settings, replay, and the on/off control — collapsed into the rebuild: the design answers all three parts — App Guide is a nav row under Settings → Help & Support (settings.jsx:590), replay lives on the App Guide screen as Replay Today introduction (guide.jsx:167), and there is no on/off toggle in the design, so none is built.
• Assemble the guide-layer spec and cut the rebuild tickets — nothing left to assemble: the design specifies the layer completely, so the spec and the build are one ticket, the rebuild.
• Micro-tips: triggers, copy, and persistence — all seven ship with the design's copy and triggers; the seen list follows tourSeen (device-local, survives Reset, dies with Delete) rather than the design's progress scope; built by Micro-tips: seven one-time cards in PR #530, at schema v12. The layer draws above the router, because the Studio and Today's term are pushed over the tab bar; its silence under a sheet comes from the barrier every sheet and dialog already wears.
• Does the Tour ask before it runs? The app does; the design does not — it does not: ruled by the product owner 10 Sep, the design does not ask so the app does not either. The offer goes and every ending of the first run — Skip, Done, leaving the tab — writes tourSeen; built in PR #589.
• The Tour's four stops say something the design does not — the design's copy on all four stops, word for word from guide.jsx's TOUR_STEPS as of the 10 Sep drop: Assemble the Tour spec and cut build tickets #195 locked the app's set before anyone knew the design had a tour, and the ticket records the reason stop by stop. Built in the same PR.

Not yet specified

• Whether the old Profile "Replay the tour" row survives, moves, or dies — decided by The guide layer's home and built by Tour: the missing controls: replay lives on the App Guide screen.
• Reduced-motion treatment of the animated highlight frame — settled by the rebuild in PR #538: the move is cut to nothing rather than dropped, because the frame still has to arrive at each stop. What reduced motion removes is the travel, not the arrival.
• Whether the Tour asks before it runs — ruled 10 Sep: it does not. Does the Tour ask before it runs? The app does; the design does not removes the offer.
• Whether the four stops keep the app's own copy or take the design's — the design's, ruled 10 Sep on The Tour's four stops say something the design does not and built in PR #589.
• Whether micro-tip dismissal state shares the tourSeen storage shape — decided by Micro-tips: triggers, copy, and persistence: it does.
• Which side the card takes when the design's side has no room — the other side, ruled by the product owner 9 Sep and built in PR #558. The design's rule sends the card above a target with less than 330 below it; the Today card is tall and starts high, so above it there is only the status bar's strip, and the first stop drew behind the clock. The mock the rule is drawn against has no status bar, so neither the rule nor the suite could see it. Clamping the card on screen was tried first and rejected: it left the card covering the CONTINUE LEARNING heading of the card it introduces.

Still owed

• tourCardTop in lib/features/tour/domain/tour_geometry.dart cites the ruling behind the card's side — done in PR #589.

Out of scope

• App-wide visual drift (colors, screen layouts, tab naming, the off-ruling "Go Premium" card) — owned by the design-parity map created alongside this one.
• The Today screen's own redesigned layout (CONTINUE LEARNING, PRACTICE accordion) — the tour anchors whatever the screen is; making the screen match the design is the drift map's work.