> ## Documentation Index
> Fetch the complete documentation index at: https://content-designer-ux-writing-skill-26.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing notifications

> Create timely, valuable notifications that inform without overwhelming

Notifications deliver important information to users at the right time. Good notification copy is clear, actionable, and respects user attention.

## Purpose

Notifications should:

* Deliver timely, valuable information
* Clearly state what happened
* Provide context when needed
* Enable quick action

## The pattern

```
[Verb-first title] + [Contextual description]
```

Notifications typically have two parts:

1. **Title**: What happened (required)
2. **Description**: Additional context or action (optional)

## Notification types

<Tabs>
  <Tab title="Action-required">
    ### Action-required notifications

    **Purpose**: Alert users to something that needs immediate attention

    **Characteristics**:

    * Intrusive (modal, banner, or blocking)
    * Time-sensitive
    * Clear call to action

    **Pattern**: `[Alert]. [Why]. [What to do].`

    **Examples**:

    * "Update required. This version is no longer supported. Update now to continue."
    * "Payment failed. Your card was declined. Update payment method."
    * "Session expiring. You'll be logged out in 2 minutes. Stay logged in?"

    <Warning>
      Use action-required notifications sparingly. They interrupt users and should only appear for truly urgent issues.
    </Warning>
  </Tab>

  <Tab title="Passive">
    ### Passive notifications

    **Purpose**: Inform users without demanding immediate action

    **Characteristics**:

    * Less intrusive (toast, badge, or inbox)
    * Can be checked later
    * Auto-dismiss or remain until acknowledged

    **Pattern**: `[What happened]. [Context].`

    **Examples**:

    * "New comment on your post"
    * "Report exported. Download ready."
    * "3 new messages from Sarah"
    * "Backup completed successfully"

    <Tip>
      Most notifications should be passive. Users appreciate staying informed without constant interruption.
    </Tip>
  </Tab>
</Tabs>

## Format guidelines

<Steps>
  <Step title="Start with a verb or noun">
    Lead with what happened, not filler words.

    * **Good**: "New message from Sarah"
    * **Avoid**: "You have a new message from Sarah"
  </Step>

  <Step title="Be specific">
    Tell users exactly what happened.

    * **Good**: "3 files uploaded successfully"
    * **Avoid**: "Upload complete"
  </Step>

  <Step title="Keep titles under 50 characters">
    Titles often get truncated on mobile.

    * **Good**: "Payment failed"
    * **Avoid**: "We were unable to process your payment at this time"
  </Step>

  <Step title="Add context in description">
    Use the optional description for details.

    **Title**: "Report generated"

    **Description**: "Q4 sales report is ready to download"
  </Step>
</Steps>

## Examples by context

### System notifications

<Accordion title="Updates and maintenance">
  * "Update available. Install version 2.0 for new features."
  * "Maintenance scheduled. Site will be offline Sunday 2-4am."
  * "Update required. This version is no longer supported."
</Accordion>

<Accordion title="Background processes">
  * "Export complete. Download your file."
  * "Sync finished. All changes saved to cloud."
  * "Backup completed successfully"
</Accordion>

<Accordion title="Errors and issues">
  * "Connection lost. Trying to reconnect..."
  * "Upload failed. File too large. Max 10MB."
  * "Payment failed. Update your payment method."
</Accordion>

### Social notifications

<Accordion title="Activity updates">
  * "New comment on 'Q4 Planning'"
  * "Sarah mentioned you in a comment"
  * "5 new reactions to your post"
</Accordion>

<Accordion title="Invitations and requests">
  * "Team invitation from Acme Corp"
  * "Sarah requested access to 'Budget 2024'"
  * "New follower: Alex Chen"
</Accordion>

### Transactional notifications

<Accordion title="Order and shipping">
  * "Order confirmed. Arriving March 15."
  * "Package shipped. Track your delivery."
  * "Delivered to front door"
</Accordion>

<Accordion title="Account and billing">
  * "Payment received. Receipt sent to email."
  * "Subscription renewed for \$9.99/month"
  * "Card expiring soon. Update payment method."
</Accordion>

## Timing and frequency

### When to send

<CardGroup cols={2}>
  <Card title="Send immediately" icon="bolt">
    * Security alerts
    * Payment failures
    * Error conditions
    * Direct messages
  </Card>

  <Card title="Batch or delay" icon="clock">
    * Social activity (likes, follows)
    * Non-urgent updates
    * Marketing messages
    * Daily summaries
  </Card>
</CardGroup>

### Respect notification preferences

<Note>
  Always provide granular notification settings. Users should control:

  * Which events trigger notifications
  * How they're notified (push, email, in-app)
  * Frequency (immediate, hourly, daily digest)
</Note>

## Notification anatomy

### Mobile push notification

```
Title: New comment on your post
Body: Sarah: "Great idea! Let's discuss tomorrow."
Action: View comment
```

### Desktop notification

```
Title: Export complete
Body: Q4_sales_report.csv is ready to download
Actions: [Download] [Dismiss]
```

### In-app banner

```
Icon: [Warning icon]
Title: Session expiring soon
Body: You'll be logged out in 2 minutes due to inactivity.
Actions: [Stay logged in] [Log out now]
```

## Before and after examples

### Example 1: Update notification

<Accordion title="❌ Before">
  "An update is available for your application. Please install it to continue using the latest features and improvements."

  **Problems**:

  * Too long (19 words)
  * Passive voice ("is available")
  * Unclear importance (is it required?)
</Accordion>

<Accordion title="✅ After">
  **Title**: "Update available"

  **Body**: "Install version 2.0 for new features"

  **Action**: \[Update now]

  **Why it works**:

  * Concise title (2 words)
  * Clear benefit (new features)
  * Optional (not required)
</Accordion>

### Example 2: Activity notification

<Accordion title="❌ Before">
  "You have received a new notification. Sarah Johnson has left a comment on your post titled 'Q4 Planning Notes'."

  **Problems**:

  * Redundant ("received a notification")
  * Too much detail in title
  * Full name unnecessary
</Accordion>

<Accordion title="✅ After">
  **Title**: "New comment on 'Q4 Planning'"

  **Body**: "Sarah: 'Great idea! Let's discuss.'"

  **Why it works**:

  * Gets to the point
  * Shows preview of comment
  * First name sufficient
</Accordion>

### Example 3: Error notification

<Accordion title="❌ Before">
  "Error: Something went wrong. Please try again."

  **Problems**:

  * Vague ("something went wrong")
  * No context about what failed
  * No specific recovery action
</Accordion>

<Accordion title="✅ After">
  **Title**: "Upload failed"

  **Body**: "File too large. Maximum 10MB."

  **Action**: \[Choose smaller file]

  **Why it works**:

  * Specific about what failed
  * Explains why (too large)
  * States the limit (10MB)
</Accordion>

## Tone by urgency

### Critical (immediate action needed)

Serious, clear, directive:

* "Payment failed. Update payment method now."
* "Security alert. Password changed from new device."
* "Session expired. Log in to continue."

### Important (action needed soon)

Direct but not alarming:

* "Update available. Install by March 15."
* "Card expiring soon. Update payment method."
* "Response needed. Review invitation from Acme Corp."

### Informational (no action needed)

Neutral, brief:

* "Backup completed successfully"
* "Report exported to Downloads"
* "Changes saved"

### Social (low priority)

Friendly, casual:

* "New comment from Sarah"
* "Alex liked your post"
* "5 new followers this week"

## Accessibility

<Check>Use clear, descriptive titles (not just "Notification")</Check>
<Check>Don't rely on icons alone - include text</Check>
<Check>Ensure sufficient color contrast for notification badges</Check>
<Check>Make notifications dismissible and keyboard accessible</Check>
<Check>Provide text alternatives for sound/vibration alerts</Check>

## Quick checklist

Before shipping a notification:

* [ ] Title clearly states what happened
* [ ] Under 50 characters for title
* [ ] Specific, not vague ("Export complete" vs "Success")
* [ ] Appropriate urgency level
* [ ] Actionable when action is needed
* [ ] Respects user's notification preferences
* [ ] Works without icons or color alone

## Related resources

<CardGroup cols={3}>
  <Card title="Error messages" icon="triangle-exclamation" href="/guides/error-messages">
    Write error notifications
  </Card>

  <Card title="Success messages" icon="check" href="/guides/success-messages">
    Craft success notifications
  </Card>

  <Card title="Voice and tone" icon="comments" href="/concepts/voice-and-tone">
    Match tone to context
  </Card>
</CardGroup>