Skip to content

ericrisco/rsc-harness / skills/ux

Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).

FileKindSize
SKILL.mdskill md9.3 KB
THIRD_PARTY.mdmarkdown1.6 KB
evals/cases.yamlconfig2.5 KB
references/flows.mdmarkdown7.3 KB
upstream/UPSTREAM.jsonconfig4.7 KB
upstream/ux-designer/GUIDE.mdmarkdown15.2 KB
upstream/ux-designer/LICENSEother1.0 KB
upstream/ux-designer/references/01-core-principles.mdmarkdown7.9 KB
upstream/ux-designer/references/02-laws-of-ux.mdmarkdown8.3 KB
upstream/ux-designer/references/03-accessibility.mdmarkdown10.7 KB
upstream/ux-designer/references/04-visual-design.mdmarkdown8.9 KB
upstream/ux-designer/references/05-information-architecture.mdmarkdown9.1 KB
upstream/ux-designer/references/06-interaction-design.mdmarkdown11.2 KB
upstream/ux-designer/references/07-forms-and-inputs.mdmarkdown11.4 KB
upstream/ux-designer/references/08-mobile-ux.mdmarkdown10.9 KB
upstream/ux-designer/references/09-ux-writing.mdmarkdown9.0 KB
upstream/ux-designer/references/10-user-research.mdmarkdown10.6 KB
upstream/ux-designer/references/11-design-systems.mdmarkdown13.2 KB
upstream/ux-designer/references/12a-presence-awareness.mdmarkdown10.2 KB
upstream/ux-designer/references/12b-conflict-resolution-sync.mdmarkdown15.8 KB
upstream/ux-designer/references/13a-canvas-navigation.mdmarkdown9.5 KB
upstream/ux-designer/references/13b-canvas-objects-performance.mdmarkdown14.2 KB
upstream/ux-designer/references/14-ai-ux-patterns.mdmarkdown20.9 KB
upstream/ux-designer/references/15-ethical-design.mdmarkdown13.9 KB
upstream/ux-designer/references/16-onboarding.mdmarkdown16.5 KB
upstream/ux-designer/references/17-notifications.mdmarkdown17.7 KB
upstream/ux-designer/references/18-data-visualization.mdmarkdown18.8 KB
upstream/ux-designer/references/19-search-ux.mdmarkdown19.0 KB
upstream/ux-designer/references/20-emotional-design.mdmarkdown14.5 KB
upstream/ux-designer/references/21-data-tables.mdmarkdown20.5 KB
upstream/ux-designer/references/22-performance-ux.mdmarkdown17.5 KB
upstream/ux-designer/references/23-internationalization.mdmarkdown15.4 KB
upstream/ux-designer/references/24-voice-and-multimodal.mdmarkdown15.9 KB
upstream/ux-designer/references/25a-barcode-camera-scanning.mdmarkdown21.3 KB
upstream/ux-designer/references/25b-barcode-scanner-workflows.mdmarkdown25.3 KB
upstream/ux-designer/references/25c-barcode-display.mdmarkdown17.3 KB
upstream/ux-usability-foundations/GUIDE.mdmarkdown16.0 KB
upstream/ux-usability-foundations/LICENSEother1.0 KB
upstream/ux-usability-foundations/references/anti-patterns.mdmarkdown8.3 KB
upstream/ux-usability-foundations/references/checklists.mdmarkdown6.2 KB
upstream/ux-usability-foundations/references/decision-prompts.mdmarkdown10.0 KB
upstream/ux-usability-foundations/references/principle-cards.mdmarkdown15.4 KB

upstream/ux-designer/references/17-notifications.md

View on GitHub
# Notification & Attention Design

Notifications are a cross-cutting concern that affects every product. This reference covers notification types, delivery channels, attention management, and permission patterns for responsible notification design.

---

## Contents

- Notification Types
- Severity & Visual Hierarchy
- Delivery Channels
- Notification Center
- Attention Management
- Permission Requests
- Key Metrics
- Anti-Patterns
- Sources

---

## Notification Types

### By Purpose

| Type | Description | Priority | Example |
|------|-------------|----------|---------|
| **Transactional** | Result of a user action | High | "Order confirmed", "Payment received" |
| **Informational** | System updates or status | Medium | "Maintenance scheduled", "Export ready" |
| **Social** | Activity from other users | Medium | "Alex commented on your post" |
| **Promotional** | Marketing or upsell | Low | "Try our new feature", "Upgrade plan" |
| **Alert** | Urgent system or security | Critical | "Unusual sign-in detected", "Server down" |

### By Urgency

```
Critical   ████████████  Requires immediate action (security, data loss)
High       █████████░░░  Important, time-sensitive (mentions, assignments)
Medium     ██████░░░░░░  Relevant but not urgent (comments, updates)
Low        ███░░░░░░░░░  Nice to know (tips, promotions)
Info       █░░░░░░░░░░░  Background context (changelog, analytics)
```

---

## Severity & Visual Hierarchy

### Standard Severity Levels

```css
/* Critical — Blocking issue, requires immediate attention */
.alert-critical {
  background: #fef2f2;
  border-left: 4px solid #dc2626;
  color: #991b1b;
}

/* Warning — Potential issue, user should be aware */
.alert-warning {
  background: #fffbeb;
  border-left: 4px solid #f59e0b;
  color: #92400e;
}

/* Success — Positive confirmation */
.alert-success {
  background: #f0fdf4;
  border-left: 4px solid #16a34a;
  color: #166534;
}

/* Info — Neutral information */
.alert-info {
  background: #eff6ff;
  border-left: 4px solid #3b82f6;
  color: #1e40af;
}
```

### Visual Priority

| Element | Critical | Warning | Info | Success |
|---------|----------|---------|------|---------|
| Icon | ⛔ / 🔴 | ⚠️ / 🟡 | ℹ️ / 🔵 | ✅ / 🟢 |
| Color | Red | Yellow/Amber | Blue | Green |
| Position | Modal/top banner | Top banner | Inline/toast | Toast |
| Sound | Optional alert | None | None | None |
| Persistence | Until resolved | Until dismissed | Auto-dismiss | Auto-dismiss |

---

## Delivery Channels

### Channel Selection Guide

```
                   Urgency
                High ──────────── Low
              │                        │
  Sync        │  Modal      Banner     │
  (blocking)  │  Alert      Inline     │
              │                        │
              │  Push        Email     │
  Async       │  Toast       Badge    │
  (non-block) │  SMS      In-app feed │
              │                        │
```

### In-App Notifications

#### Banners (Persistent)

```
┌───────────────────────────────────────────────────┐
│ ⚠️ Your trial expires in 3 days. [Upgrade now] [✕] │
└───────────────────────────────────────────────────┘
┌─────────────────── Page Content ──────────────────┐
```

- Fixed at top or bottom of viewport
- Persist until dismissed or condition resolved
- Use for: system-wide announcements, degraded service, account alerts
- Include clear action button and dismiss option
- Maximum 1-2 banners visible at a time

#### Toasts / Snackbars

```
                              ┌──────────────────────────┐
                              │ ✅ Document saved         │
                              │            [Undo] [✕]    │
                              └──────────────────────────┘
```

**Duration guidelines:**
- Short messages (no action): 4 seconds
- Messages with action button: 6-8 seconds
- Error messages: 8-10 seconds or until dismissed
- Never auto-dismiss critical errors

**Placement:**
- Bottom-center or bottom-right (most common)
- Top-center for important alerts
- Consistent position throughout the app
- Away from primary interaction areas

**Stacking:**
```
┌──────────────────────────────┐
│ ✅ File uploaded              │  ← newest
└──────────────────────────────┘
┌──────────────────────────────┐
│ ℹ️ 2 team members online     │  ← older
└──────────────────────────────┘

Max stack: 3 toasts visible
Older toasts slide out or collapse
```

- Stack newest on top
- Maximum 3 visible at once
- Older toasts auto-dismiss to make room
- All toasts dismissible with close button or swipe

#### Badges

```
┌────────────────────────────────────────┐
│  [🔔 3]  [📨 12]  [👤]                │
└────────────────────────────────────────┘
```

**Design rules:**
- Numeric badge: 1-99, then "99+" for overflow
- Dot badge: for "something new" without specific count
- Position: top-right of the icon
- Color: red for requiring attention, blue/gray for informational
- Clear on interaction (opening the relevant section)
- Animate on increment (subtle scale pulse)

#### Modals / Dialogs

Reserve for critical interruptions that require immediate user decision.

```
┌─────────────────────────────────────────┐
│  ⚠️ Unsaved Changes                     │
│                                          │
│  You have unsaved changes that will be   │
│  lost if you leave this page.            │
│                                          │
│  [Discard Changes]  [Save & Continue]    │
└──────────────────────────────────────────┘
```

- Only for actions that require a decision
- Never for informational messages (use toast/banner instead)
- Always provide a clear way to dismiss (Esc, close button, outside click)
- Maximum 1 modal at a time (never stack modals)
- Include a clear primary action

#### Inline Notifications

```
┌─────────────────────────────────────────┐
│  Email: [user@example.com          ]    │
│  ⚠️ This email is already in use.       │
│     [Sign in instead?]                  │
└─────────────────────────────────────────┘
```

- Placed directly next to the relevant content
- Contextual and specific to the user's action
- Best for: form validation, field-level errors, contextual tips
- Don't require dismissal (disappear when issue is resolved)

### External Channels

#### Push Notifications

```
┌─────────────────────────────────────────┐
│ 🔔 AppName                     now      │
│ Alex commented on "Q4 Report"           │
│ "Great analysis! Can we discuss the..." │
└─────────────────────────────────────────┘
```

- Ask permission contextually (not on first visit)
- Group related notifications (3+ from same thread → summary)
- Deep-link to the relevant content
- Rich notifications: image previews, action buttons
- Respect quiet hours (system settings or app-level)

#### Email Notifications

- Batch non-urgent notifications (daily/weekly digest)
- Include unsubscribe link in every email (CAN-SPAM, GDPR)
- One-click unsubscribe header (RFC 8058)
- Clear sender name and subject line
- Deep-link to specific content in the app

---

## Notification Center

### Inbox Pattern

```
┌─ Notifications ─────────────────────────┐
│  [All] [Unread (5)] [Mentions]          │
│                                          │
│  Today                                   │
│  ┌────────────────────────────────────┐  │
│  │ 🔵 Alex commented on "Q4 Report"  │  │
│  │    "Looks great! One question..."  │  │
│  │    2 hours ago            [···]    │  │
│  ├────────────────────────────────────┤  │
│  │ 🔵 Build #142 passed              │  │
│  │    main branch — all tests green   │  │
│  │    3 hours ago            [···]    │  │
│  ├────────────────────────────────────┤  │
│  │    Sarah shared "Design Brief"     │  │
│  │    5 hours ago            [···]    │  │
│  └────────────────────────────────────┘  │
│                                          │
│  Yesterday                               │
│  ┌────────────────────────────────────┐  │
│  │    Invoice #1234 paid              │  │
│  │    Yesterday at 4:32 PM   [···]    │  │
│  └────────────────────────────────────┘  │
│                                          │
│  [Mark all as read]                      │
└──────────────────────────────────────────┘
```

**Features:**
- Read/unread visual distinction (dot, bold, background color)
- Grouping by time (Today, Yesterday, This week, Older)
- Filter tabs (All, Unread, Mentions, specific categories)
- Bulk actions: mark all as read, clear all
- Individual actions: mark read/unread, mute thread, delete
- Clicking notification navigates to relevant content
- Infinite scroll with loading states
- "You're all caught up" message when empty

---

## Attention Management

### Interruption Budget

Not all notifications deserve equal interruption.

```
Daily interruption budget (suggested maximums):
├── Critical alerts: No limit (safety/security)
├── High-priority (mentions, assignments): 10-15
├── Medium (comments, updates): Batched 2-3x/day
├── Low (tips, promotions): 1/day maximum
└── Passive (badges, feed): Zero interruption
```

### Do Not Disturb

```
┌─ Focus Mode ────────────────────────────┐
│                                          │
│  [🔕 Do Not Disturb]  Until: [1 hour ▾] │
│                                          │
│  Allow through:                          │
│  [✓] Direct mentions                    │
│  [✓] Critical system alerts             │
│  [ ] Comments on my items               │
│  [ ] Team updates                        │
│                                          │
│  Schedule:                               │
│  [ ] Auto-enable outside work hours      │
│      Work hours: [9:00] - [17:00]        │
│                                          │
│  [Save]                                  │
└──────────────────────────────────────────┘
```

### Notification Preferences

```
┌─ Notification Settings ─────────────────┐
│                                          │
│  Channel          In-app  Push   Email   │
│  ─────────────────────────────────────── │
│  Mentions          ✓      ✓      ✓      │
│  Comments          ✓      ✓      ○      │
│  Updates           ✓      ○      ○      │
│  Marketing         ○      ○      ○      │
│                                          │
│  ✓ = enabled  ○ = disabled               │
│                                          │
│  Email digest: [Weekly ▾]                │
│                                          │
│  [Save preferences]                      │
└──────────────────────────────────────────┘
```

- Per-category, per-channel control
- Sensible defaults (not everything on)
- Email digest option for batching
- Quick "mute all" toggle
- Accessible from notification center and settings

### Batching & Grouping

```
Instead of 5 separate notifications:
  "Alex commented on Project X"
  "Alex commented on Project X"
  "Sarah commented on Project X"
  "Alex commented on Project X"
  "Jordan commented on Project X"

Send 1 grouped notification:
  "4 new comments on Project X from Alex, Sarah, and Jordan"
```

- Group by thread/topic, not by user
- Show count and participant summary
- Batch non-urgent notifications (5-15 minute window)
- Expand to individual items on click

---

## Permission Requests

### Just-in-Time Permissions

```
❌ On first visit:
"AppName wants to send you notifications"
[Don't Allow]  [Allow]

✅ In context, when relevant:
┌─────────────────────────────────────────┐
│  Want to know when someone replies?     │
│                                         │
│  Get notified when team members         │
│  respond to your comments.              │
│                                         │
│  [Enable Notifications]  [Not now]      │
└─────────────────────────────────────────┘
→ Then triggers the browser permission prompt
```

### Pre-Permission Pattern

Before triggering the system permission dialog:

1. **Explain value**: Why the user benefits from this permission
2. **Show in context**: When the permission is relevant to what they're doing
3. **Custom prompt first**: Your own UI before the system dialog
4. **Respect "not now"**: Don't ask again for at least 30 days
5. **Never on first visit**: Wait until user has experienced product value

### Permission Denied Recovery

```
When user denied permission:
┌─────────────────────────────────────────┐
│  ℹ️ Notifications are disabled           │
│                                          │
│  To enable notifications:               │
│  1. Click the lock icon in your browser │
│  2. Find "Notifications"               │
│  3. Change to "Allow"                   │
│                                          │
│  [Show me how]                           │
└─────────────────────────────────────────┘
```

- Provide clear instructions to re-enable in browser/OS settings
- Don't repeatedly nag about denied permissions
- Offer email as a fallback channel
- Show relevant instructions per browser/platform

---

## Key Metrics

| Metric | Target | Context |
|--------|--------|---------|
| Push opt-in rate | > 50% | Permission acceptance |
| Notification open rate | > 15% | Push engagement |
| Email unsubscribe rate | < 0.5%/email | List health |
| Toast dismissal rate | Track | Too many = too noisy |
| Notification → action | > 25% | Relevance indicator |
| Permission ask timing | After activation | Not on first visit |
| DND usage | Monitor | High = too noisy overall |

---

## Anti-Patterns

1. **Permission on first visit** — Asking for push permission before user sees value
2. **Notification carpet bombing** — Sending every event as a push notification
3. **No notification preferences** — All-or-nothing notification control
4. **Stacking modals** — Multiple dialogs requiring sequential dismissal
5. **Auto-dismissing errors** — Critical errors that disappear before user reads them
6. **Same urgency for everything** — Treating promotions like security alerts
7. **No grouping** — 10 individual notifications for 10 comments on the same thread
8. **Notification-only features** — Actions only accessible through notification center
9. **Dark pattern nudging** — "You have 0 notifications" as a growth hack
10. **Ignoring quiet hours** — Sending push notifications at 3 AM

---

## Sources

- [Material Design: Notifications](https://m3.material.io/foundations/content-design/notifications) — Component patterns
- [Apple HIG: Notifications](https://developer.apple.com/design/human-interface-guidelines/notifications) — Platform guidelines
- [Nielsen Norman Group: Notification UX](https://www.nngroup.com/articles/push-notification/) — Research
- [Intercom: Notification Design](https://www.intercom.com/blog/) — SaaS patterns
- [Web Push Protocol](https://web.dev/articles/push-notifications-overview) — Technical implementation
- [RFC 8058](https://datatracker.ietf.org/doc/html/rfc8058) — One-click unsubscribe
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall