@usefragments/ui 1.5.4 → 1.7.0

package/src/components/ThinkingIndicator/ThinkingIndicator.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ThinkingIndicator",
-  "description": "Animated indicator showing AI is processing",
+  "description": "Shows that an AI response is being generated.",
   "category": "ai",
-  "tags": [
-    "thinking",
-    "loading",
-    "ai",
-    "processing",
-    "indicator",
-    "animation"
-  ],
+  "tags": ["thinking", "loading", "ai", "processing", "indicator", "animation"],
   "status": "stable",
   "sourcePath": "src/components/ThinkingIndicator/index.tsx",
   "exportName": "ThinkingIndicator",
@@ -39,11 +32,7 @@
       "description": "Animation style",
       "default": "dots",
       "required": false,
-      "values": [
-        "dots",
-        "pulse",
-        "spinner"
-      ]
+      "values": ["dots", "pulse", "spinner"]
     },
     "showElapsed": {
       "type": "boolean",
@@ -59,21 +48,21 @@
   },
   "usage": {
     "when": [
-      "AI is processing a request and generating a response",
-      "Need visual feedback during async AI operations",
-      "Want to show multi-step progress for complex AI tasks",
-      "Indicating streaming is about to begin"
+      "A model is working on a request",
+      "Async AI work that would otherwise look frozen",
+      "Multi-stage tasks worth showing stage by stage",
+      "The moment before streaming starts"
     ],
     "whenNot": [
-      "Simple loading states (use Progress or Skeleton)",
-      "Form submission loading (use Button loading state)",
-      "Page-level loading (use Progress or Skeleton)"
+      "Ordinary loading (use Progress or Skeleton)",
+      "Form submission (use the Button loading state)",
+      "Whole-page loading (use Progress or Skeleton)"
     ],
     "guidelines": [
-      "Use active prop to control visibility",
-      "Choose variant based on context (dots for chat, spinner for actions)",
-      "Enable showElapsed for longer operations",
-      "Use steps for multi-step AI workflows (tool calls, research)"
+      "active controls whether it shows at all",
+      "dots suits chat; spinner suits a discrete action",
+      "Turn on showElapsed once waits run past a few seconds",
+      "Use steps for tool calls, research, and other staged work"
     ],
     "accessibility": [
       "Uses role=\"status\" and aria-live=\"polite\"",
@@ -85,37 +74,37 @@
   "examples": [
     {
       "name": "Dots (Default)",
-      "description": "Bouncing dots animation",
+      "description": "Three dots bounce in sequence; the quietest option.",
       "code": "<ThinkingIndicator variant=\"dots\" label=\"Thinking...\" />"
     },
     {
       "name": "Pulse",
-      "description": "Pulsing ring animation",
+      "description": "A single ring breathes in place.",
       "code": "<ThinkingIndicator variant=\"pulse\" label=\"Processing...\" />"
     },
     {
       "name": "Spinner",
-      "description": "Rotating spinner animation",
+      "description": "A rotating arc, for work with a definite end.",
       "code": "<ThinkingIndicator variant=\"spinner\" label=\"Loading...\" />"
     },
     {
       "name": "With Elapsed Time",
-      "description": "Shows time since started",
+      "description": "A live counter reassures the reader during long waits.",
       "code": "<ThinkingIndicator\n  variant=\"dots\"\n  label=\"Generating response...\"\n  showElapsed\n/>"
     },
     {
       "name": "Multi-Step Progress",
-      "description": "Shows progress through multiple steps",
+      "description": "Finished, running, and queued stages read at a glance.",
       "code": "<ThinkingIndicator\n  variant=\"spinner\"\n  label=\"Working...\"\n  steps={[\n    { id: '1', label: 'Analyzing request', status: 'complete' },\n    { id: '2', label: 'Searching knowledge base', status: 'active' },\n    { id: '3', label: 'Generating response', status: 'pending' },\n  ]}\n/>"
     },
     {
       "name": "With Error Step",
-      "description": "Shows a step that encountered an error",
+      "description": "A failed stage turns red while the next one retries.",
       "code": "<ThinkingIndicator\n  variant=\"spinner\"\n  label=\"Retrying...\"\n  steps={[\n    { id: '1', label: 'Connecting to API', status: 'complete' },\n    { id: '2', label: 'Fetching data', status: 'error' },\n    { id: '3', label: 'Retrying with fallback', status: 'active' },\n  ]}\n/>"
     },
     {
       "name": "Custom Label",
-      "description": "Custom status text",
+      "description": "Name the actual task instead of a generic status.",
       "code": "<ThinkingIndicator\n  variant=\"dots\"\n  label=\"Claude is writing code...\"\n/>"
     }
   ],
@@ -144,17 +133,11 @@
       "showElapsed: boolean - show elapsed time",
       "steps: ThinkingStep[] - multi-step progress"
     ],
-    "a11yRules": [
-      "A11Y_ARIA_LIVE",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_ARIA_LIVE", "A11Y_MOTION_PREFERENCE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Steps",
-      "Step"
-    ]
+    "subComponents": ["Steps", "Step"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/ThinkingIndicator/ThinkingIndicator.module.scss

@@ -1,5 +1,7 @@
 @use "../../tokens/variables" as *;
-@use "../../tokens/mixins" as *;
+@use "../../recipes/layout" as layout;
+@use "../../recipes/representation" as representation;
+@use "../../recipes/typography" as typography;
 
 // ============================================
 // Thinking Indicator Root
@@ -8,25 +10,25 @@
 .thinkingIndicator {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("sm");
+  padding: layout.gap("sm");
 }
 
 .main {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("sm");
 }
 
 .label {
-  @include text-base;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include typography.role("body-compact");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
 }
 
 .elapsed {
-  @include helper-text;
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  @include typography.role("caption");
+
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   font-variant-numeric: tabular-nums;
 }
@@ -42,17 +44,18 @@
 .steps {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-1, $fui-space-1);
-  padding-left: var(--fui-space-4, $fui-space-4);
-  border-left: 2px solid var(--fui-border, $fui-border);
-  margin-left: var(--fui-space-1, $fui-space-1); // 7px — align with center of animation
+  gap: layout.gap("xs");
+  margin-inline-start: calc(representation.activity-size("sm") / 2);
+  padding-inline-start: layout.gap("lg");
+  border-inline-start: var(--fui-stroke-default, 2px) solid var(--fui-border, $fui-border);
 }
 
 .step {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  gap: layout.gap("sm");
+  @include typography.role("caption");
+
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
@@ -60,14 +63,16 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  width: var(--fui-icon-md, $fui-icon-md); // 16px
-  height: var(--fui-icon-md, $fui-icon-md);
-  flex-shrink: 0;
+  @include representation.glyph("md");
+
+  > svg {
+    @include representation.glyph("xs");
+  }
 }
 
 .stepDot {
-  width: 6px;
-  height: 6px;
+  inline-size: var(--fui-raw-space-8, 8px);
+  block-size: var(--fui-raw-space-8, 8px);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   background-color: var(--fui-text-tertiary, $fui-text-tertiary);
   opacity: 0.5;

package/src/components/ThinkingIndicator/index.tsx

@@ -1,15 +1,15 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './ThinkingIndicator.module.scss';
-import { Loading } from '../Loading';
+import * as React from "react";
+import styles from "./ThinkingIndicator.module.scss";
+import { Loading } from "../Loading";
 
 // ============================================
 // Types
 // ============================================
 
-export type ThinkingVariant = 'dots' | 'pulse' | 'spinner';
-export type StepStatus = 'pending' | 'active' | 'complete' | 'error';
+export type ThinkingVariant = "dots" | "pulse" | "spinner";
+export type StepStatus = "pending" | "active" | "complete" | "error";
 
 export interface ThinkingStep {
   id: string;
@@ -55,7 +55,9 @@ const ThinkingIndicatorContext = React.createContext<ThinkingIndicatorContextVal
 function useThinkingIndicatorContext() {
   const context = React.useContext(ThinkingIndicatorContext);
   if (!context) {
-    throw new Error('ThinkingIndicator compound components must be used within a ThinkingIndicator');
+    throw new Error(
+      "ThinkingIndicator compound components must be used within a ThinkingIndicator"
+    );
   }
   return context;
 }
@@ -82,7 +84,7 @@ function useElapsedTime(active: boolean): string {
     return () => clearInterval(interval);
   }, [active]);
 
-  if (elapsed < 1000) return '';
+  if (elapsed < 1000) return "";
 
   const seconds = Math.floor(elapsed / 1000);
   if (seconds < 60) return `${seconds}s`;
@@ -100,8 +102,6 @@ function CheckIcon() {
   return (
     <svg
       xmlns="http://www.w3.org/2000/svg"
-      width="12"
-      height="12"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -119,8 +119,6 @@ function ErrorIcon() {
   return (
     <svg
       xmlns="http://www.w3.org/2000/svg"
-      width="12"
-      height="12"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
@@ -140,7 +138,7 @@ function ErrorIcon() {
 // ============================================
 
 function ThinkingSteps({ children, className, ...htmlProps }: ThinkingStepsProps) {
-  const classes = [styles.steps, className].filter(Boolean).join(' ');
+  const classes = [styles.steps, className].filter(Boolean).join(" ");
 
   return (
     <div {...htmlProps} className={classes}>
@@ -149,25 +147,31 @@ function ThinkingSteps({ children, className, ...htmlProps }: ThinkingStepsProps
   );
 }
 
-function ThinkingStep({
-  label,
-  status = 'pending',
-  className,
-  ...htmlProps
-}: ThinkingStepProps) {
+function ThinkingStep({ label, status = "pending", className, ...htmlProps }: ThinkingStepProps) {
   const classes = [
     styles.step,
     styles[`step${status.charAt(0).toUpperCase() + status.slice(1)}`],
     className,
-  ].filter(Boolean).join(' ');
+  ]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <div {...htmlProps} className={classes}>
       <span className={styles.stepIndicator}>
-        {status === 'complete' && <CheckIcon />}
-        {status === 'error' && <ErrorIcon />}
-        {status === 'active' && <Loading size="sm" variant="spinner" color="current" label="" />}
-        {status === 'pending' && <span className={styles.stepDot} />}
+        {status === "complete" && <CheckIcon />}
+        {status === "error" && <ErrorIcon />}
+        {status === "active" && (
+          <Loading
+            size="sm"
+            variant="spinner"
+            color="current"
+            label=""
+            role="presentation"
+            aria-hidden="true"
+          />
+        )}
+        {status === "pending" && <span className={styles.stepDot} />}
       </span>
       <span className={styles.stepLabel}>{label}</span>
     </div>
@@ -180,8 +184,8 @@ function ThinkingStep({
 
 function ThinkingIndicatorRoot({
   active = true,
-  label = 'Thinking...',
-  variant = 'dots',
+  label = "Thinking...",
+  variant = "dots",
   showElapsed = false,
   steps,
   className,
@@ -196,41 +200,31 @@ function ThinkingIndicatorRoot({
 
   if (!active) return null;
 
-  const classes = [
-    styles.thinkingIndicator,
-    className,
-  ].filter(Boolean).join(' ');
+  const classes = [styles.thinkingIndicator, className].filter(Boolean).join(" ");
 
   // Map ThinkingIndicator variants to Loading variants
-  const loadingVariant = variant === 'dots' ? 'dots'
-    : variant === 'pulse' ? 'pulse'
-    : 'spinner';
+  const loadingVariant = variant === "dots" ? "dots" : variant === "pulse" ? "pulse" : "spinner";
 
   return (
     <ThinkingIndicatorContext.Provider value={contextValue}>
-      <div
-        {...htmlProps}
-        className={classes}
-        role="status"
-        aria-label={label}
-        aria-live="polite"
-      >
+      <div {...htmlProps} className={classes} role="status" aria-label={label} aria-live="polite">
         <div className={styles.main}>
-          <Loading size="sm" variant={loadingVariant} color="muted" label="" />
+          <Loading
+            size="sm"
+            variant={loadingVariant}
+            color="muted"
+            label=""
+            role="presentation"
+            aria-hidden="true"
+          />
           <span className={styles.label}>{label}</span>
-          {showElapsed && elapsedTime && (
-            <span className={styles.elapsed}>{elapsedTime}</span>
-          )}
+          {showElapsed && elapsedTime && <span className={styles.elapsed}>{elapsedTime}</span>}
         </div>
 
         {steps && steps.length > 0 && (
           <ThinkingSteps>
             {steps.map((step) => (
-              <ThinkingStep
-                key={step.id}
-                label={step.label}
-                status={step.status}
-              />
+              <ThinkingStep key={step.id} label={step.label} status={step.status} />
             ))}
           </ThinkingSteps>
         )}
@@ -248,10 +242,6 @@ export const ThinkingIndicator = Object.assign(ThinkingIndicatorRoot, {
   Step: ThinkingStep,
 });
 
-export {
-  ThinkingIndicatorRoot,
-  ThinkingSteps,
-  ThinkingStep,
-};
+export { ThinkingIndicatorRoot, ThinkingSteps, ThinkingStep };
 
 export { useThinkingIndicatorContext };

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

@@ -1,14 +1,9 @@
 {
   "$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",
@@ -44,18 +39,12 @@
       "description": "Visual variant indicating message type",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "success",
-        "error",
-        "warning",
-        "info"
-      ]
+      "values": ["default", "success", "error", "warning", "info"]
     },
     "duration": {
       "type": "number",
       "description": "Auto-dismiss duration in ms (0 = no auto-dismiss)",
-      "default": 5000,
+      "default": 8000,
       "required": false
     },
     "action": {
@@ -81,62 +70,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 variant 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": "Variants",
+      "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    variant=\"success\"\n  />\n  <Toast\n    title=\"Error\"\n    description=\"Failed to save changes. Please try again.\"\n    variant=\"error\"\n  />\n  <Toast\n    title=\"Warning\"\n    description=\"This action cannot be undone.\"\n    variant=\"warning\"\n  />\n  <Toast\n    title=\"New update\"\n    description=\"Version 2.0 is now available.\"\n    variant=\"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  variant=\"info\"\n  onDismiss={() => {}}\n/>"
     }
   ],
   "relations": [
@@ -161,16 +140,11 @@
       "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",