Every ping is a person, showing up

The complete notification system: every trigger, who receives it, what it says, what it shows, and where a tap lands. The doctrine in one line: we announce people, and we announce openings — never mechanics, never nags. Almost every push title is a human name; the two exceptions are the app itself (rare announcements) and a facepile (batching, V2). If a notification wouldn't make sense spoken aloud by that person, the copy is wrong. In-app surface: notifications.html.

Anatomy — the push on the lock screen

Title = the actor's name. Body = the action + a content preview (≤150 chars, cut at a word, no emoji). Step and journey pushes carry the step photo (contentImageUrl, 150px): a compact thumbnail collapsed, the full photo expanded. Comment-family pushes stay text-only — the words are the content. People pushes carry the face only.

iOS · collapsed

Maya Okonkwonow

Stepped with you by heart: “Trail run before work — up the ridge and back.”

The step photo rides the right slot. iOS keeps the app-icon position for Stepo's mark — the actor lives in the title.

iOS · long-press expanded

Marco Ferri2m

Finished Learn to play guitar — the finale is live

A Notification Service Extension fetches the photo and attaches it. The finale push is the highest-value tap in the app — it arrives while the Celebrator window is open.

Android · banner

Linh Trầnnow

Stepped with you: “so proud of this one”

Android's largeIcon slot takes the actor's face; the step photo expands below as BigPicture. The person is visible before a single word is read.

Grouped · thread per step

Kofi Asante5m

Stepped with you by share: “Trail run before work…”

Interactions on the same step share a thread — a busy window stacks into one card instead of wallpapering the lock screen. The badge number still counts every unseen row.

The matrix — every notification in the system

15 live types from the backend enum, two proposed recognition types, and the deferred batch pair. Push title is always the actor; the example column shows title + body verbatim. Tap destinations are contract — the row and the push land on the same screen.

One step, one push

A published step could legally trigger three notifications; it sends exactly one, and never before its media finishes processing — nobody taps into a placeholder. Followers of both the person and the journey are deduplicated.

The badge tells the truth

Instagram's Seen / Read split, server-authoritative: the number on the icon is always a fresh COUNT of unseen rows, pushed as an absolute value with every notification — never a client-side +1, so it can't drift. The Activity tab carries that same number, counting to 9 and then reading 9+.

Asking for the permission

The channel above only exists if the OS lets us use it, and Stepo's loop travels through it: a user without notifications cannot know a journey they follow is live, so they are not experiencing the product at all. The two failure modes are asymmetric — asking too often costs a sheet swipe, never converting costs the user, permanently and invisibly — so the cadence leans toward asking, bounded only by what the OS makes mechanically pointless. The gate is live OS state, never an app latch that stands in for it: a primer may show whenever the OS will still prompt and the cadence allows it. iOS self-latches after its one alert; Android grants a second prompt after a soft deny and the cadence spends it. The ruling lives in DESIGN.md "The one shot at the prompt".

The quiet rules

What keeps the lock screen worthy of trust.

User controls

Seven toggles plus the master switch, grouped by relationship direction — the canonical layout is settings-notifications.html. Toggles govern push delivery only; the Activity screen always shows every row. Announcements ride the master switch. Muting on Stepo filters the feed only; it does not filter notifications (blocking does). Per-person / per-journey overrides are V2.