# One app, four clients

*3 September 2026. Don: "make sure the UI and look of icons is identical between the apps … this
should be as 100% consistent as the OS will allow and will hold for the MacOS and Windows clients
as well … We want to leverage people's familiarity with other messaging apps and particularly with
WA such that there will be almost no learning curve … the behind the scenes work is where most of
the difference will live."*

This is the reference the iOS, Android and future desktop clients all build against. It exists
because the drift was already real after two clients; with four it would be unfixable.

## The rule

**Where WhatsApp has solved a layout, copy the solution.** Not the branding, not the colours — the
*shape*: what lives in which tab, what a long-press offers, where the archive sits, what tapping a
name does. Every hour a user spends learning our navigation is an hour spent on something that is
not the reason to use this app.

**Where we differ, differ for a reason and only in the places the reason applies.** Pairing has no
WhatsApp equivalent because WhatsApp has phone numbers and we do not. That justifies a different
*setup* flow. It does not justify a different contact list.

**Platform idiom wins over cross-platform sameness where they collide.** A back gesture, a
navigation bar, a share sheet — use what the OS gives, because a user's familiarity with their
*phone* outranks their familiarity with our other client. Everything above that layer matches.

## Structure

Three top-level destinations, in this order, on every client.

| | Contains | Archive |
|---|---|---|
| **Chats** | Active conversations, newest first, pinned above | **A row at the top of the list**, not a tab and not a menu item — exactly WhatsApp's placement |
| **Contacts** | Everyone paired or named, whether or not a word has been exchanged | — |
| **Settings** | Everything else | — |

Chats and Contacts are **separate lists of different things** and must stay so: a conversation is a
thread, a contact is a person, and a person with no thread still exists.

## Tapping a name opens their profile

From either list, and from the conversation header. One screen, the same on every client, in this
order:

1. **Name**, editable in place. We own this string — there is no address book behind it — so
   renaming is ours to offer and must exist on every client.
2. **Pairing state**, and the verification code when there is one.
3. **Message**, which opens or creates the thread.
4. **Mute**, and **notification sound for this conversation**.
5. **Block**, **Report**, **Delete**.

Deliberately *not* here yet, and each is a Tier 2/3 item rather than an omission: shared media,
disappearing-message timer, and a per-contact calling handoff.

## The icon vocabulary

One meaning, one icon, everywhere. The two platforms name them differently; the *shape* must read
the same.

| Meaning | SF Symbol (Apple) | Material (Android/desktop) |
|---|---|---|
| Add a contact | `person.badge.plus` | `PersonAdd` |
| Pair / scan a code | `qrcode.viewfinder` | `QrCodeScanner` |
| Show my code | `qrcode` | `QrCode2` |
| Message someone | `message` | `Chat` |
| Contacts list | `person.2` | `People` |
| Settings | `gear` | `Settings` |
| Archive | `archivebox` | `Archive` |
| Mute | `bell.slash` | `NotificationsOff` |
| Pin | `pin` | `PushPin` |
| Mark unread | `envelope.badge` | `MarkEmailUnread` |
| Copy | `doc.on.doc` | `ContentCopy` |
| Attach a picture | `photo` | `Image` |
| Message info | `info.circle` | `Info` |
| Block | `hand.raised` | `Block` |
| Delete | `trash` | `Delete` |

**Adding a row here is the cheap moment.** Adding an icon to one client without adding it here is
how the next divergence starts, and the drift this document was written to fix took two clients and
about a week to appear.

## Known divergences, to be closed

Found auditing on 3 Sep 2026:

- **Rename existed on Android and not iOS.** Closed.
- **Pairing was one button on iOS and three on Android** (Show my code / Scan their code / Enter a
  code). One entry point, then the choice inside — the shorter list is the better one.
- **The add-contact icon differed**, which is what Don noticed first.

## What does *not* have to match

The parts a user never sees, and the parts where honesty beats symmetry:

- **Transport, storage and crypto** — all of it, which is where the real work is.
- **Anything one platform genuinely cannot do.** iOS has no system notification-sound picker, so it
  ships bundled sounds where Android offers every sound on the phone. Faking parity by hiding
  Android's picker would make both worse.


## Big screens: iPad, macOS, Windows, Android tablets (`J100`)

Same shape and same words on every platform, never the same pixels.

**Panes.** Three when the window is wide (rail · list · thread), two when medium, one when
phone-width. Width decides, not device, so a resized window behaves like a smaller device.

**Thread header.** Picture, name, status letters beneath the name, call and video at the right.
Back appears only in one-pane mode.

**Menu bar** (macOS, iPadOS 26+, Windows -- and nothing may live *only* here):

| Menu | Items | Shortcut |
|---|---|---|
| File | New Chat · New Contact · Check Now | Cmd/Ctrl N · Shift N · R |
| Profile | switch profile · Manage Profiles | Cmd/Ctrl 1-9 |
| View | Messages · Contacts · Settings | Cmd/Ctrl Alt 1-3 |
| Help | How Channel picks a path · Privacy | -- |

**Input.** Pointer hover states, arrow keys through the list, Return to send wherever a keyboard
exists.

A new platform implements this section. It does not copy screenshots of the others.