Skip to content

STD-UX-004: Toast Notification System

1. Context

Toast notifications are critical for non-blocking feedback during transacting. To prevent "Visual Noise" and maintain "Cinematic Consistency," this standard defines the physical, mechanical, and thematic behavior of the Unified Toast Handler.

2. The Standard

A. Physical Properties

  • Position: Fixed top-6 right-6.
  • Width: Standard 400px (desktop), full-width - 2rem (mobile).
  • Layering: z-index: 100 (above all Modals/Overlays).

B. Cinematic Motion (The "Directional Standard")

  • Physical Consistency: Toasts MUST exit in the same direction they entered (Right-In, Right-Out) to preserve the "Drawer" mental model.
  • Entrance: Horizontal slide along the X-axis from the right edge.
  • Initial: opacity: 0, x: 60px, scale: 0.9
  • Animate: opacity: 1, x: 0, scale: 1
  • Exit: Horizontal recession back to the right edge (the "Return Path").
  • Exit: opacity: 0, x: 60px, scale: 0.9
  • Vertical Stacking: New toasts enter from the top, pushing existing toasts DOWN (Top-Down Flow).

C. Severity-Aware Theming

All toasts MUST follow the severity-based neon border system to communicate urgency at a glance.

Message Type Border Color Accent Glow Background
Success Emerald-500/30 Emerald-500 #050505/95
Error Red-500/30 Red-500 #050505/95
Warning Amber-500/30 Amber-500 #050505/95
Info Vertical-Specific Vertical-Specific #050505/95

D. Context Awareness (The Vertical Rule)

"Info" toasts are context-sensitive. They should not use generic colors but must inherit the active vertical's primary gradient (e.g., Financial Emerald, Community Blue) to reinforce the user's current transactional domain.

3. Implementation Patterns

Standard Toast Call

const { showToast } = useToast();

// Severity examples
showToast("Record saved successfully", "success");
showToast("Transaction failed: Insufficient permissions", "error");

// Vertical-aware info example
showToast("New ledger entry detected", "info"); // Uses active vertical's neon glow

4. Hierarchy & Persistence

  • Multiple Toasts: Should stack vertically with popLayout transitions.
  • Auto-Dismiss: Success/Info toasts dismiss after 4 seconds. Errors and critical Warnings should remain until acknowledged or used with a 6-second timeout.

5. Version History

Version Date Author Change
1.0 2026-01-26 Antigravity Initial Comprehensive Toast Standard

Version History

Version Date Author Change
0.1.0 2026-01-26 Antigravity Initial Audit & Metadata Injection