@usefragments/ui 1.6.0 → 2.0.0

package/src/components/Toast/Toast.contract.json

@@ -1,9 +1,14 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Toast",
-  "description": "Brief, non-blocking notification messages",
+  "description": "Briefly reports what just happened, without blocking the page.",
   "category": "feedback",
-  "tags": ["notification", "alert", "message", "feedback"],
+  "tags": [
+    "notification",
+    "alert",
+    "message",
+    "feedback"
+  ],
   "status": "stable",
   "sourcePath": "src/components/Toast/index.tsx",
   "exportName": "Toast",
@@ -11,7 +16,7 @@
     "onDismiss: function",
     "title: string",
     "description: string",
-    "variant: default|success|error|warning|info (default: default)",
+    "tone: neutral|success|danger|warning|info (default: neutral)",
     "duration: number",
     "action: object",
     "id: string",
@@ -34,12 +39,18 @@
       "description": "Additional message content",
       "required": false
     },
-    "variant": {
+    "tone": {
       "type": "enum",
-      "description": "Visual variant indicating message type",
-      "default": "default",
+      "description": "Colour on the shared status ramp; neutral is the plain notification. The useToast().error helper sets tone=\"danger\".",
+      "default": "neutral",
       "required": false,
-      "values": ["default", "success", "error", "warning", "info"]
+      "values": [
+        "neutral",
+        "success",
+        "danger",
+        "warning",
+        "info"
+      ]
     },
     "duration": {
       "type": "number",
@@ -70,62 +81,52 @@
   },
   "usage": {
     "when": [
-      "Providing feedback after an action",
-      "Showing success/error status of operations",
-      "Non-critical information that doesn't require action",
-      "Temporary messages that auto-dismiss"
+      "Confirming an action landed",
+      "Reporting whether an operation worked",
+      "News the user does not have to act on",
+      "Messages that can disappear on their own"
     ],
     "whenNot": [
-      "Critical errors requiring user action (use Dialog)",
-      "Persistent information (use Alert)",
-      "Inline validation (use form error states)",
-      "System-wide announcements (use Banner)"
+      "Errors the user must resolve — use Dialog",
+      "Anything that must stay on screen — use Alert",
+      "Field-level validation — use form error states",
+      "Site-wide notices — use a banner"
     ],
     "guidelines": [
-      "Keep messages brief and actionable",
-      "Use appropriate variant for the message type",
-      "Auto-dismiss after reasonable duration (3-5s)",
-      "Allow manual dismissal for longer messages",
-      "Limit number of simultaneous toasts",
-      "useToast() variant helpers accept either (title, description?) or an options object for action/duration/id"
+      "One sentence, plus a title if it helps",
+      "Match the tone to what actually happened",
+      "Auto-dismiss in three to five seconds",
+      "Anything with an action needs a manual dismiss too",
+      "Two or three on screen at once, no more",
+      "useToast() helpers take (title, description) or an options object for action, duration, and id"
     ],
     "accessibility": [
-      "Use role=\"alert\" for important messages",
-      "Ensure sufficient display time for reading",
-      "Don't rely solely on color for meaning",
-      "Provide dismiss button with accessible label"
+      "role=\"alert\" for anything the user must not miss",
+      "Leave enough time to read it",
+      "Never let colour be the only signal",
+      "Give the dismiss button a real label"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Interactive toast demo - click buttons to trigger toasts (includes helper object syntax example)",
-      "code": "<ToastDemoWrapper />"
-    },
-    {
-      "name": "Success",
-      "description": "Success message variant",
-      "code": "<Toast\n  title=\"Success!\"\n  description=\"Your changes have been saved.\"\n  variant=\"success\"\n/>"
-    },
-    {
-      "name": "Error",
-      "description": "Error message variant",
-      "code": "<Toast\n  title=\"Error\"\n  description=\"Failed to save changes. Please try again.\"\n  variant=\"error\"\n/>"
+      "description": "Neutral message with a title and one line under it.",
+      "code": "<Toast\n  title=\"Draft saved\"\n  description=\"We will keep it until you publish.\"\n/>"
     },
     {
-      "name": "Warning",
-      "description": "Warning message variant",
-      "code": "<Toast\n  title=\"Warning\"\n  description=\"This action cannot be undone.\"\n  variant=\"warning\"\n/>"
+      "name": "Tones",
+      "description": "Icon and colour together carry the outcome.",
+      "code": "import { Stack } from '@/components/Stack';\n\n<Stack direction=\"column\" gap=\"sm\">\n  <Toast\n    title=\"Success!\"\n    description=\"Your changes have been saved.\"\n    tone=\"success\"\n  />\n  <Toast\n    title=\"Error\"\n    description=\"Failed to save changes. Please try again.\"\n    tone=\"danger\"\n  />\n  <Toast\n    title=\"Warning\"\n    description=\"This action cannot be undone.\"\n    tone=\"warning\"\n  />\n  <Toast\n    title=\"New update\"\n    description=\"Version 2.0 is now available.\"\n    tone=\"info\"\n  />\n</Stack>"
     },
     {
-      "name": "Info",
-      "description": "Informational message variant",
-      "code": "<Toast\n  title=\"New Update\"\n  description=\"Version 2.0 is now available.\"\n  variant=\"info\"\n/>"
+      "name": "With Action",
+      "description": "One-tap way back from something destructive.",
+      "code": "<Toast\n  title=\"File deleted\"\n  description=\"The file has been moved to trash.\"\n  action={{\n    label: 'Undo',\n    onClick: () => {},\n  }}\n/>"
     },
     {
-      "name": "With Action",
-      "description": "Toast with an action button",
-      "code": "<Toast\n  title=\"File deleted\"\n  description=\"The file has been moved to trash.\"\n  action={{\n    label: 'Undo',\n    onClick: () => console.log('Undo clicked'),\n  }}\n/>"
+      "name": "Dismissible",
+      "description": "onDismiss adds a close button for longer messages.",
+      "code": "<Toast\n  title=\"Export running\"\n  description=\"We will email you when the file is ready.\"\n  tone=\"info\"\n  onDismiss={() => {}}\n/>"
     }
   ],
   "relations": [
@@ -144,17 +145,22 @@
     "propsSummary": [
       "title: string - toast title",
       "description: string - additional message",
-      "variant: default|success|error|warning|info",
+      "tone: neutral|success|danger|warning|info",
       "duration: number - ms before auto-dismiss",
       "action: { label, onClick } - optional action",
       "ToastInput (useToast): optional id for deterministic creation/replacement flows",
       "useToast().success/error/warning/info: (title, description?) or ({ title, description, action, duration, id })"
     ],
-    "a11yRules": ["A11Y_ALERT_ROLE", "A11Y_TARGET_SIZE_MIN"]
+    "a11yRules": [
+      "A11Y_ALERT_ROLE",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": ["Provider"]
+    "subComponents": [
+      "Provider"
+    ]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Toast/Toast.module.scss

@@ -1,22 +1,23 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/feedback" as feedback;
 
 .container {
   position: fixed;
-  z-index: var(--fui-feedback-toast-layer, 70);
+  z-index: var(--fui-overlay-layer-toast, #{$fui-overlay-layer-toast});
   display: flex;
   flex-direction: column;
-  gap: var(--fui-feedback-stack-gap, var(--fui-raw-space-8, 8px));
+  gap: var(--fui-raw-space-8, #{measurements.raw-space(8)});
   inline-size: min(
-    var(--fui-feedback-toast-max-inline, 400px),
+    var(--fui-overlay-popover-md, #{measurements.target-value("overlay", "popover-md")}),
     calc(
       100% - var(
           --fui-feedback-viewport-inset-left,
-          max(var(--fui-raw-space-16, 16px), env(safe-area-inset-left))
+          max(var(--fui-raw-space-16, #{measurements.raw-space(16)}), env(safe-area-inset-left))
         ) - var(
           --fui-feedback-viewport-inset-right,
-          max(var(--fui-raw-space-16, 16px), env(safe-area-inset-right))
+          max(var(--fui-raw-space-16, #{measurements.raw-space(16)}), env(safe-area-inset-right))
         )
     )
   );
@@ -53,10 +54,17 @@
 
 .toast {
   @include feedback.transient;
+  @include high-contrast-outline;
 
-  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  --_toast-tint: var(--fui-bg-elevated, #{$fui-bg-elevated});
+  --_toast-line: var(--fui-border, #{$fui-border});
+  --_toast-ink: var(--fui-text-primary, #{$fui-text-primary});
+  --_toast-ink-soft: var(--fui-text-secondary, #{$fui-text-secondary});
+
+  background-color: var(--_toast-tint, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--_toast-line, var(--fui-border, #{$fui-border}));
+  border-radius: var(--fui-radius-l1, $fui-radius-l1);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
   animation: toastEnter var(--fui-transition-normal, $fui-transition-normal);
 }
@@ -68,7 +76,7 @@
 @keyframes toastEnter {
   from {
     opacity: 0;
-    transform: translateY($fui-anim-offset-md) scale(0.96);
+    transform: translateY(var(--fui-anim-offset-md, #{$fui-anim-offset-md})) scale(0.95);
   }
 
   to {
@@ -77,64 +85,46 @@
   }
 }
 
-.default .icon {
-  color: var(--fui-text-secondary, $fui-text-secondary);
-}
-
-.success {
-  background: var(--fui-color-success-bg, $fui-color-success-bg);
-  border-color: var(--fui-color-success-border, $fui-color-success-border);
-
-  .title,
-  .description,
-  .icon {
-    color: var(--fui-color-success-text, $fui-color-success-text);
-  }
+// Tones paint wash, hairline and ink from the shared status ramp; the
+// description drops to the same ink so the toast reads as one tinted object.
+@mixin _tone($tone, $bg, $text, $border) {
+  --_toast-tint: var(--fui-color-#{$tone}-bg, #{$bg});
+  --_toast-line: var(--fui-color-#{$tone}-border, #{$border});
+  --_toast-ink: var(--fui-color-#{$tone}-text, #{$text});
+  --_toast-ink-soft: var(--fui-color-#{$tone}-text, #{$text});
 }
 
-.error {
-  background: var(--fui-color-danger-bg, $fui-color-danger-bg);
-  border-color: var(--fui-color-danger-border, $fui-color-danger-border);
-
-  .title,
-  .description,
-  .icon {
-    color: var(--fui-color-danger-text, $fui-color-danger-text);
-  }
+.toneSuccess {
+  @include _tone(
+    "success",
+    $fui-color-success-bg,
+    $fui-color-success-text,
+    $fui-color-success-border
+  );
 }
 
-.warning {
-  background: var(--fui-color-warning-bg, $fui-color-warning-bg);
-  border-color: var(--fui-color-warning-border, $fui-color-warning-border);
-
-  .title,
-  .description,
-  .icon {
-    color: var(--fui-color-warning-text, $fui-color-warning-text);
-  }
+.toneDanger {
+  @include _tone("danger", $fui-color-danger-bg, $fui-color-danger-text, $fui-color-danger-border);
 }
 
-.info {
-  background: var(--fui-color-info-bg, $fui-color-info-bg);
-  border-color: var(--fui-color-info-border, $fui-color-info-border);
-
-  .title,
-  .description,
-  .icon {
-    color: var(--fui-color-info-text, $fui-color-info-text);
-  }
+.toneWarning {
+  @include _tone(
+    "warning",
+    $fui-color-warning-bg,
+    $fui-color-warning-text,
+    $fui-color-warning-border
+  );
 }
 
-.success .description,
-.error .description,
-.warning .description,
-.info .description {
-  opacity: 0.8;
+.toneInfo {
+  @include _tone("info", $fui-color-info-bg, $fui-color-info-text, $fui-color-info-border);
 }
 
 .icon {
   @include feedback.icon;
 
+  color: var(--_toast-ink-soft, var(--fui-text-secondary, #{$fui-text-secondary}));
+
   svg {
     inline-size: 100%;
     block-size: 100%;
@@ -142,81 +132,36 @@
 }
 
 .toast:has(.description) .icon {
-  margin-block-start: var(--fui-stroke-hairline, 1px);
+  margin-block-start: var(--fui-stroke-hairline, #{$fui-stroke-hairline});
 }
 
 .content {
   display: grid;
   flex: 1;
-  gap: var(--fui-feedback-text-gap, var(--fui-raw-space-4, 4px));
+  gap: var(--fui-feedback-text-gap, var(--fui-raw-space-4, #{measurements.raw-space(4)}));
   min-inline-size: 0;
 }
 
 .title {
   @include feedback.title;
 
-  color: var(--fui-text-primary, $fui-text-primary);
+  color: var(--_toast-ink, var(--fui-text-primary, #{$fui-text-primary}));
 }
 
 .description {
   @include feedback.body;
 
-  color: var(--fui-text-secondary, $fui-text-secondary);
-}
-
-.action {
-  @include button-reset;
-  @include feedback.compact-action;
-
-  flex-shrink: 0;
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  color: var(--fui-color-accent, $fui-color-accent);
-  cursor: pointer;
-  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
-
-  &:hover {
-    background-color: var(--fui-bg-hover, $fui-bg-hover);
-  }
-
-  &:focus-visible {
-    @include focus-ring;
-  }
+  color: var(--_toast-ink-soft, var(--fui-text-secondary, #{$fui-text-secondary}));
 }
 
+// The action and close are kit buttons; only their placement lives here.
+.action,
 .close {
-  @include button-reset;
-  @include feedback.close;
-
   flex-shrink: 0;
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  color: var(--fui-text-tertiary, $fui-text-tertiary);
-  cursor: pointer;
-  transition:
-    background-color var(--fui-transition-fast, $fui-transition-fast),
-    color var(--fui-transition-fast, $fui-transition-fast);
-
-  svg {
-    inline-size: var(--_fui-action-icon-size);
-    block-size: var(--_fui-action-icon-size);
-  }
-
-  &:hover {
-    background-color: var(--fui-bg-hover, $fui-bg-hover);
-    color: var(--fui-text-secondary, $fui-text-secondary);
-  }
-
-  &:focus-visible {
-    @include focus-ring;
-  }
 }
 
 @media (prefers-reduced-motion: reduce) {
   .toast {
     animation: none;
   }
-
-  .action,
-  .close {
-    transition: none;
-  }
 }

package/src/components/Toast/index.tsx

@@ -1,13 +1,15 @@
 'use client';
 
-import * as React from 'react';
-import styles from './Toast.module.scss';
+import * as React from "react";
+import { Button } from "../Button";
+import { IconButton } from "../IconButton";
+import styles from "./Toast.module.scss";
 
 // ============================================
 // Types
 // ============================================
 
-export type ToastVariant = 'default' | 'success' | 'error' | 'warning' | 'info';
+export type ToastTone = "neutral" | "success" | "danger" | "warning" | "info";
 export type ToastPosition =
   | 'top-left'
   | 'top-center'
@@ -20,7 +22,8 @@ export interface ToastData {
   id: string;
   title?: string;
   description?: string;
-  variant?: ToastVariant;
+  /** Colour. `neutral` is the plain notification; the semantic tones paint the shared status ramp. */
+  tone?: ToastTone;
   duration?: number;
   action?: {
     label: string;
@@ -76,21 +79,22 @@ export function useToast() {
     return context.addToast(options);
   }, [context]);
 
-  const makeVariantHelper = React.useCallback(
-    (variant: ToastVariant) =>
-      (titleOrOptions: string | Omit<ToastInput, 'variant'>, description?: string) => {
-        if (typeof titleOrOptions === 'string') {
-          return context.addToast({ title: titleOrOptions, description, variant });
+  const makeToneHelper = React.useCallback(
+    (tone: ToastTone) =>
+      (titleOrOptions: string | Omit<ToastInput, "tone">, description?: string) => {
+        if (typeof titleOrOptions === "string") {
+          return context.addToast({ title: titleOrOptions, description, tone });
         }
-        return context.addToast({ ...titleOrOptions, variant });
+        return context.addToast({ ...titleOrOptions, tone });
       },
     [context]
   );
 
-  const success = React.useMemo(() => makeVariantHelper('success'), [makeVariantHelper]);
-  const error = React.useMemo(() => makeVariantHelper('error'), [makeVariantHelper]);
-  const warning = React.useMemo(() => makeVariantHelper('warning'), [makeVariantHelper]);
-  const info = React.useMemo(() => makeVariantHelper('info'), [makeVariantHelper]);
+  const success = React.useMemo(() => makeToneHelper("success"), [makeToneHelper]);
+  // Keeps its name; the field it sets is `tone: "danger"`.
+  const error = React.useMemo(() => makeToneHelper("danger"), [makeToneHelper]);
+  const warning = React.useMemo(() => makeToneHelper("warning"), [makeToneHelper]);
+  const info = React.useMemo(() => makeToneHelper("info"), [makeToneHelper]);
 
   return {
     toast,
@@ -155,14 +159,22 @@ function CloseIcon() {
   );
 }
 
-const variantIcons: Record<ToastVariant, React.ComponentType | null> = {
-  default: null,
+const toneIcons: Record<ToastTone, React.ComponentType | null> = {
+  neutral: null,
   success: SuccessIcon,
-  error: ErrorIcon,
+  danger: ErrorIcon,
   warning: WarningIcon,
   info: InfoIcon,
 };
 
+const TONE_CLASS: Record<ToastTone, string | undefined> = {
+  neutral: undefined,
+  success: styles.toneSuccess,
+  danger: styles.toneDanger,
+  warning: styles.toneWarning,
+  info: styles.toneInfo,
+};
+
 // ============================================
 // Toast Component
 // ============================================
@@ -171,7 +183,7 @@ function ToastItem({
   id,
   title,
   description,
-  variant = 'default',
+  tone = "neutral",
   action,
   onDismiss,
   onPause,
@@ -183,18 +195,14 @@ function ToastItem({
   onPause?: () => void;
   onResume?: () => void;
 }) {
-  const Icon = variantIcons[variant];
+  const Icon = toneIcons[tone];
   const uniqueId = React.useId();
   const toastRef = React.useRef<HTMLDivElement>(null);
   const titleId = title ? `toast-title-${id || uniqueId}` : undefined;
   const descId = description ? `toast-desc-${id || uniqueId}` : undefined;
-  const liveRole = variant === 'error' || variant === 'warning' ? 'alert' : 'status';
+  const liveRole = tone === "danger" || tone === "warning" ? "alert" : "status";
 
-  const toastClasses = [
-    styles.toast,
-    styles[variant],
-    className,
-  ].filter(Boolean).join(' ');
+  const toastClasses = [styles.toast, TONE_CLASS[tone], className].filter(Boolean).join(" ");
 
   return (
     <div
@@ -232,23 +240,20 @@ function ToastItem({
         {description && <div id={descId} className={styles.description}>{description}</div>}
       </div>
       {action && (
-        <button
-          type="button"
-          className={styles.action}
-          onClick={action.onClick}
-        >
+        <Button variant="link" size="sm" className={styles.action} onClick={action.onClick}>
           {action.label}
-        </button>
+        </Button>
       )}
       {onDismiss && (
-        <button
-          type="button"
+        <IconButton
+          variant="ghost"
+          size="sm"
           className={styles.close}
           onClick={onDismiss}
           aria-label="Dismiss notification"
         >
           <CloseIcon />
-        </button>
+        </IconButton>
       )}
     </div>
   );