# Notifications

> Kwark tells people only what they need to act on or would want to know, in the place it concerns, quietly; it sends no email, has no notification feed, and never exists to bring people back.

Source: https://kwark.space/designSystem/patterns/notifications

## The problem

A writer is three pages into the hardest scene of her film. A toast slides in to say a co-writer resolved a comment. A badge pulses on a bell. A red dot appears on an avatar. None of it needs her now, and each one pulls her out of the page.

Most software treats notifications as a growth tool: streaks to protect, digests to open, red counts to clear. Kwark's mission rules that out in plain words: "No notifications that exist to bring people back." And the calm test asks of every screen: does anything ask for attention it has not earned?

But some things do need a person: someone is waiting to be let into the project, a revision was issued, an action can be undone for a few seconds, their words have not reached the cloud. Those must be told clearly, in the right place.

## Kwark's answer

### Tell only what earns it

A notification is allowed when it is one of these:

| Kind | Example | Form |
|---|---|---|
| The result of what you just did | "Rev 3 issued. Save it as PDF to send it to the crew." | Toast |
| Something you can undo for a moment | "Cover removed." **Undo** | Toast with action, 8 seconds |
| Someone is waiting for you | "People asking to join" | The bell, with a count |
| Someone spoke to you | "Someone mentioned you" | In the comment dock, and a dot |
| Your work is not where you think | "Saved on this device" | The sync word, and a banner if you must act |
| Something on this page needs you before it can continue | "Location to be confirmed. Add it before issuing the call sheet." | Inline notice |

Everything else is not said. A co-writer resolving a comment, someone opening the project, a save that worked: these are visible where they happened, if you look, and nowhere else.

### Kwark sends no email

Kwark has no mail sender. Sharing says so and gives the owner **Copy invite message** and **Email the invite** from their own mail app (Decision 0042). Emailed crew-call invitations with calendar files are written and tested but on hold, and nothing is deployed; the button to send them stays hidden until a mail sender exists. **Never** write "We'll email you" or "Invitation sent" anywhere in Kwark.

### The bell is for people waiting

The only bell in Kwark is `AccessRequestsBell`: people asking to join any of your projects. Its bubble (accent) is the number waiting. Opening it lists "People asking to join" with **Keep**, **Decline** and **Open project**. It does not pulse (Decision 0042 removed the pulse). If an answer could not be saved: "That request was not answered. Open the project and try from Share."

### Dots, each with a reason

Every dot has a row in the element register saying what it means and what to do:

- **Dot on the floating button (phone)**: comments waiting for you. It is the button's only badge (Decision 0016).
- **Dot on the screenplay's Menu**: comments for you (Decision 0015).
- **Dot on View**: a focus mode is on.
- **Bubble on the bell**: people asking to join.

A dot with no reason is removed.

### Toasts

From `components/ui/Toast.tsx`:

- Four tones: success, info, warning, error. Each has words; the tone supports them.
- Dismiss after **4 seconds**, or **8 seconds** when there is an action (such as Undo). The timer pauses on hover and focus.
- At most one action, named with its verb.
- `role="status"` for ordinary toasts; `role="alert"` for errors.
- Bottom right on desktop; above the floating button on a phone.

## Anatomy

| Part | Means |
|---|---|
| Toast | Something just happened because of you |
| Toast action | One reversible step, usually Undo |
| Bell and bubble | People waiting to be let in; the number is how many |
| Mention row in the dock | Remarks that name you; **Show** |
| Dot | One recorded meaning, per surface |
| Banner | A state that stays until it changes |
| Inline notice | This part of this page needs something |

## Rules

- **Must** tie every notification to something the person did, is waiting on, or must act on.
- **Must** put every dot, badge and count in the element register with its meaning.
- **Must** give toasts words, one action at most, and the 4 or 8 second timing with pause on hover and focus.
- **Never** notify to bring people back: no streak reminders, no "You haven't written in a while", no digests, no "what's new" pop-ups.
- **Never** promise email or say anything was sent. Kwark sends no email.
- **Never** pulse, bounce, glow or shake a badge.
- **Never** use red for a count. A count is not a danger.
- **Never** interrupt the page while someone writes for anything that can wait. The screenplay hides the app's floating pen and comments bubble in favour of its own rail and Menu entries.
- **Always** say the result in the words the action used: Issue, "Rev 3 issued"; Move to trash, "Moved to trash".
- **Always** show a count only where it is useful: Home's tabs show a count only on the selected tab (Decision 0021).

## Edge cases

- **Many toasts at once** (a batch of imports). Stack at most three; combine the rest into one ("3 projects imported").
- **A toast during a sheet or dialog.** It appears above the sheet, never under it, and never steals focus.
- **The person is offline.** Do not toast every queued save; the sync word carries it.
- **A mention while writing in the screenplay.** The dot appears on Menu; nothing slides over the page.
- **Access ended.** Not a toast. The person sees the named access-ended page when they next open the project.
- **Quota reached for the day.** Say it once, as a quota, not a fault in their change.

## Phone and desktop

Desktop: toasts bottom right, the bell in the app header, mentions in the comment dock beside the page. Phone: toasts sit above the floating button's slot and span the width minus the gutters; the bell keeps its place in the app chrome and must never collide with the one-line header or the floating button; the dot on the floating button is the only badge on screen.

## Writing

- Results: "Rev 3 issued. Save it as PDF to send it to the crew." "Copied. Paste it into WhatsApp or an email." "Story restored" / "It is back in your library".
- Requests: "People asking to join", **Keep**, **Decline**, **Open project**.
- Mentions: "Someone mentioned you", "{n} remarks mention you", **Show**.
- No "Success!", "Yay", "Oops", or exclamation marks. Legacy toasts such as "Account created successfully" with an exclamation mark, or "Failed to delete", are deviations to fix.

## Accessibility

- Toasts are in a polite live region; error toasts use `role="alert"`.
- A toast's action is reachable by keyboard before it dismisses, and focusing it pauses the timer.
- The dismiss button is named for what it dismisses ("Dismiss notification").
- Dots and bubbles have text equivalents in their control's name: "Comments, 2 waiting", "People asking to join, 1".

**Do:** "Cover removed." with **Undo** for 8 seconds, pausing on hover.

**Don't:** "Success!" in green, gone in 2 seconds, with nothing to do.

**Do:** A bubble with "1" on the bell when Asha asks to join; it never pulses.

**Don't:** A pulsing red badge for every comment resolved by anyone.

**Do:** After inviting: "Kwark doesn't send emails. Let them know, and say which Google account to use." with **Copy invite message**.

**Don't:** "Invitation sent" when no email was sent.

## Demo

```html
<div class="kw-toast-stack" aria-label="Example notifications">
<div class="kw-toast kw-toast--info" role="status"><span>Moved to trash.</span><button class="kw-text-button" type="button">Undo</button></div>
<div class="kw-toast kw-toast--success" role="status"><span class="kw-toast__icon" aria-hidden="true">✓</span><span>Story restored. It is back in your library.</span><button class="kw-icon-button" type="button" aria-label="Dismiss notification">×</button></div>
<div class="kw-toast kw-toast--error" role="alert"><span class="kw-toast__icon" aria-hidden="true">!</span><span>That request was not answered. Open the project and try from Share.</span></div>
</div>
<div class="kw-menu" role="dialog" aria-label="People asking to join" style="width:340px;display:grid;gap:6px;padding:12px">
<strong>People asking to join</strong>
<div class="kw-row"><span class="kw-avatar" style="--kw-peer:var(--k-brand-aqua)">AK</span><span class="kw-row__title">Asha Kumar<br><span class="kw-row__meta">Blank Pages · as Actor</span></span></div>
<span style="display:flex;gap:8px;justify-content:flex-end"><button class="kw-button kw-button--sm" type="button">Decline</button><button class="kw-button kw-button--sm kw-button--primary" type="button">Keep</button></span>
<a class="kw-link" href="#">Open project</a>
</div>
```

## Related

[Toast](https://kwark.space/designSystem/components/toast.md), [Badge](https://kwark.space/designSystem/components/badge.md), [Status dot](https://kwark.space/designSystem/components/status-dot.md), [Banner](https://kwark.space/designSystem/components/banner.md), [Collaboration](https://kwark.space/designSystem/patterns/collaboration.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md), [Errors](https://kwark.space/designSystem/patterns/errors.md).

## AI readiness test

**Task:** The founder's co-writer asks for a notification when a scene is changed.

**Give the agent:** This page, the mission ("What we will not do"), Collaboration, the element register.

**Constraint:** Nothing that exists to bring people back.

**A reliable answer:**
- Asks what they need to act on (a review request, a mention) rather than notifying every change
- Proposes a mention or a comment pin in the place it concerns, with the dot recorded in the register
- No email (none is sent), no feed, no pulsing badge
- Leaves change marks in the script as the record of what changed
