Design record · shipped (#2576)

← Design HQ HTML on GitHub ↗ PRD · prd-pl-payment-billing-usage ↗

Billing — as approved and built

Wallet, add funds, then the prepaid statement.

SizePortrait scrolls 375 · sideways is a slide deckNotes

Design brief — overview · scope · journey (closed)

Wallet, top-up, statement, and invoicing — one flat Billing surface (Billing and Usage are now separate nav rows, no in-page tab bar).

tabs 4 → 2 nav rowswallet hero de-boxed focalsetup = one flat row groupreceipt sheet stacks above the drill

The widths drawn here are samples of a fluid continuum, not the only states that exist — content (spacing, type, gaps, card/column widths) scales continuously between them, each clamp reading a named container. Structure (rail, row↔stack, grid columns) steps only at sm 640 · md 768 · lg 1024; radius, hairlines, and pills never scale. Kit: design-canon.md U8.

Reading order in this document: § Desktop journey first — every desktop frame, full flow, journey order — then § Mobile journey — 375 below it — every mobile frame, same order, laid out side by side as a wrapping grid (never a tall single-file column of phone screens). Two sections, never interleaved — a review-document convention only (this repo's design-canon.md § Mockup review reading order). Mobile 375px is still designed and scored FIRST in the /design ritual (kit canon U5/U8) — the two rules never conflate.

Part I · Active — build now

Wallet

1 · Billing overview — wallet hero · wallet activity · billing setup

Workspace

Explore

Brain

Pulse

Team

Connects

Support

Wishlist

Feedback

Support

FAQ

Account

Billing

Usage

Billing

Wallet balance

$41.20

Wallet running low — add funds

+ Add funds

Never expires · refundable anytimeSpent this month $18.60 →

Wallet activity

View all →

Added funds Jul 18+$50.00

Refund to card Jul 15−$12.00

Added funds Jul 12+$25.00

Billing setup

Visa ···· 4242 defaultRemove

+ Add a card

Auto-reload offTurn on →

Warn me below$10 ▾

Notify byEmailSlack

Invoicing details→

Alerts and receipts go to your account email.

Overview — BillingPage.tsx

Compact <h1>Billing</h1> on the readable column, not the PageLayout h1/description zone.
No tab bar: renders straight into WalletBalance (hero + wallet activity), then BillingOverview "Billing setup" group.
Setup = ONE flat hairline row group: payment methods, auto-reload, wallet alerts (warn-below + channels), invoicing.
Wallet activity, not a usage log (Peyton 2026-08-22 — CPO split): this on-page list shows wallet money movements ONLY — categories topup / refund / adjustment / chargeback (labels from walletActivityLabel(): Added funds · Refund to card · Adjustment · Chargeback). run / ai / addon debit rows are DROPPED here — those events live in Pulse → Activity (Assistant/Brain scope) and their totals in Usage. Empty state: “Top-ups and refunds will show here.” (replaces “Runs and top-ups will show here” in WalletBalance.tsx). The section runs short at realistic volume (1–3 rows/month) — let the balance hero breathe, never pad it.
Do NOT over-trim: “View all →” still lands on /billing/history (frame 3) and that statement stays COMPLETE — every category including run/AI/add-on debits. Only this on-page list is wallet-movements-only.
Spent this month is now a link → Usage (the aggregates home) — the wallet hero keeps the stat, Usage answers “where did it go?”. Same connectivity map as Usage → Activity.

768 not yet drawn for this flow. Desktop and 375 are the contract.

MystFlo Platform Preview

Billing

Wallet balance

$41.20

Wallet running low — add funds

Never expires · refundable anytime

Spent this month $18.60 →

+ Add funds

Wallet activity

Added funds Jul 18+$50.00

Refund to card Jul 15−$12.00

Added funds Jul 12+$25.00

View all →

Billing setup

Visa ···· 4242 defaultRemove

+ Add a card

Auto-reload offTurn on →

Warn me below$10 ▾

Notify byEmailSlack

Invoicing details→

Alerts and receipts go to your account email.

Toggle opens the full-screen drawer (rail never shows below lg).
Add funds: full-width under the meta line (desktop keeps it beside the focal).
Same component + data, layout reflows only.

2Add funds — bottom sheet, first top-up (TopUpModal)

Add funds

This step is 375. No 1180 drawing — use the Mobile size.

768 not yet drawn for this flow. Desktop and 375 are the contract.

MystFlo Platform

Billing

Wallet balance

$41.20

Wallet running low — add funds

+ Add funds

Add funds to your wallet✕

$25

$50 ✓

$100

$200

Custom amount

Card · Link · Apple Paypayment form always rendered, no Continue hop

Add $50

Never expires · refundable anytime — it's your money.

No saved card

PaymentElement mounts in deferred-intent mode (no client-secret round trip).
Confirm both funds the wallet AND saves the card.

2Add funds — bottom sheet, card on file (repeat top-up)

MystFlo Platform

Billing

Wallet balance

$41.20

Add funds to your wallet✕

$25

$50 ✓

$100

$200

Custom amount

Visa ···· 4242 08/28 Change

Your card will be charged $50.00.

Add $50.00

Repeat top-up

Saved-card row instead of PaymentElement; same amount rows + one confirm.
The ONE add-money flow — activation / blocked-run presets (FundToGoLiveSheet, AddMoneyToContinueDialog) reuse it with different copy, never a second surface.

3Wallet activity — mobile 375px (/billing/history)

Activity

3 · Wallet activity — left slide-over (/billing/history, prepaid statement)

Billing

← Billing · Wallet activity

Top-up Jul 18+$50.00

Autumn retreat support run Jul 18−$0.08

AI usage Jul 18−$0.02

Spring retreat booking run Jul 17−$1.75

Read My Site Jul 16−$2.50

Full statement for the period.

Tap to return

BillingDrillOver

Masthead stripped — panel sits ABOVE the dimmed header, not beside it.
64px dimmed peek edge right (desktop) + rotated "Tap to return"; Esc / backline close to /billing.
Mobile: full-width panel.

4 · Receipt sheet stacked above the drill — postpaid path (/billing/history/:invoiceId)

Two layers, one z-axis

BillingDrillOver at z-10300; row → /billing/history/:invoiceId, InvoiceDetailModal mounts zIndexOffset=2500 (backdrop/sheet at 10500/12000, above the drill).
Esc closes the receipt first (drill Esc suppressed while open); second Esc → Billing.

z-10300 drill

← Billing · History

Invoices

Jul 18, 2026 Invoice #A1B2C3$41.20 Paid

Jun 18, 2026 Invoice #F7E8D9$34.85 Paid

May 18, 2026 Invoice #B4C5D6$29.10 Paid

Tap to return

z-12000 receipt

Invoice #A1B2C3✕

Paid Jul 18, 2026 · $41.20

On-Brand Support 142 × $0.06$8.52

Retreat Booking 5 × $1.75$8.75

AI usage$23.93

Total$41.20

Download PDF

Postpaid rollback path

Never mounts under the live prepaid rail (no wallet invoices); shown as the unchanged postpaid fallback.
Line items enrich Stripe data with assistant names from the DB mirror.
401/403/404 → "Receipt not found" empty state, never a crash.

5 · Invoicing details — left slide-over (/billing/details)

← Billing · Invoicing details

Billing information

Company nameUglywoo Retreats

Billing emailpeyton@mystflo.com

Phone number+60 ·· ··· ····

Billing address

Street address12 Jalan Example

Apartment, suite, etc.—

CityKuala Lumpur

State / province—

Postal code50450

CountryMalaysia ▾

Tax information

Tax ID typeMY SST ▾

Tax ID00-0000-0000

Saved automatically.

Tap to return

InvoicingDetails + BillingPreferences

Desktop: same panel, wider column, 64px peek edge right.
Guests are gated to the signup modal before the form loads (onSignupRequired).

768 not yet drawn for this flow. Desktop and 375 are the contract.

← Billing · Wallet activity

Top-up Jul 18+$50.00

Autumn retreat support run Jul 18−$0.08

AI usage Jul 18−$0.02

Spring retreat booking run Jul 17−$1.75

Autumn retreat support run Jul 17−$0.08

Read My Site Jul 16−$2.50

Refund to card Jul 10−$15.00

Top-up Jul 02+$10.00

Full statement for the period — every credit and debit.

Prepaid statement

BillingHistory reads the wallet statement (no Stripe fetch).
Flat hairline rows, no row navigation (no per-transaction receipt on this rail).

5Invoicing details — mobile 375px

MystFlo Platform

← Billing · Invoicing details

Billing information

Company nameUglywoo Retreats

Billing emailpeyton@mystflo.com

Phone number+60 ·· ··· ····

Billing address

Street address12 Jalan Example

Apartment, suite, etc.—

CityKuala Lumpur

State / province—

Postal code50450

CountryMalaysia ▾

Tax information

Tax ID typeMY SST ▾

Tax ID00-0000-0000

Saved automatically.

11-field identity form (company / address / tax), reached from "Invoicing details →" in setup.
Same left slide-over choreography as wallet activity; full-width panel.
No Save button — each field commits on blur.

Part II · Future — build later

No deferred items — everything above is the current build (shipped #2578).