{"slug":"notifications","meta":{"title":"Notifications","slug":"notifications","kind":"pattern","summary":"Telling someone that something needs them — with a strict rule about what earns an interruption, because the cost of a wrong one is that all of them get ignored.","problem":"Everything that happens generates a notification, so people mute the product or archive without reading. The one message that genuinely needed a person is now indistinguishable from forty that did not, and it gets missed.","family":["coordinate","recover"],"data_shape":["record"],"principles":["surface-dont-bury","friction","orientation"],"interaction":["feedback"],"density":"low","complexity":"high","status":"stable","visibility":"public","use_when":["Something happens that a specific person must act on, and they are not looking at the screen.","Work is assigned or handed over between people.","A deadline or a threshold is passed and nobody would otherwise notice."],"avoid_when":["The event is something the person did themselves.","Nobody needs to act; it is history, and belongs in the timeline.","It can wait for the next time they open the product — that is a badge, not a notification."],"alternatives":[{"slug":"activity-timeline","when":"The event is worth recording but nobody has to be told."},{"slug":"review-queue","when":"The volume is high and steady. A queue people work beats interrupting them per item."}],"ask_leo":"Add notifications, and be strict about what qualifies.\n\n- Notify a person only when they need to ACT, or when something they are\n  accountable for has changed. If nobody needs to do anything, it belongs in\n  the record's timeline, not in someone's inbox.\n- Never notify someone about their own action.\n- Every notification names the record, says what happened and who did it, and\n  links straight to the thing — not to a list.\n- Group related events. Ten comments on one record in ten minutes is one\n  notification, not ten.\n- Separate urgency from delivery: in-app for everything, email or SMS only for\n  things that cannot wait until the person next opens the product. Let people\n  change that per category.\n- Mark as read when the person opens the linked record, not just when they see\n  the list. An unread count that does not go down is why people stop looking.\n- Give a real preferences screen, per category, and honour it immediately.\n- Do not send a notification during a bulk action for every affected record.\n  Send one summary.\n","related":[{"title":"Comments and Mentions","url":"/patterns/comments-and-mentions","summary":"The most common legitimate trigger — someone named you."},{"title":"Assign an Owner","url":"/patterns/assign-owner","summary":"The other one — work became yours."}]},"body":"## Anatomy\n\n```\n  ┌─ Notifications ───────────────────────── 3 unread ─┐\n  │ ● Priya mentioned you on INV-1043        2h ago    │ ← act\n  │   \"can you check the labour hours before we send?\" │\n  │ ● JOB-204 was handed to you by Sales     yesterday │ ← act\n  │ ● 4 comments on JOB-118                  yesterday │ ← grouped, not 4 rows\n  │   Dana, Sam and 1 other                            │\n  └────────────────────────────────────────────────────┘\n     each row links to the RECORD, not to a list\n```\n\nThe three rules that decide whether this works:\n\n1. **Only actionable events.** The test is whether a reasonable person would do\n   something. If not, it is timeline material.\n2. **Grouped.** One record's burst of activity is one row.\n3. **Deep links.** A notification that drops you on a dashboard has made you do\n   the finding it was supposed to save you.\n\n## Why it works\n\nIt works only through restraint, which is why this entry is mostly about what NOT\nto send. The engineering is easy and the judgment is hard. Every stakeholder wants\ntheir event notified, each request is individually reasonable, and the\ncumulative result is a channel nobody reads.\n\nThe failure is not gradual — it is a **cliff**. Up to some volume, people read\nnotifications. Past it, they mute or bulk-archive, and from that moment the\nchannel carries nothing, including the important messages. You cannot recover\nby adding a priority flag later, because nobody is looking.\n\nSo the useful discipline is a budget, like the one on a glance layer: to add a\nnotification type, justify it against the ones that exist, and be willing to\nremove one.\n\n## Urgency is a separate axis from delivery\n\nTwo questions, often conflated:\n\n| Question | Answer shapes |\n|---|---|\n| Does someone need to act? | Notify, or put it in the timeline |\n| Can it wait until they next open the app? | In-app only, or email/SMS too |\n\nMost events that deserve a notification do **not** deserve an email. Getting\nthis wrong is how a product ends up in a mail filter, at which point the in-app\nnotification is fine and nobody sees the email that mattered.\n\n## Getting it wrong\n\n- **Notifying people about their own actions**, the fastest way to train\n  everyone to ignore the icon.\n- **One per event during a bulk operation** — forty emails from one click.\n- **A count that does not clear** when you read the underlying record.\n- **Links to a list**, not the record.\n- **No per-category preferences**, so the only available control is \"all off\".\n- **Everything by email**, which puts the product in a filter permanently.\n\n## Exemplars\n\n**GitHub's notification model** is unusually explicit about the distinction:\nparticipating versus watching, and per-repository settings. The lesson is that\nthe *reason* you got a notification is itself information, and showing it lets\npeople tune rather than mute.\n\n**Linear** groups aggressively and defaults to in-app, with email reserved for\nthings assigned to you. The result is a notification list people actually read.\n\n**Slack's @-here versus @-channel** is the clearest demonstration of the cliff:\nthe moment a workspace normalises broad mentions, everyone mutes the channel and\nthe mechanism is dead for everyone.\n\nThe extractable rule: **notifications are a budget, not a feature.** Every one\nyou add spends attention that the important ones need, and the failure mode is\nsudden and permanent.\n"}