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”.
“Cover removed.” with Undo for 8 seconds, pausing on hover.
“Success!” in green, gone in 2 seconds, with nothing to do.
A bubble with “1” on the bell when Asha asks to join; it never pulses.
A pulsing red badge for every comment resolved by anyone.
After inviting: “Kwark doesn’t send emails. Let them know, and say which Google account to use.” with Copy invite message.
“Invitation sent” when no email was sent.
Demo
<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, Badge, Status dot, Banner, Collaboration, Sharing and roles, Errors.
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