Embers: design scaffolding handoff

Status: scaffolding, not final. Prototypes settle concept, visual language and core flows. Exact rule values, copy, data wiring and edge states happen at integration. Source: Claude Design project "Mario Kart ember badges", HANDOFF.md, imported 2026-08-17. Transcribed here because the share link is only openable by someone with access and cannot be searched, diffed, or survive a dead link. Issue: #579Not scheduled. Operator: not to work on yet.

The system in one paragraph

Embers are die-cut stickers (cream border, flat multicolor, chunky type) that guests earn by lighting lanterns. They live in the Hearth, a warm-paper collection screen inside the dark PWA. Venue embers anchor to their place; anywhere embers travel with the user. A venue's house ember is granted automatically at first light and carries reusable promos; custom embers are granted by rules ("when X, then grant"). Promos redeem in a timed window (show to staff plus countdown, one redemption per person).

Screens prototyped

File	Surface	State
Embers Sticker Sheet	Sticker language, 16 embers plus locked slots	direction locked
Hearth	User collection: hero, search and sort, Anywhere row, venue shelves, viewer sheet	flagship, most refined
Ember Earned	Earn moment: bottom sheet over venue page, promo accept/decline plus opt-out	approved layout
Hearth Entry Compare	Nav decision, option 2 (Hearth tab) chosen	decision record
Ember Ping	Promo notification: lock-screen push plus in-app toast	baseline approved
Ember Portal	Merchant: new ember / promo rule builder, auto die-cut preview	good baseline
Ember Manage	Merchant: embers index, house ember card plus custom rows	good baseline

Decisions made

• Nav: Hearth replaces Info in the bottom nav (Info folds into Me/Settings). Icon lucide Sparkles, active amber with fill-amber-500/20, label "Hearth". Amber dot on the inactive tab when a promo waits (not yet mocked).
• Hearth canvas: warm paper #efe9db, a deliberate divergence and the one light room in the dark app. Nav stays dark. Stickers cast real drop shadows; locked slots are recessed dashed sockets.
• Live vs static: a redeeming ember gets drop shadow, slow sway, foil sweep, green pulse, countdown. Viewing is fully static with a "VIEWING ONLY" pill. No glows on paper, drop shadow only.
• Promo model: the promo rides an ember. House ember is the venue logo sticker, earned once, and promos re-fire on it with no new art per promo. Custom embers may carry a promo at creation. Markers: armed-hub dot on the sticker corner; promo line above the CTA; the ticket carries only show-to-staff plus countdown plus one-redemption.
• Rules are conditional: WHEN (count hit / event window / late night) plus optional AND holds an ember, THEN grant sticker or fire promo. Promo targeting: holders-on-next-light, ping-all-now, or new-earners-only.
• Die-cut is automatic: transparent PNG traces alpha, solid image becomes a rounded sticker. No shape picker. 400x400 or larger suggested.
• User consent: the earn sheet offers accept promo, just collect, or "always just collect", a global opt-out changeable in Me and Embers.
• Naming: "anywhere embers" (standards and wander rejected), "gathered" not "earned" in user copy, Hearth is the collection.

Open items, deferred to integration

1. Milestone rule values. Dwell minimum, one-per-day cap, collision handling when two embers share a trigger, retroactivity (lean: grant on next light so the moment stays at the venue), repeatability, custom N, multi-venue house embers. The owner wants these set during integration.
2. Venue-page crumb. "Your embers here, 5/6" on venue pages. Agreed, not mocked.
3. Staff-side verification. A countdown alone is screenshot-spoofable. Needs a live timer, a rotating code, or a merchant redemption feed.
4. Ping guardrails. One ping per promo, per-venue frequency cap, quiet hours, opt-out respected. Surface a reach estimate near Submit.
5. Anywhere-ember incentive. Proposal: cosmetic lantern flair. Unexplored.
6. Review pipeline. Embers and promos share the offers moderation queue. The portal states it; the admin queue UI is untouched.

Implementation notes from the handoff

• Bottom nav is DashboardNavigation; hub states already match. Earn and viewer sheets use the standard bottom-sheet recipe.
• Merchant surfaces use the MerchantShell sidebar plus the OfferForm section/phone-preview pattern. Embers becomes a sibling of Offers.
• Me page is the ProfileSettings takeover. A Hearth card mock exists as a secondary entry.
• Ticket gradient is the beveled high-stakes CTA. Sort pills are DashboardButton ghost/selected. Toast follows the WaveManager pattern.
• Sticker art is inline SVG in the prototypes; production wants versioned assets with the programmatic white die-cut and shadow.

Fidelity caveats from the handoff

Mock data throughout. The redemption window and one-per-person must be enforced server-side, not client. Muted body text on paper should darken to #6b6355 for 4.5:1. The ember viewer needs drag-to-dismiss and a focus trap.

Where this meets our existing rules

Not objections. These are the points where the handoff and the repo's standing constraints touch, worth settling at integration rather than discovering.

• Server enforcement goes to Cloud Run, not Cloud Functions. The handoff says Cloud Functions. Non-negotiable rule 9 is API first: new HTTP endpoints belong in a Cloud Run API service, and Cloud Functions are only for event-driven triggers. The redemption window and one-per-person guard are HTTP.
• #efe9db and #6b6355 need to become tokens. The design skill forbids inventing hex values in components. A deliberate divergence is fine; an untokenised literal is what rots.
• Warm paper under dark nav is a contrast surface. The a11y gate now fails on axe color-contrast, and the handoff already flags the muted-text ratio. Every new component needs a colocated story, and stories are smoke-rendered and a11y-gated in CI.
• Fonts must be self-hosted. The handoff says so already, and it matches the privacy stance. Prototypes load from Google Fonts; production cannot.
• Sharing the offers moderation queue is a decision with a live surface. That queue was verified end to end on 2026-08-16, both the approve and reject branches. Anything that adds a new item type into it should not be assumed to inherit that verification.
• Promo targeting is the privacy-sensitive part. Holders-on-next-light and ping-all-now describe a cohort a venue can reach. The privacy-architecture skill governs, and the targeting is where #579's original anonymity framing actually lives.