From harness-claude
Guides writing notification copy for toasts, banners, modals: calibrates urgency, front-loads subjects, limits to one action, matches length to dismissal behavior. For UX alerts without overwhelming users.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Notification and alert copy — urgency calibration, actionability, toast vs banner vs modal selection, and writing messages that inform without overwhelming
Generates specific success confirmation messages, calibrated celebrations for milestones, and next-step prompts for UI toasts, emails, and undo links after actions.
Writes user-facing copy following Sentry brand guidelines using Plain Speech (default) or Sentry Voice for UI text, errors, empty states, docs, and marketing.
Writes UI text, error messages, empty states, onboarding, docs, and marketing copy following Sentry's Plain Speech (default) and Voice guidelines.
Share bugs, ideas, or general feedback.
Notification and alert copy — urgency calibration, actionability, toast vs banner vs modal selection, and writing messages that inform without overwhelming
Match notification type to urgency level — the component choice is a copy decision. Toast for completed actions and low-urgency info (auto-dismisses in 3-5 seconds). Banner for persistent warnings and system status (stays until dismissed or resolved). Modal for blocking system states that require immediate action. Using a toast for a billing failure that requires action — and having it auto-dismiss — means the user misses critical information. Using a modal for a routine "changes saved" message interrupts the user unnecessarily. The component type is the first line of urgency communication; the copy reinforces it.
Front-load the subject — actor, then action. "Jordan commented on your PR" not "You have a new notification from Jordan." "Deployment failed" not "There was a failure in your deployment." "Payment of $49.99 succeeded" not "Your recent payment transaction has been successfully processed." The first word of a notification is the most important word — it determines whether the user reads the rest. In a notification list, ten notifications all starting with "You have" are indistinguishable at a glance. Ten notifications starting with different actors or objects are scannable.
Include one action maximum — never two. "Reply" or "View" — not both. When a notification offers two actions of equal weight, the user is paralyzed: which one do they need? Two actions also increase the risk of accidental taps on mobile. If two actions are necessary, make the primary action a button and the secondary action a plain text link — the visual hierarchy communicates the priority. Slack's notifications offer "Reply" as the only action. Linear's notifications offer "Open issue" as the only action. The constraint forces the writer to decide: what is the single most important thing the user might want to do?
Calibrate length to dismissal behavior. Toasts auto-dismiss in 3-5 seconds — the user reads approximately 7-10 words in that window. Keep toast copy to 40-80 characters. Banners are persistent — the user can read more. Keep banner copy to 80-120 characters for the primary message, with a "Learn more" link for detail. Push notifications have a subject line (40-50 chars) and a body (100-120 chars) — front-load the most critical information in the subject. The character limit is a function of the time the user has to read the notification, not an arbitrary constraint.
Never say "notification" in a notification — it is redundant. "You have a new notification" is a notification telling the user they have a notification. "Jordan commented on your pull request" is a notification. "New message from Jordan: 'Can you review the PR?'" is a notification. The word "notification" adds nothing to the message and wastes space in a character-constrained format. The same principle applies to "alert," "message," and "update" — lead with the actual content, not the content category.
Name the actor in social and activity notifications. "Jordan" not "Someone." "The Acme team" not "A team." "You" only when there is no other actor (system-generated, user-initiated). Social notifications that anonymize the actor are less actionable and less engaging. GitHub names the specific user who commented, reviewed, or merged. Slack names the specific person who messaged or reacted. Linear names the assignee or commenter. The name creates context for the notification's relevance — "Jordan commented" is more actionable than "Someone commented" because the user knows if Jordan's opinion matters to them right now.
Use past tense for completed events, present for ongoing, future for upcoming. "Deployment completed" (past, done). "Deployment in progress — 2 of 4 steps complete" (present, active). "Deployment scheduled for 3:00 PM EST" (future, upcoming). The tense communicates the state without additional words. "Your deployment is complete" wastes "is" when "Deployment complete" communicates the same state. "There has been a completion of the deployment process" is the robot-voice version of "Deployment complete." Match tense to state.
For actionable notifications, make the action obvious without requiring the user to open the source. "Jordan requested a review on PR #247: Fix authentication timeout" gives enough context that the user can decide whether to act without opening GitHub. "Jordan requested review" requires opening GitHub to understand what to review. "New request" requires two clicks to understand. The notification should answer: who, what, and enough context to decide whether to act now. The action button provides the "act now" path; the copy provides the "should I act now?" context.
Select the notification type based on urgency and whether the user can safely continue:
| Type | Urgency | Dismissal | Max Length | Action Required? | Example |
|---|---|---|---|---|---|
| Toast | Low | Auto (3-5s) | 80 chars | Optional | "Changes saved" |
| Snackbar | Low-medium | Auto + dismiss | 120 chars | One optional | "Message sent. Undo" |
| Banner | Medium | Manual | 160 chars | One recommended | "Your trial ends in 3 days. Upgrade." |
| Alert banner | High | Manual | 200 chars | One required | "Payment failed. Update billing." |
| Blocking modal | Critical | Action only | Full modal | Required | "Your account has been suspended." |
Completed action (success toast): Past tense, object named. "Issue #247 closed." "Report exported." "Team member invited." Never: "Done!" or "Success!" — these are too vague to be meaningful.
Social activity: Actor + action + object. "Jordan commented on your PR." "The Acme team assigned you to Issue #42." "Sarah approved your expense report." Name the actor first.
System alert: System + consequence + action. "Deployment failed. View logs →." "Sync paused. Check your connection." "Storage 90% full. Manage files →."
Scheduled event: Time + event. "Team standup in 15 minutes." "Invoice due in 3 days." "Subscription renews on April 30."
Billing: Specific amount + action. "Payment of $149 failed. Update card →." "Your plan renews for $49 on May 1." Always include the dollar amount — "payment failed" without an amount is less actionable than "payment of $149 failed."
Push notifications are read in a notification tray without opening the app — the subject line must be independently comprehensible:
| Category | Pattern | Example |
|---|---|---|
| Social | Actor + action + object | "Jordan commented on your pull request" |
| Reminder | Event + time | "Team standup starts in 10 minutes" |
| Alert | System + consequence | "Deployment failed on acme-api" |
| Billing | Amount + action needed | "$149 payment failed — action required" |
| Progress | Operation + status | "Your export is ready to download" |
The Notification Notification. "You have a new notification from Jordan about your project." Every word except "Jordan" and "project" is structural overhead. The notification says it is a notification — obvious — that it's new — obvious — from a person — obvious. The content is "Jordan did something to your project." What did Jordan do? What project? These are the words that belong in the notification. The fix: delete every word that describes the notification format rather than the notification content.
The Action Overload. A notification with three or four action buttons: "Reply," "Mark as read," "Snooze," "View in app." On mobile, four action buttons on a notification makes tapping the correct one difficult. In a notification feed, four buttons per notification creates visual noise that makes scanning impossible. The fix: one primary action button. Surface secondary actions in the full notification view, not in the notification itself.
The Urgency Inflation. Marking routine events as urgent using all-caps, exclamation points, or "URGENT:" prefixes. "URGENT: Jordan commented on your issue" — Jordan's comment is not an emergency. Urgency inflation trains users to ignore urgency signals, which means real urgent notifications (payment failure, security alert) are ignored alongside the inflated ones. Reserve urgency markers for genuinely time-sensitive events: "ACTION REQUIRED: Payment failed — account suspended in 24 hours."
The Vague Alert. "Something happened to your project." "There's a problem with your account." "An error occurred." The user cannot act on a vague alert. They must open the app, navigate to the relevant section, and investigate what happened — and by then, the notification has already failed at its primary job (giving the user enough context to decide whether to act). Every notification must name the specific subject, action, and consequence. "Payment failed" is a vague alert. "Payment of $149.00 declined — update your billing info to keep your subscription" is actionable.
GitHub's PR Notification System. GitHub's notifications follow a strict format: actor + action + context. "Jordan Doe reviewed your pull request: Fix authentication timeout in auth.ts." The reviewer's full name, the action (reviewed), the PR title (which adds context), and the file context. In the notification feed, each notification is independently scannable — users can triage 20 PR notifications in seconds because each one names a different actor and action. GitHub's mobile push notifications truncate the PR title but always lead with the actor's name: "Jordan Doe reviewed your PR."
Slack's Message Notifications. Slack's in-app notifications are minimal and conversational: "Jordan: Can you review this before the meeting?" — sender name, message content. No preamble, no "You have a new message from," no "In #engineering." The channel context is provided visually (the notification appears under the channel or DM), so the copy does not need to repeat it. Slack's push notifications add the channel for non-DM messages: "Jordan in #engineering: Can you review this before the meeting?" — adding exactly the context needed for a push notification where visual context is absent.
Linear's Issue Assignment Notifications. Linear's notifications follow: "Jordan assigned you to: #247 Fix authentication timeout." Assignee, action, issue number, issue title. The issue number allows users who track by number to identify the issue without opening it. The issue title provides enough context to prioritize. Linear's notification feed is sorted by recency and can be filtered by type (assigned, mentioned, commented) — the copy format is consistent across types, making the feed scannable by the leading action word.
Stripe's Payment Alert System. Stripe's payment failure notifications balance technical precision with human language: "A payment of $149.00 from Acme Corp failed. The card was declined. Update your payment method to keep Acme Corp's subscription active." Three sentences: amount and payer (context), reason (cause), consequence and action (next step). Stripe names the specific customer, the specific amount, and the specific consequence — which is critical for merchants who process multiple customers' payments simultaneously. Vague "payment failed" notifications are useless for a merchant with 1,000 active subscriptions.
Email notifications extend the in-app notification's reach. Subject lines must function without opening the email:
Email notification subjects follow the same actor-first, specificity-over-brevity rules as in-app notifications, with the additional constraint that subjects compete with dozens of other emails in an inbox — they must be distinguishable at a glance.
Before shipping notification copy, verify each item:
| Check | Pass Criteria |
|---|---|
| Component type matches urgency | Toast = low, banner = medium, modal = blocking |
| Actor-first structure | Subject/actor is the first word, not structural preamble |
| Length within limit | Toast ≤80 chars, banner ≤160 chars, push subject ≤50 chars |
| One action maximum | Single primary action button or link |
| No redundant category word | "Notification," "alert," "message" not as first word |
| Correct tense | Past for completed, present for ongoing, future for upcoming |
| Social notifications name the actor | Person's name used, not "Someone" or "A user" |
| Billing notifications name the amount | "$149" not "a payment" — specific amounts always |
Notification copy failure has a compounding effect: poor notifications train users to dismiss all notifications without reading, which means critical notifications (payment failures, security alerts) are also dismissed. Investment in notification copy quality pays back in user trust and actionability of the entire notification system.