Micro-tips: seven one-time cards that explain a feature the first time it matters

[maximsan]

Decided on Micro-tips: triggers, copy, and persistence on 5 September 2026, under the guide-layer map #336. Independent of the tour rebuild #341: the only coupling is that no tip shows while the tour runs.

What a micro-tip is

A small card at the bottom of the screen that explains one feature the first time it matters, once ever, dismissable with an X. Seven exist (prototype/guide.jsx:91-98), copy verbatim:

Id	Eyebrow · title	Body
path	YOUR PATH · The whole course, in order	Each finished lesson unlocks the next, top to bottom. The diamonds branching off the line are hands-on Coffee Challenges.
brew	COFFEE CHALLENGE · A real brew, not a quiz	Make it at your own pace within 48 hours, then log the result here on Today. Logging it earns the challenge's stamp.
tree	COFFEE TREE · Your tree just grew	Completing that lesson pushed it toward harvest. Only core lessons grow it — see it any time from your Profile.
saved	SAVED · Kept for later	Everything you save waits behind the ribbon at the top of Today — lessons, terms and guides on one shelf.
dictionary	DICTIONARY · Every term you've met	Terms join your Dictionary as lessons introduce them. Search them here, or drill them with flashcards.
freeze	STREAK FREEZE · A safety net you've earned	Every 7 streak days in a row earns a freeze; you hold one at a time. Miss a day and it's spent for you — your streak survives.
studio	STUDIO · Make it yours	Dress Roasty and choose your tree's variety and light. The look you set here applies everywhere in the app.

When each one fires (prototype/app.jsx:1196-1214)

Never inside a lesson, never while the tour or a gate sheet is up. One candidate at a time, in this priority:

1. saved: after the first save, on whatever screen it happened, once no sheet is open (a save made mid-lesson waits for the lesson to end).
2. dictionary: the Dictionary is open.
3. studio: the Studio is open and unlocked.
4. path: the Path tab is showing.
5. On the Learn tab with no sheet open: brew if a challenge is active; else tree if a lesson was completed since the last look; else freeze if a freeze is held or the freeze-earned beat has shown.

Pacing (prototype/guide.jsx:101-131)

• A tip counts as seen the moment it shows; the X only hides it.
• After a dismissal the same screen waits 12 s before another tip.
• Moving to another screen retires a visible tip and waits 1.6 s before the next (6 s if one was showing), so two never read as a chain.
• The tour finishing counts as "something was just shown": the 12 s wait applies.

The card (prototype/guide.jsx:134-154)

Bottom of the screen, 16 from each side, 112 above the bottom when the tab bar shows and 40 otherwise, above everything but the tour. Surface background, color-mix(in oklab, accent 30%, rule) border, radius 14, padding 14 by 16, a soft drop shadow. Eyebrow in small caps in accent-text ink, title at the support size weight 500 in ink, body at the label size, line height 1.5, in muted ink. The X on the right, labelled "Dismiss" for assistive tech, the card announced as a status. It fades up; under reduced motion it appears without the fade.

Persistence, ruled on #342

The seen list follows tourSeen, not the design's progress scope: it lives on the device-local settings row beside tourSeen, survives Reset progress, and goes with Delete account (which already drops that row). One rule for both "already introduced" bits.

Acceptance criteria

• Each of the seven tips shows once ever, on the trigger in the table, with its copy verbatim, and never inside a lesson, under the tour, or over a gate sheet — copy pinned in micro_tip_test.dart, triggers in micro_tip_candidate_test.dart, and the three silences driven through the whole app in micro_tip_host_test.dart
• On the Learn tab an active challenge, a fresh completion and a held freeze produce one tip at a time, in that order, with the 12 s wait between them — the order in micro_tip_candidate_test.dart, the wait in micro_tip_host_test.dart
• The seen list survives Reset progress and is gone after Delete account, proved the way tourSeen is — asserted beside it in account_wipe_test.dart
• dart format, flutter analyze, the metrics gate and the suite pass, with a changelog bullet — green on PR Micro-tips: seven one-time cards that explain a feature the first time it matters #530; the simulator smoke, which gates main rather than a PR, was run locally on a wiped device

Built in PR #530, at schema v12.

Two things the ticket left implicit, settled in the build:

• The freeze tip's second arm is a session flag of its own. A freeze earned and then spent on a missed day leaves nothing held, and the learner was still shown a safety net nobody explained.
• A tip already seen is passed over, not treated as the answer. The design's chain stops at the first candidate, which would have left the Learn tab silent for as long as a challenge lasted — and the second criterion above asks for the opposite.