# LYNX: full mobile design

The new look (liquid glass, logo palette, light and dark) with the full content:
- every screen of the old LYNX app (prototype `lynx/` and the Flutter port, ids 1.0–15.5);
- the PRD screens neither had (ids 16+).

It is Swahili first, with English on a switch, and uses TZS / KES / UGX / NGN.

## Open it

Double-click `run.bat`. It starts a small local server and opens http://127.0.0.1:8010/; keep its window open while you look. Then choose **Mobile app**.

**In the stage:**
- **← / →** step through the screens.
- **L** switches Kiswahili / English.
- **T** switches light / dark.
- The top-right controls also do language, zoom and theme.
- The list on the right jumps to any screen; amber "concept" marks what the team still has to decide.
- `?screen=16.2` opens one screen directly.

`gallery/index.html` shows every screen as a picture (Swahili light and dark, English light), with no server needed.

## Flows (117 screens)

| Flow | Screens |
|---|---|
| Start | 1.0 intro · 1.1 language · 1.1s story onboarding · 1.2 create account · 1.3 email code · 1.4 PIN · 1.5 fingerprint · 1.8 sign in · 1.9 2FA code · 1.10 forgot password |
| Verification | 1.11 levels and what each unlocks · 1.6 ID + selfie (Didit) · 1.7 under review → approved · 1.12 the gate sheet |
| Home | 2.1 Home (available + pending T+1, Toa sasa, today's numbers, payday and approvals) · 2.2 hidden · 2.9 new account · 2.3 currencies · 2.4 notifications · 2.5 money received · 2.6 Kibubu · 2.7 search · 2.8 wallet |
| Get paid | 6.5 hub (link, TAN-QR, invoice, USSD request) · 6.1 links · 6.2 create · 6.3 share · 6.4 live link tracking · 10.2 my QR |
| Invoices | 19.1 list · 19.2 new · 19.3 detail (paper, Draft → Sent → Viewed → Paid) |
| Send & payouts | 3.1 hub · 3.2 recipient + name check · 3.3 amount · 3.4 review · 3.5 processing (5 s to stop) · 3.6 printed receipt · 3.7 saved recipients |
| Lipa | 4.1 hub · 4.2 till / paybill · 4.3 amount + swipe · 4.4 USSD push waiting |
| Bank | 5.1 directory · 5.2 account lookup · 5.3–5.4 international (concept) · 5.5 proof of payment |
| Settlements | 16.1 history · 16.2 detail (gross → fee → net) · 16.3 Toa sasa (instant) |
| Approvals | 17.1 queue · 17.2 held payout, explained |
| Bulk payouts | 8.1 hub · 8.2 CSV · 8.3 validation + fix · 8.4 two-person approval · 8.5 live progress |
| Payroll | 18.1 groups · 18.2 group · 18.3 new · 18.4 run now · 18.5 history |
| Bills | 9.1 categories (Selcom billers) · 9.2 lookup + pay · 9.3 LUKU token · 9.4 history |
| QR | 10.1 scanner · 10.3 scanned → swipe to pay |
| Activity | 11.1 transactions · 11.2 detail (timeline, fees, risk) · 11.5 refund · 11.6 dispute · 11.3 statement · 11.4 Mwezi wako · 11.7 insights |
| Cards (concept) | 7.1 carousel · 7.2 reveal · 7.3 controls · 7.4 limits · 7.5 new virtual card · 7.6 tiers |
| Money in & out | 14.1–14.2 add money (concept) · 14.3–14.4 cash out code (concept) · 14.5 bundles |
| Sales tools | 20.1 customers · 20.2 customer · 20.3 subscriptions · 20.4 discount codes · 20.5 disputes |
| More & security | 12.1 More (every service + settings) · 12.7 business profile · 12.2 payout accounts · 12.3 security · 12.5 2FA setup · 12.6 sessions · 12.8 notifications · 12.4 help & chat |
| Developer | 21.1 API keys (shown once) · 21.2 webhooks · 21.3 deliveries & logs |
| Standouts | 15.1–15.2 Michango · 15.3 Uliza LYNX · 15.4 Okoa chenji · 15.5 offline queue |
| System states | 13.1 offline · 13.2 not enough balance · 13.3 over limit · 13.4 camera · 13.5 lockout · 13.6 payment failed · 13.7–13.9 empty states |

## PRD numbers used

- **KYC limits:** 300K / 3M / 15M / 50M a day.
- **Tier 2 unlocks:** payouts, bills, P2P, bulk, payroll and sandbox keys.
- **Fees:**
  - collections 2.2%;
  - payouts TZS 1,000 to mobile money, 2,000 to a bank, free LYNX to LYNX;
  - instant settlement +1%.
- **Settlement:** T+1 at 09:00.
- **Velocity:** 500 bulk payouts an hour, 1,000 a day.

## Decisions still with the team (marked "concept")

- Cards (7.x)
- International SWIFT (5.3–5.4)
- Adding money from your own wallet (14.1–14.2)
- Agent cash-out (14.3–14.4)

## Not covered

`Lynx Dashboard.html` and `Lynx Landing Page.html` keep their original content. They show USD amounts, use the old sample names and have no dark mode. The landing page's phone shows the new Home.

## Files

| Path | What |
|---|---|
| `shared/tokens.css` | Palette, light/dark tokens, the liquid-glass material |
| `shared/icons.jsx` | The line icon set |
| `mobile/data.jsx` | Language helper, PRD numbers, all sample data |
| `mobile/ui.jsx` | The kit: glass controls, nav droplet, sheets, keypad, money, rows |
| `mobile/s-*.jsx` | Screens by flow |
| `mobile/app.jsx` | Registry, navigation, state, stage |
| `mobile/_v1/` | The first version's screens, kept for reference |

## Added 2026-10-21 (evening)

- **Intro and onboarding from the Flutter app:**
  - 1.0 is the cinematic blades intro, slowed to about 7 s, with the partner logos orbiting.
  - 1.1 is the Flutter welcome: glass crystal, LYNX, tagline, Kiswahili | English pill.
  - 1.1s is the four-page story onboarding: it advances every 4 s, hold to pause, tap to step, with the glass slab wipe.
- **Providers in four countries:** the selected currency picks the country, and the country sets the networks, banks, billers, phone prefix and number format.
  - **Tanzania:** M-Pesa, Mixx, Airtel, HaloPesa, AzamPesa, T-Pesa.
  - **Kenya:** Safaricom M-Pesa, Airtel; KCB, Equity, Co-op, NCBA.
  - **Uganda:** MTN MoMo, Airtel; Centenary, dfcu.
  - **Nigeria:** OPay, PalmPay, Moniepoint, Kuda, MTN; GTBank, Access, Zenith, UBA, Fidelity, Sterling.
  - Logo sources are in `assets/logos/SOURCES.md`; companies without a logo show a letter mark.
  - `?cur=KES`, `?cur=UGX` or `?cur=NGN` opens the app in that country.
- **Real QR codes:** every QR in the app now scans, using qrcode-generator 1.4.4 from `vendor/`.
- **Phone mode:** `?app` (or opening it on a phone) shows the app alone, full screen. `app.html` is the short link to it.
- **Landing page:**
  - realistic iPhone frames;
  - the hero phone sized to the window;
  - LYNX content in TZS with real partner logos;
  - a real QR that opens the app on your phone.
- **`run.bat` shares the design on your Wi-Fi** so the landing page's QR works from a phone.
- **Cards, as in the Flutter app (7.1–7.6):**
  - Debit / Credit tabs and a deck you can swipe;
  - each card's balance or available credit, Active / Frozen, and frost that spreads over a frozen card;
  - details behind Face ID that hide again after 30 s, with copy buttons;
  - where the card works (online, ATM, international, contactless, subscriptions, magstripe);
  - limits with draggable sliders, an 80% marker and SMS alerts;
  - six designs to mint (the laser engraves the card, then it spins into the wallet);
  - Silver / Gold / Black tiers, ordered behind verification.
- **New card screens:** 7.7 lost or stolen (block and reissue), 7.8 change card PIN, 7.9 add to Google Pay / Apple Pay.
- **Settings:**
  - **12.9 Settings hub:** account, payments and settlement, security and privacy, notifications and sounds, appearance and accessibility, data, developer, about, close account. Saved on the device.
  - **12.10 Team and roles:** members, the permissions grid, invites.
  - **12.11 Settlement schedule:** when, where, how much to keep, automatic instant.
  - **More:** the gear opens Settings, and the verification card shows the levels.
- **Receipts, as in the Flutter app (`mobile/receipt.jsx`):**
  - **How it prints:** a glass LYNX printer feeds a thermal-paper slip out of its mouth in short jerks, with the print sound. The LYNX mark draws itself on the slip, then the round LYNX · PAID · IMELIPWA stamp slams down with a thump and a vibration. Tap to skip.
  - **Where it's used:**
    - 3.6 is every payment out: a person, a bank, a till, a QR or a bill.
    - 9.3 LUKU lights up the house and prints the token slowly, with VAT and REA.
    - 5.5 proof of payment is stamped SENT · IMETUMWA.
    - 11.2 has "View receipt", stamped PENDING or REFUND when that applies.
  - **Confetti:** only on a first payment.
  - **Sound and vibration:** they follow the Settings switches (sound files in `assets/sfx/`).