@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-feedback-toast.json

@@ -0,0 +1,1040 @@
+{
+  "meta": {
+    "id": "Components-Toast",
+    "title": "Toast",
+    "exportName": "toast",
+    "description": "Displays brief, temporary notifications that confirm actions or provide status updates without interrupting the user's workflow.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/toast/toast.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Toast"
+    ],
+    "route": "components/feedback/toast",
+    "tags": [
+      "component",
+      "notification",
+      "feedback",
+      "transient"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key characteristics",
+        "href": "#key-characteristics",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Color palette",
+        "href": "#color-palette",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Info (blue)",
+        "href": "#info-blue",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Positive (green)",
+        "href": "#positive-green",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Warning (orange)",
+        "href": "#warning-orange",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Critical (red)",
+        "href": "#critical-red",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Placement",
+        "href": "#placement",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Top positions",
+        "href": "#top-positions",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Bottom positions",
+        "href": "#bottom-positions",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Structure",
+        "href": "#structure",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Title and description",
+        "href": "#title-and-description",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Custom icons",
+        "href": "#custom-icons",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Action buttons",
+        "href": "#action-buttons",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Best practices",
+        "href": "#best-practices",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Writing guidelines",
+        "href": "#writing-guidelines",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Message structure",
+        "href": "#message-structure",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Preferred words",
+        "href": "#preferred-words",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Avoid these words",
+        "href": "#avoid-these-words",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Voice and tone",
+        "href": "#voice-and-tone",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          3,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Accessibility",
+        "href": "#accessibility",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Screen reader announcements",
+        "href": "#screen-reader-announcements",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Keyboard navigation",
+        "href": "#keyboard-navigation",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Auto-dismiss considerations",
+        "href": "#auto-dismiss-considerations",
+        "depth": 3,
+        "numbering": [
+          1,
+          4,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Specs",
+        "href": "#specs",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nToasts are lightweight, non-modal notifications that appear temporarily at the edge of the screen. They provide contextual feedback about completed actions, system status, or important updates while allowing users to continue their work uninterrupted. Unlike alerts or dialogs, toasts automatically dismiss after a few seconds and don't require user interaction unless an action is provided.\n\n### Key characteristics\n\n- **Non-intrusive**: Appears without blocking content or requiring immediate attention\n- **Temporary**: Auto-dismisses after a configurable duration (default 6 seconds)\n- **Stackable**: Multiple toasts can appear simultaneously in organized regions\n- **Contextual**: Provides immediate feedback at key moments in the user journey\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[ARIA Live Regions Pattern](https://www.w3.org/WAI/ARIA/apg/practices/live-regions/)\n\n## Variables\n\nGet familiar with the features.\n\n### Color palette\n\nEach color palette conveys a specific semantic meaning and visual urgency level.\n\n#### Info (blue)\n\nUse for general informational messages that provide helpful context without requiring action.\n\n```jsx-live\nconst App = () => {\n  const showInfoToast = () => {\n    toast.info({\n      title: \"Information\",\n      description: \"Your settings have been synced with the cloud.\"\n    });\n  };\n\n  return <Button onPress={showInfoToast}>Show Info Toast</Button>;\n}\n```\n\n#### Positive (green)\n\nUse for success confirmations after users complete important actions.\n\n```jsx-live\nconst App = () => {\n  const showSuccessToast = () => {\n    toast.success({\n      title: \"Success\",\n      description: \"Your changes have been saved successfully.\"\n    });\n  };\n\n  return <Button onPress={showSuccessToast}>Show Success Toast</Button>;\n}\n```\n\n#### Warning (orange)\n\nUse for cautionary messages that don't prevent action but require user awareness.\n\n```jsx-live\nconst App = () => {\n  const showWarningToast = () => {\n    toast.warning({\n      title: \"Warning\",\n      description: \"You're approaching your storage limit (85% used).\"\n    });\n  };\n\n  return <Button onPress={showWarningToast}>Show Warning Toast</Button>;\n}\n```\n\n#### Critical (red)\n\nUse for error messages when actions fail or require immediate attention.\n\n```jsx-live\nconst App = () => {\n  const showErrorToast = () => {\n    toast.error({\n      title: \"Error\",\n      description: \"Unable to save changes. Please try again.\"\n    });\n  };\n\n  return <Button onPress={showErrorToast}>Show Error Toast</Button>;\n}\n```\n\n### Placement\n\nChoose placement based on interface layout and user attention priorities.\n\n#### Top positions\n\nBest for important confirmations that users should notice immediately. Use top-end (default) for most cases as it aligns with reading direction and avoids covering primary content.\n\n- **Top-start**: Left-aligned notifications\n- **Top-end**: Right-aligned (default), recommended for most use cases\n\n#### Bottom positions\n\nBetter for less urgent updates or dense interfaces where top placement might obscure important content.\n\n- **Bottom-start**: Left-aligned, use in left-nav interfaces\n- **Bottom-end**: Right-aligned, balances with top-end\n\n### Structure\n\n#### Title and description\n\nAlways include a clear title that summarizes the message. Use description for additional context when needed.\n\n```jsx-live\nconst App = () => {\n  const showToast = () => {\n    toast.success({\n      title: \"Product published\",\n      description: \"Your product is now live and visible to customers.\"\n    });\n  };\n\n  return <Button onPress={showToast}>Publish Product</Button>;\n}\n```\n\n#### Custom icons\n\nOverride the default type-based icon with a custom icon to provide more specific visual context.\n\n```jsx-live\nconst App = () => {\n  const { Bathtub } = Icons;\n\n  const showCustomIconToast = () => {\n    toast.info({\n      title: \"Bath is ready\",\n      description: \"Your bath has reached the perfect temperature.\",\n      icon: <Bathtub />\n    });\n  };\n\n  return <Button onPress={showCustomIconToast}>Show Custom Icon Toast</Button>;\n}\n```\n\n#### Action buttons\n\nInclude action buttons when users might want to undo or view details. Toasts with actions auto-dismiss after the standard duration (6 seconds by default). Each toast supports a single action button — this keeps notifications scannable and focused. For workflows that involve multiple steps, use `toast.update()` to evolve the same toast through each stage rather than stacking separate notifications (see the [multi-step operations pattern](./toast.dev.mdx#multi-step-operations) in the implementation docs).\n\n```jsx-live\nconst App = () => {\n  const [undone, setUndone] = useState(false);\n\n  const handleDelete = () => {\n    setUndone(false);\n    toast({\n      title: \"Item deleted\",\n      description: \"The item has been removed from your list.\",\n      type: \"info\",\n      action: {\n        label: \"Undo\",\n        onPress: () => setUndone(true)\n      }\n    });\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      <Button onPress={handleDelete}>Delete Item</Button>\n      {undone && <Text color=\"positive.fg\">Action was undone</Text>}\n    </Stack>\n  );\n}\n```\n\n## Guidelines\n\nUse toasts strategically to confirm actions and provide feedback without disrupting the user experience.\n\n### Best practices\n\n- **Keep messages concise**: Aim for titles under 60 characters and descriptions under 120 characters\n- **Use appropriate urgency**: Match the color palette to the message severity\n- **Provide clear actions**: If including a button, make the action specific (\"Undo delete\" not \"Undo\")\n- **Consider timing**: Default 6 seconds works for most messages; use longer durations for complex information\n- **Limit frequency**: Avoid showing multiple toasts simultaneously unless they're from different contexts\n- **Maintain consistency**: Use the same placement throughout your application\n\n### When to use\n\n> [!TIP]\\\n> When to use Toast\n\n- **Action confirmations**: \"Saved successfully\", \"Item deleted\"\n- **Background task updates**: \"Export complete\", \"Sync finished\"\n- **Non-critical errors**: Recoverable failures that don't require immediate action\n- **Undo opportunities**: Allow users to reverse recent actions\n- **Progress notifications**: Brief updates on ongoing operations\n\n> [!CAUTION]\\\n> When NOT to use Toast\n\n- **Critical errors requiring action**: Use Dialog instead for errors that block workflow\n- **Complex information**: Use Alert for messages requiring careful reading\n- **Persistent status**: Use Alert for information that should remain visible\n- **Input validation**: Use inline FieldErrors for form validation feedback\n- **Confirmation dialogs**: Use Dialog when user decision is required before proceeding\n- **Success states already visible**: Don't duplicate feedback that's obvious from UI changes\n\n### Writing guidelines\n\nWrite clear, actionable messages that users can quickly scan and understand.\n\n#### Message structure\n\n- **Title**: Action + outcome (\"Item deleted\", \"Changes saved\")\n- **Description**: Additional context or next steps (optional)\n- **Action button**: Specific verb (\"Undo\", \"View details\", \"Retry\")\n\n#### Preferred words\n\n| Use | When |\n| --- | --- |\n| **Saved** | Confirming data persistence |\n| **Deleted** | Confirming removal |\n| **Updated** | Confirming changes applied |\n| **Published** | Confirming content went live |\n| **Synced** | Confirming data synchronization |\n| **Complete** | Confirming process finished |\n\n#### Avoid these words\n\n| Avoid | Use instead |\n| --- | --- |\n| **Success!** | Specific action (\"Saved successfully\") |\n| **Error** | Specific problem (\"Unable to save changes\") |\n| **OK** | Specific action (\"View details\", \"Got it\") |\n| **Done** | Specific completion (\"Export complete\") |\n\n#### Voice and tone\n\n- **Active voice**: \"Deleted 3 items\" not \"3 items were deleted\"\n- **Positive framing**: \"Saved successfully\" not \"No errors occurred\"\n- **Specific outcomes**: \"Product published\" not \"Operation completed\"\n\n## Accessibility\n\nToasts follow WCAG 2.1 AA guidelines with proper ARIA implementation for screen readers.\n\n### Screen reader announcements\n\n- **Info, Success, and Warning**: Announced politely (role=\"status\") without interrupting current reading\n- **Error**: Announced assertively (role=\"alert\") to immediately notify users of important information\n- The `\"aria-live\"` option allows overriding the default politeness level for any toast type\n\n### Keyboard navigation\n\n| Key | Action |\n| --- | --- |\n| `Tab` | Navigate between close button and action button (if present) |\n| `Escape` | Dismiss the focused toast |\n| `Ctrl+Shift+[1-9]` | Focus specific placement region (based on numpad position) |\n\nUsers can dismiss toasts via keyboard, ensuring full accessibility for non-mouse users.\n\n### Auto-dismiss considerations\n\n- Toasts with action buttons auto-dismiss after the standard duration; use `duration: Infinity` with `closable: true` to create persistent toasts that require user interaction\n- Timers pause when toast is focused or hovered, accommodating users who need more time\n- Default 6-second duration allows sufficient time to read messages (reading time: ~2-3 seconds + comprehension buffer)\n\n## Specs\n\nSee the [Implementation tab](./toast.dev.mdx) for the full API reference including `ToastOptions` properties and control methods.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nToasts are lightweight, non-modal notifications that appear temporarily at the edge of the screen. They provide contextual feedback about completed actions, system status, or important updates while allowing users to continue their work uninterrupted. Unlike alerts or dialogs, toasts automatically dismiss after a few seconds and don't require user interaction unless an action is provided.\n\n### Key characteristics\n\n- **Non-intrusive**: Appears without blocking content or requiring immediate attention\n- **Temporary**: Auto-dismisses after a configurable duration (default 6 seconds)\n- **Stackable**: Multiple toasts can appear simultaneously in organized regions\n- **Contextual**: Provides immediate feedback at key moments in the user journey\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[ARIA Live Regions Pattern](https://www.w3.org/WAI/ARIA/apg/practices/live-regions/)\n\n## Variables\n\nGet familiar with the features.\n\n### Color palette\n\nEach color palette conveys a specific semantic meaning and visual urgency level.\n\n#### Info (blue)\n\nUse for general informational messages that provide helpful context without requiring action.\n\n```jsx-live\nconst App = () => {\n  const showInfoToast = () => {\n    toast.info({\n      title: \"Information\",\n      description: \"Your settings have been synced with the cloud.\"\n    });\n  };\n\n  return <Button onPress={showInfoToast}>Show Info Toast</Button>;\n}\n```\n\n#### Positive (green)\n\nUse for success confirmations after users complete important actions.\n\n```jsx-live\nconst App = () => {\n  const showSuccessToast = () => {\n    toast.success({\n      title: \"Success\",\n      description: \"Your changes have been saved successfully.\"\n    });\n  };\n\n  return <Button onPress={showSuccessToast}>Show Success Toast</Button>;\n}\n```\n\n#### Warning (orange)\n\nUse for cautionary messages that don't prevent action but require user awareness.\n\n```jsx-live\nconst App = () => {\n  const showWarningToast = () => {\n    toast.warning({\n      title: \"Warning\",\n      description: \"You're approaching your storage limit (85% used).\"\n    });\n  };\n\n  return <Button onPress={showWarningToast}>Show Warning Toast</Button>;\n}\n```\n\n#### Critical (red)\n\nUse for error messages when actions fail or require immediate attention.\n\n```jsx-live\nconst App = () => {\n  const showErrorToast = () => {\n    toast.error({\n      title: \"Error\",\n      description: \"Unable to save changes. Please try again.\"\n    });\n  };\n\n  return <Button onPress={showErrorToast}>Show Error Toast</Button>;\n}\n```\n\n### Placement\n\nChoose placement based on interface layout and user attention priorities.\n\n#### Top positions\n\nBest for important confirmations that users should notice immediately. Use top-end (default) for most cases as it aligns with reading direction and avoids covering primary content.\n\n- **Top-start**: Left-aligned notifications\n- **Top-end**: Right-aligned (default), recommended for most use cases\n\n#### Bottom positions\n\nBetter for less urgent updates or dense interfaces where top placement might obscure important content.\n\n- **Bottom-start**: Left-aligned, use in left-nav interfaces\n- **Bottom-end**: Right-aligned, balances with top-end\n\n### Structure\n\n#### Title and description\n\nAlways include a clear title that summarizes the message. Use description for additional context when needed.\n\n```jsx-live\nconst App = () => {\n  const showToast = () => {\n    toast.success({\n      title: \"Product published\",\n      description: \"Your product is now live and visible to customers.\"\n    });\n  };\n\n  return <Button onPress={showToast}>Publish Product</Button>;\n}\n```\n\n#### Custom icons\n\nOverride the default type-based icon with a custom icon to provide more specific visual context.\n\n```jsx-live\nconst App = () => {\n  const { Bathtub } = Icons;\n\n  const showCustomIconToast = () => {\n    toast.info({\n      title: \"Bath is ready\",\n      description: \"Your bath has reached the perfect temperature.\",\n      icon: <Bathtub />\n    });\n  };\n\n  return <Button onPress={showCustomIconToast}>Show Custom Icon Toast</Button>;\n}\n```\n\n#### Action buttons\n\nInclude action buttons when users might want to undo or view details. Toasts with actions auto-dismiss after the standard duration (6 seconds by default). Each toast supports a single action button — this keeps notifications scannable and focused. For workflows that involve multiple steps, use `toast.update()` to evolve the same toast through each stage rather than stacking separate notifications (see the [multi-step operations pattern](./toast.dev.mdx#multi-step-operations) in the implementation docs).\n\n```jsx-live\nconst App = () => {\n  const [undone, setUndone] = useState(false);\n\n  const handleDelete = () => {\n    setUndone(false);\n    toast({\n      title: \"Item deleted\",\n      description: \"The item has been removed from your list.\",\n      type: \"info\",\n      action: {\n        label: \"Undo\",\n        onPress: () => setUndone(true)\n      }\n    });\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      <Button onPress={handleDelete}>Delete Item</Button>\n      {undone && <Text color=\"positive.fg\">Action was undone</Text>}\n    </Stack>\n  );\n}\n```\n\n## Guidelines\n\nUse toasts strategically to confirm actions and provide feedback without disrupting the user experience.\n\n### Best practices\n\n- **Keep messages concise**: Aim for titles under 60 characters and descriptions under 120 characters\n- **Use appropriate urgency**: Match the color palette to the message severity\n- **Provide clear actions**: If including a button, make the action specific (\"Undo delete\" not \"Undo\")\n- **Consider timing**: Default 6 seconds works for most messages; use longer durations for complex information\n- **Limit frequency**: Avoid showing multiple toasts simultaneously unless they're from different contexts\n- **Maintain consistency**: Use the same placement throughout your application\n\n### When to use\n\n> [!TIP]\\\n> When to use Toast\n\n- **Action confirmations**: \"Saved successfully\", \"Item deleted\"\n- **Background task updates**: \"Export complete\", \"Sync finished\"\n- **Non-critical errors**: Recoverable failures that don't require immediate action\n- **Undo opportunities**: Allow users to reverse recent actions\n- **Progress notifications**: Brief updates on ongoing operations\n\n> [!CAUTION]\\\n> When NOT to use Toast\n\n- **Critical errors requiring action**: Use Dialog instead for errors that block workflow\n- **Complex information**: Use Alert for messages requiring careful reading\n- **Persistent status**: Use Alert for information that should remain visible\n- **Input validation**: Use inline FieldErrors for form validation feedback\n- **Confirmation dialogs**: Use Dialog when user decision is required before proceeding\n- **Success states already visible**: Don't duplicate feedback that's obvious from UI changes\n\n### Writing guidelines\n\nWrite clear, actionable messages that users can quickly scan and understand.\n\n#### Message structure\n\n- **Title**: Action + outcome (\"Item deleted\", \"Changes saved\")\n- **Description**: Additional context or next steps (optional)\n- **Action button**: Specific verb (\"Undo\", \"View details\", \"Retry\")\n\n#### Preferred words\n\n| Use | When |\n| --- | --- |\n| **Saved** | Confirming data persistence |\n| **Deleted** | Confirming removal |\n| **Updated** | Confirming changes applied |\n| **Published** | Confirming content went live |\n| **Synced** | Confirming data synchronization |\n| **Complete** | Confirming process finished |\n\n#### Avoid these words\n\n| Avoid | Use instead |\n| --- | --- |\n| **Success!** | Specific action (\"Saved successfully\") |\n| **Error** | Specific problem (\"Unable to save changes\") |\n| **OK** | Specific action (\"View details\", \"Got it\") |\n| **Done** | Specific completion (\"Export complete\") |\n\n#### Voice and tone\n\n- **Active voice**: \"Deleted 3 items\" not \"3 items were deleted\"\n- **Positive framing**: \"Saved successfully\" not \"No errors occurred\"\n- **Specific outcomes**: \"Product published\" not \"Operation completed\"\n\n## Accessibility\n\nToasts follow WCAG 2.1 AA guidelines with proper ARIA implementation for screen readers.\n\n### Screen reader announcements\n\n- **Info, Success, and Warning**: Announced politely (role=\"status\") without interrupting current reading\n- **Error**: Announced assertively (role=\"alert\") to immediately notify users of important information\n- The `\"aria-live\"` option allows overriding the default politeness level for any toast type\n\n### Keyboard navigation\n\n| Key | Action |\n| --- | --- |\n| `Tab` | Navigate between close button and action button (if present) |\n| `Escape` | Dismiss the focused toast |\n| `Ctrl+Shift+[1-9]` | Focus specific placement region (based on numpad position) |\n\nUsers can dismiss toasts via keyboard, ensuring full accessibility for non-mouse users.\n\n### Auto-dismiss considerations\n\n- Toasts with action buttons auto-dismiss after the standard duration; use `duration: Infinity` with `closable: true` to create persistent toasts that require user interaction\n- Timers pause when toast is focused or hovered, accommodating users who need more time\n- Default 6-second duration allows sufficient time to read messages (reading time: ~2-3 seconds + comprehension buffer)\n\n## Specs\n\nSee the [Implementation tab](./toast.dev.mdx) for the full API reference including `ToastOptions` properties and control methods.\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key characteristics",
+          "href": "#key-characteristics",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Info (blue)",
+          "href": "#info-blue",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Positive (green)",
+          "href": "#positive-green",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Warning (orange)",
+          "href": "#warning-orange",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical (red)",
+          "href": "#critical-red",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement",
+          "href": "#placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Top positions",
+          "href": "#top-positions",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Bottom positions",
+          "href": "#bottom-positions",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Structure",
+          "href": "#structure",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Title and description",
+          "href": "#title-and-description",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom icons",
+          "href": "#custom-icons",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Action buttons",
+          "href": "#action-buttons",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Writing guidelines",
+          "href": "#writing-guidelines",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Message structure",
+          "href": "#message-structure",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Preferred words",
+          "href": "#preferred-words",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Avoid these words",
+          "href": "#avoid-these-words",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Voice and tone",
+          "href": "#voice-and-tone",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Screen reader announcements",
+          "href": "#screen-reader-announcements",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Auto-dismiss considerations",
+          "href": "#auto-dismiss-considerations",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Specs",
+          "href": "#specs",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { toast, type ToastOptions } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nCreate toast notifications using the imperative `toast()` API. Toasts are rendered automatically by the `NimbusProvider`.\n\n```jsx-live-dev\nconst App = () => {\n  const handleClick = () => {\n    toast({\n      title: \"Success\",\n      description: \"Your changes have been saved.\",\n      type: \"success\"\n    });\n  };\n\n  return (\n    <Button onPress={handleClick}>\n      Show Toast\n    </Button>\n  );\n}\n```\n\n## Usage examples\n\n### Toast types\n\nFour types are available, each with semantic meaning and ARIA roles:\n\n```jsx-live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\" flexWrap=\"wrap\">\n    <Button onPress={() => toast.info({ title: \"Information\", description: \"This is informational.\" })}>\n      Info Toast\n    </Button>\n    <Button onPress={() => toast.success({ title: \"Success\", description: \"Operation completed.\" })}>\n      Success Toast\n    </Button>\n    <Button onPress={() => toast.warning({ title: \"Warning\", description: \"Please review this.\" })}>\n      Warning Toast\n    </Button>\n    <Button onPress={() => toast.error({ title: \"Error\", description: \"An error occurred.\" })}>\n      Error Toast\n    </Button>\n  </Stack>\n)\n```\n\n**ARIA semantics:**\n- `info`, `success`, and `warning`: `role=\"status\"` (polite announcements)\n- `error`: `role=\"alert\"` (assertive announcements)\n- Use the `\"aria-live\"` option to override the default politeness level for any toast type\n\n### Placement options\n\nControl where toasts appear on screen using the `placement` prop. Each placement creates an independent toast region:\n\n```jsx-live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\" flexWrap=\"wrap\">\n    <Button onPress={() => toast({ title: \"Top Start\", placement: \"top-start\" })}>\n      Top Start\n    </Button>\n    <Button onPress={() => toast({ title: \"Top End (Default)\", placement: \"top-end\" })}>\n      Top End\n    </Button>\n    <Button onPress={() => toast({ title: \"Bottom Start\", placement: \"bottom-start\" })}>\n      Bottom Start\n    </Button>\n    <Button onPress={() => toast({ title: \"Bottom End\", placement: \"bottom-end\" })}>\n      Bottom End\n    </Button>\n  </Stack>\n)\n```\n\n### Auto-dismiss behavior\n\nToasts auto-dismiss after 6 seconds by default. The timer pauses on hover and focus:\n\n```jsx-live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\" flexWrap=\"wrap\">\n    <Button onPress={() => toast({ title: \"Default (6s)\", description: \"Dismisses after 6 seconds\" })}>\n      Default Duration\n    </Button>\n    <Button onPress={() => toast({ title: \"Custom Duration\", description: \"Dismisses after 10 seconds\", duration: 10000 })}>\n      10 Second Duration\n    </Button>\n    <Button onPress={() => toast({ title: \"Persistent\", description: \"Never auto-dismisses\", duration: Infinity })}>\n      No Auto-Dismiss\n    </Button>\n  </Stack>\n)\n```\n\n**Duration values:**\n- Default: `6000` (6 seconds)\n- Custom: Any positive number in milliseconds\n- Persistent: `Infinity` (never auto-dismisses)\n\n### Action buttons\n\nAdd action buttons to toasts. Duration is controlled independently — set `duration: Infinity` if the action requires user acknowledgment:\n\n```jsx-live-dev\nconst App = () => {\n  const handleUndo = () => {\n    toast.success({ title: \"Undo successful\" });\n  };\n\n  const handleDelete = () => {\n    toast({\n      title: \"Item deleted\",\n      description: \"The item has been removed from your list.\",\n      type: \"info\",\n      action: {\n        label: \"Undo\",\n        onPress: handleUndo\n      }\n    });\n  };\n\n  return (\n    <Button onPress={handleDelete}>\n      Delete Item\n    </Button>\n  );\n}\n```\n\n### Promise pattern\n\nUse `toast.promise()` to show loading, success, and error states for async operations:\n\n```jsx-live-dev\nconst App = () => {\n  const simulateAsyncOperation = () => {\n    return new Promise((resolve, reject) => {\n      setTimeout(() => {\n        Math.random() > 0.5 ? resolve(\"Success!\") : reject(\"Failed!\");\n      }, 2000);\n    });\n  };\n\n  const handleClick = () => {\n    toast.promise(\n      simulateAsyncOperation(),\n      {\n        loading: { title: \"Saving...\", description: \"Please wait\", closable: false },\n        success: { title: \"Saved\", description: \"Your changes have been saved\", type: \"success\" },\n        error: { title: \"Error\", description: \"Failed to save changes\", type: \"error\" }\n      }\n    );\n  };\n\n  return (\n    <Button onPress={handleClick}>\n      Save with Promise\n    </Button>\n  );\n}\n```\n\n### Programmatic control\n\nUpdate or dismiss toasts programmatically using their IDs:\n\n```jsx-live-dev\nconst App = () => {\n  const [toastId, setToastId] = useState<string | null>(null);\n\n  const handleCreate = () => {\n    const id = toast({\n      title: \"Processing...\",\n      description: \"Operation in progress\",\n      duration: Infinity\n    });\n    setToastId(id);\n  };\n\n  const handleUpdate = () => {\n    if (toastId) {\n      toast.update(toastId, {\n        title: \"Updated!\",\n        description: \"Toast content has been updated\",\n        type: \"success\"\n      });\n    }\n  };\n\n  const handleDismiss = () => {\n    if (toastId) {\n      toast.dismiss(toastId);\n      setToastId(null);\n    }\n  };\n\n  return (\n    <Stack direction=\"row\" gap=\"200\">\n      <Button onPress={handleCreate}>Create Toast</Button>\n      <Button onPress={handleUpdate} isDisabled={!toastId}>Update Toast</Button>\n      <Button onPress={handleDismiss} isDisabled={!toastId}>Dismiss Toast</Button>\n    </Stack>\n  );\n}\n```\n\n**API methods:**\n- `toast.update(id, options)`: Update toast content\n- `toast.dismiss(id)`: Dismiss with animation (omit `id` to dismiss all)\n- `toast.remove(id)`: Remove immediately without animation (omit `id` to remove all)\n\n### Custom icon\n\nOverride the default type-based icon with a custom icon element using the `icon` prop:\n\n```jsx-live-dev\nconst App = () => {\n  const { Bathtub } = Icons;\n\n  return (\n    <Stack direction=\"row\" gap=\"200\" flexWrap=\"wrap\">\n      <Button onPress={() => toast.info({ title: \"Custom Icon\", description: \"This toast uses a custom icon\", icon: <Bathtub /> })}>\n        Custom Icon Toast\n      </Button>\n      <Button onPress={() => toast.info({ title: \"Default Icon\", description: \"This toast uses the default info icon\" })}>\n        Default Icon Toast\n      </Button>\n    </Stack>\n  );\n}\n```\n\nWhen the `icon` prop is provided, it replaces the default icon for that toast type. The `loading` type always shows a spinner regardless of the `icon` prop.\n\n### Closable control\n\nControl close button visibility with the `closable` prop. Useful for loading states:\n\n```jsx-live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\">\n    <Button onPress={() => toast({ title: \"Closable Toast\", description: \"Has close button\", closable: true })}>\n      With Close Button\n    </Button>\n    <Button onPress={() => toast({ title: \"Loading...\", description: \"Processing your request\", closable: false, duration: 3000 })}>\n      No Close Button\n    </Button>\n  </Stack>\n)\n```\n\n### Stacking and queuing\n\nMultiple toasts stack vertically without overlapping. When the maximum (24) is exceeded, additional toasts queue:\n\n```jsx-live-dev\nconst App = () => {\n  const handleCreateMultiple = () => {\n    for (let i = 1; i <= 5; i++) {\n      setTimeout(() => {\n        toast({\n          title: `Toast ${i}`,\n          description: `This is toast notification ${i}`,\n          type: i % 2 === 0 ? \"success\" : \"info\"\n        });\n      }, i * 300);\n    }\n  };\n\n  return (\n    <Button onPress={handleCreateMultiple}>\n      Create Multiple Toasts\n    </Button>\n  );\n}\n```\n\n## Component requirements\n\n### Zero setup\n\nToast functionality is automatically available when using `NimbusProvider`. No additional setup is required:\n\n```tsx\nimport { NimbusProvider } from '@commercetools/nimbus';\n\nconst App = () => (\n  <NimbusProvider>\n    {/* Toast is ready to use anywhere in your app */}\n    <YourApp />\n  </NimbusProvider>\n);\n```\n\nThe `ToastOutlet` component is rendered internally by `NimbusProvider` and manages all toast regions.\n\n### Accessibility\n\nThe Toast component handles accessibility requirements internally via React Aria and Chakra UI.\n\n**ARIA role differentiation:**\n- Info, success, and warning toasts use `role=\"status\"` with `aria-live=\"polite\"` for non-intrusive announcements\n- Error toasts use `role=\"alert\"` with `aria-live=\"assertive\"` for immediate attention\n- The `ariaLive` option allows overriding the default politeness level for any toast type\n\n**Internationalization:**\nThe close button uses a localized `aria-label` resolved via `useLocalizedStringFormatter` from `@react-aria/i18n`. Translations are provided for English, German, Spanish, French, and Portuguese.\n\n#### Keyboard navigation\n\nToast regions support keyboard interaction:\n\n- `Tab`: Navigate between close button and action button (if present)\n- `Escape`: Dismiss the focused toast\n- `Ctrl+Shift+[1-9]`: Focus specific placement regions (works with both number row and numpad)\n  - `Ctrl+Shift+7`: Top-start\n  - `Ctrl+Shift+9`: Top-end (default)\n  - `Ctrl+Shift+1`: Bottom-start\n  - `Ctrl+Shift+3`: Bottom-end\n\nHotkeys are only active for placements with visible toasts.\n\n## API reference\n\n### `toast(options: ToastOptions): string`\n\nCreates a toast and returns its ID. Also available as convenience methods: `toast.info()`, `toast.success()`, `toast.warning()`, `toast.error()`.\n\n### ToastOptions\n\n| Prop | Type | Default | Description |\n| --- | --- | --- | --- |\n| `type` | `\"info\" \\| \"success\" \\| \"warning\" \\| \"error\"` | `\"info\"` | Visual style and ARIA semantics |\n| `title` | `string` | — | Title text |\n| `description` | `string` | — | Description text |\n| `action` | `{ label: string; onPress: () => void }` | — | Action button |\n| `icon` | `React.ReactElement` | — | Custom icon replacing the default type-based icon |\n| `duration` | `number` | `6000` | Auto-dismiss in ms (`Infinity` = never) |\n| `placement` | `ToastPlacement` | `\"top-end\"` | Screen position |\n| `closable` | `boolean` | `false` | Show/hide close button (auto-enabled for persistent toasts) |\n| `pauseOnInteraction` | `boolean` | `true` | Pause timer on hover/focus |\n| `variant` | `\"solid\" \\| \"subtle\" \\| \"accent-start\"` | `\"accent-start\"` | Visual variant |\n\n### Control methods\n\n| Method | Description |\n| --- | --- |\n| `toast.update(id, options)` | Update toast content |\n| `toast.dismiss(id?)` | Dismiss with animation (omit `id` for all) |\n| `toast.remove(id?)` | Remove immediately (omit `id` for all) |\n| `toast.promise(promise, options, config?)` | Loading → success/error transitions |\n\n## Common patterns\n\n### Error handling with actions\n\nProvide users with recovery options directly in error toasts:\n\n```jsx-live-dev\nconst App = () => {\n  const handleRetry = () => {\n    toast.info({ title: \"Retrying...\", description: \"Attempting operation again\" });\n  };\n\n  const handleError = () => {\n    toast.error({\n      title: \"Network Error\",\n      description: \"Failed to connect to the server\",\n      action: {\n        label: \"Retry\",\n        onPress: handleRetry\n      }\n    });\n  };\n\n  return (\n    <Button onPress={handleError}>\n      Simulate Error\n    </Button>\n  );\n}\n```\n\n### Success confirmation with undo\n\nAllow users to undo destructive actions:\n\n```jsx-live-dev\nconst App = () => {\n  const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']);\n  const [lastDeleted, setLastDeleted] = useState<string | null>(null);\n\n  const handleDelete = (item: string) => {\n    setLastDeleted(item);\n    setItems(items.filter(i => i !== item));\n\n    toast.success({\n      title: \"Item deleted\",\n      description: `${item} has been removed`,\n      action: {\n        label: \"Undo\",\n        onPress: () => {\n          if (lastDeleted) {\n            setItems([...items, lastDeleted]);\n            setLastDeleted(null);\n            toast.info({ title: \"Restored\", description: `${lastDeleted} has been restored` });\n          }\n        }\n      }\n    });\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      {items.map(item => (\n        <Stack key={item} direction=\"row\" gap=\"200\" alignItems=\"center\">\n          <Text>{item}</Text>\n          <Button size=\"sm\" onPress={() => handleDelete(item)}>Delete</Button>\n        </Stack>\n      ))}\n      {items.length === 0 && <Text>No items remaining</Text>}\n    </Stack>\n  );\n}\n```\n\n### Multi-step operations\n\nTrack progress through multi-step processes:\n\n```jsx-live-dev\nconst App = () => {\n  const handleMultiStep = async () => {\n    const id = toast({\n      title: \"Step 1 of 3\",\n      description: \"Validating data...\",\n      type: \"info\",\n      duration: Infinity\n    });\n\n    await new Promise(resolve => setTimeout(resolve, 1500));\n    toast.update(id, {\n      title: \"Step 2 of 3\",\n      description: \"Processing records...\"\n    });\n\n    await new Promise(resolve => setTimeout(resolve, 1500));\n    toast.update(id, {\n      title: \"Step 3 of 3\",\n      description: \"Finalizing...\"\n    });\n\n    await new Promise(resolve => setTimeout(resolve, 1500));\n    toast.update(id, {\n      title: \"Complete!\",\n      description: \"All steps finished successfully\",\n      type: \"success\",\n      duration: 6000\n    });\n  };\n\n  return (\n    <Button onPress={handleMultiStep}>\n      Start Multi-Step Process\n    </Button>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Toast in your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Usage\n\nCreate toast notifications using the imperative toast() API\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { toast } from \"@commercetools/nimbus\";\n\ndescribe(\"Toast - Basic usage\", () => {\n  it(\"creates toast using toast() function\", () => {\n    const id = toast({\n      title: \"Imperative Toast\",\n      description: \"Created programmatically\",\n      type: \"info\",\n    });\n\n    expect(id).toBeDefined();\n    expect(typeof id).toBe(\"string\");\n\n    // Clean up\n    toast.remove(id);\n  });\n\n  it(\"creates toasts using convenience methods\", () => {\n    const successId = toast.success({\n      title: \"Success Toast\",\n      description: \"Operation completed successfully\",\n    });\n\n    const errorId = toast.error({\n      title: \"Error Toast\",\n      description: \"Something went wrong\",\n    });\n\n    const warningId = toast.warning({\n      title: \"Warning Toast\",\n      description: \"Please be careful\",\n    });\n\n    const infoId = toast.info({\n      title: \"Info Toast\",\n      description: \"Here is some information\",\n    });\n\n    expect(successId).toBeDefined();\n    expect(errorId).toBeDefined();\n    expect(warningId).toBeDefined();\n    expect(infoId).toBeDefined();\n\n    // Clean up\n    toast.remove(successId);\n    toast.remove(errorId);\n    toast.remove(warningId);\n    toast.remove(infoId);\n  });\n\n  it(\"creates toasts with custom placement\", () => {\n    const id = toast({\n      title: \"Custom Placement\",\n      description: \"This toast appears at bottom-end\",\n      placement: \"bottom-end\",\n    });\n\n    expect(id).toBeDefined();\n\n    // Clean up\n    toast.remove(id);\n  });\n});\n```\n\n### Programmatic Control\n\nUpdate and dismiss toasts programmatically\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { toast } from \"@commercetools/nimbus\";\n\ndescribe(\"Toast - Programmatic control\", () => {\n  it(\"updates toast content programmatically\", () => {\n    const id = toast({\n      title: \"Initial Title\",\n      description: \"Initial Description\",\n      duration: Infinity,\n    });\n\n    // Update the toast content\n    toast.update(id, {\n      title: \"Updated Title\",\n      description: \"Updated Description\",\n    });\n\n    // Clean up\n    toast.remove(id);\n  });\n\n  it(\"dismisses toast programmatically\", () => {\n    const id = toast({\n      title: \"Dismissible Toast\",\n      description: \"This toast can be dismissed programmatically\",\n      duration: Infinity,\n    });\n\n    // Dismiss triggers the exit animation\n    toast.dismiss(id);\n  });\n});\n```\n\n### Promise Pattern\n\nUse toast.promise() for async operation states\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { toast } from \"@commercetools/nimbus\";\n\ndescribe(\"Toast - Promise pattern\", () => {\n  it(\"shows loading then success states\", async () => {\n    const promiseSpy = vi.spyOn(toast, \"promise\");\n\n    const asyncOperation = () =>\n      new Promise((resolve) => {\n        setTimeout(() => resolve(\"Done\"), 10);\n      });\n\n    const promise = asyncOperation();\n\n    toast.promise(promise, {\n      loading: {\n        title: \"Loading...\",\n        description: \"Please wait\",\n        closable: false,\n      },\n      success: {\n        title: \"Success!\",\n        description: \"Operation completed\",\n        type: \"success\",\n      },\n      error: {\n        title: \"Failed\",\n        description: \"Something went wrong\",\n        type: \"error\",\n      },\n    });\n\n    // Verify toast.promise was called with the correct promise and state titles\n    expect(promiseSpy).toHaveBeenCalledWith(\n      promise,\n      expect.objectContaining({\n        loading: expect.objectContaining({ title: \"Loading...\" }),\n        success: expect.objectContaining({ title: \"Success!\" }),\n        error: expect.objectContaining({ title: \"Failed\" }),\n      })\n    );\n\n    promiseSpy.mockRestore();\n  });\n});\n```\n\n### Action Buttons\n\nCreate toasts with action buttons and callbacks\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { toast } from \"@commercetools/nimbus\";\n\ndescribe(\"Toast - Action buttons\", () => {\n  it(\"creates toast with action button\", () => {\n    const handleAction = vi.fn();\n\n    const id = toast({\n      title: \"Action Required\",\n      description: \"Please take action\",\n      action: {\n        label: \"Retry\",\n        onPress: handleAction,\n      },\n    });\n\n    expect(id).toBeDefined();\n\n    // Clean up\n    toast.remove(id);\n  });\n});\n```\n\n\n## Resources\n\n{/* TODO: Add Storybook deep-link once the story is published */}\n- [Chakra UI Toast Documentation](https://www.chakra-ui.com/docs/components/toast)\n- [React Aria Live Regions](https://react-spectrum.adobe.com/react-aria/useLiveAnnouncer.html)\n- [ARIA Live Regions](https://www.w3.org/WAI/ARIA/apg/practices/live-regions/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Toast types",
+          "href": "#toast-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement options",
+          "href": "#placement-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Auto-dismiss behavior",
+          "href": "#auto-dismiss-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Action buttons",
+          "href": "#action-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Promise pattern",
+          "href": "#promise-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Programmatic control",
+          "href": "#programmatic-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom icon",
+          "href": "#custom-icon",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Closable control",
+          "href": "#closable-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacking and queuing",
+          "href": "#stacking-and-queuing",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Zero setup",
+          "href": "#zero-setup",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "toast(options: ToastOptions): string",
+          "href": "#toastoptions-toastoptions-string",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ToastOptions",
+          "href": "#toastoptions",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Control methods",
+          "href": "#control-methods",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error handling with actions",
+          "href": "#error-handling-with-actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Success confirmation with undo",
+          "href": "#success-confirmation-with-undo",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-step operations",
+          "href": "#multi-step-operations",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Usage",
+          "href": "#basic-usage-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Programmatic Control",
+          "href": "#programmatic-control-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Promise Pattern",
+          "href": "#promise-pattern-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Action Buttons",
+          "href": "#action-buttons-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}