@commercetools/nimbus-mcp 3.2.0 → 3.3.0

package/data/docs/routes/components-chat-chat-message.json

@@ -0,0 +1,580 @@
+{
+  "meta": {
+    "id": "Components-ChatMessage",
+    "title": "Chat message",
+    "exportName": "ChatMessage",
+    "description": "A single message in an AI chat conversation, pairing a sender avatar with a message body and optional actions, meta, and typing indicator.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/chat-message/chat-message.mdx",
+    "menu": [
+      "Components",
+      "Chat",
+      "Chat message"
+    ],
+    "route": "components/chat/chat-message",
+    "tags": [
+      "component",
+      "chat",
+      "message",
+      "body",
+      "ai",
+      "conversation"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Senders",
+        "href": "#senders",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Tone",
+        "href": "#tone",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Actions",
+        "href": "#actions",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Meta",
+        "href": "#meta",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Typing / streaming",
+        "href": "#typing--streaming",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=10601-14469",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\n`ChatMessage` renders **one message** in an AI chat conversation — an avatar\npaired with a message body, plus optional actions, a meta row, and a typing\nindicator for streaming replies. It does not compose the surrounding feed:\nstacking messages, scrolling, and the live region that announces new content are\nthe transcript's job (see `ChatMessageList`).\n\nThe `sender` prop drives which participant the message is from and controls both\nthe layout direction and the body/avatar styling:\n\n- `user` — the human; avatar trails the body.\n- `agent` (default) — the agent; avatar leads the body.\n\n`sender` denotes only _who_ sent the message. System notices are out of scope\nhere — a system notice isn't a message, and it isn't a standardized component\neither; consumers render their own content (for example inside a\n`ChatMessageList.Item`). Tool/function output is content _inside_ an `agent`\nmessage. Neither is a `sender` value.\n\n`tone=\"error\"` is independent of `sender` — it tints the body to flag a failed\ngeneration, since an agent message can still fail.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=10601-14469)\n\n## Variables\n\nGet familiar with the features.\n\n### Senders\n\nEach sender has its own layout direction and surface: `user` places the body\nbefore the avatar, `agent` places the avatar before the body. A system\nnotice (not standardized in this release, so a consumer renders their own\ncentered, subdued content) can sit between turns as an interjection.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\">\n    <ChatMessage.Root sender=\"user\">\n      <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n      <ChatMessage.Body>\n        <Text>Can you summarise last week's orders?</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n    <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n      Conversation history was cleared.\n    </Box>\n    <ChatMessage.Root sender=\"agent\">\n      <ChatMessage.Avatar>\n        <Icons.AutoAwesome />\n      </ChatMessage.Avatar>\n      <ChatMessage.Body>\n        <Text>Revenue is up 12% week-over-week.</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n  </Stack>\n);\n```\n\n### Tone\n\n`tone=\"error\"` tints the body with the critical palette to flag a failed\ngeneration, on top of whatever `sender` styling already applies.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" tone=\"error\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Something went wrong generating this response.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Retry\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Actions\n\n`ChatMessage.Actions` is a right-aligned row of buttons rendered inside the\nbody. Place it last so the actions pin to the bottom of the card.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>I drafted the date range for your report. Approve to apply.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Save as draft\n        </Button>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          Approve\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Meta\n\n`ChatMessage.Meta` is a `space-between` row rendered below the body, for a\ntimestamp, a trust/provenance link, or reaction icons.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Here is the summary you asked for.</Text>\n    </ChatMessage.Body>\n    <ChatMessage.Meta>\n      <Link href=\"#\">How was this generated?</Link>\n      <Stack direction=\"row\" alignItems=\"center\" gap=\"100\">\n        <Text color=\"neutral.11\">Apr 13, 11:56pm</Text>\n        <IconButton aria-label=\"Good response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbUp />\n        </IconButton>\n        <IconButton aria-label=\"Bad response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbDown />\n        </IconButton>\n        <IconButton aria-label=\"Copy\" variant=\"ghost\" size=\"xs\">\n          <Icons.ContentCopy />\n        </IconButton>\n      </Stack>\n    </ChatMessage.Meta>\n  </ChatMessage.Root>\n);\n```\n\n### Typing / streaming\n\n`ChatMessage.Typing` shows an animated \"generating…\" indicator as the body's\npayload while a reply streams. Pair it with `isStreaming` on the root, which\nsets `aria-busy`.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" isStreaming>\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <ChatMessage.Typing>\n        <Text color=\"neutral.11\">Agent is typing…</Text>\n      </ChatMessage.Typing>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`ChatMessage` renders **one message** in an AI chat conversation — an avatar\npaired with a message body, plus optional actions, a meta row, and a typing\nindicator for streaming replies. It does not compose the surrounding feed:\nstacking messages, scrolling, and the live region that announces new content are\nthe transcript's job (see `ChatMessageList`).\n\nThe `sender` prop drives which participant the message is from and controls both\nthe layout direction and the body/avatar styling:\n\n- `user` — the human; avatar trails the body.\n- `agent` (default) — the agent; avatar leads the body.\n\n`sender` denotes only _who_ sent the message. System notices are out of scope\nhere — a system notice isn't a message, and it isn't a standardized component\neither; consumers render their own content (for example inside a\n`ChatMessageList.Item`). Tool/function output is content _inside_ an `agent`\nmessage. Neither is a `sender` value.\n\n`tone=\"error\"` is independent of `sender` — it tints the body to flag a failed\ngeneration, since an agent message can still fail.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=10601-14469)\n\n## Variables\n\nGet familiar with the features.\n\n### Senders\n\nEach sender has its own layout direction and surface: `user` places the body\nbefore the avatar, `agent` places the avatar before the body. A system\nnotice (not standardized in this release, so a consumer renders their own\ncentered, subdued content) can sit between turns as an interjection.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\">\n    <ChatMessage.Root sender=\"user\">\n      <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n      <ChatMessage.Body>\n        <Text>Can you summarise last week's orders?</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n    <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n      Conversation history was cleared.\n    </Box>\n    <ChatMessage.Root sender=\"agent\">\n      <ChatMessage.Avatar>\n        <Icons.AutoAwesome />\n      </ChatMessage.Avatar>\n      <ChatMessage.Body>\n        <Text>Revenue is up 12% week-over-week.</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n  </Stack>\n);\n```\n\n### Tone\n\n`tone=\"error\"` tints the body with the critical palette to flag a failed\ngeneration, on top of whatever `sender` styling already applies.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" tone=\"error\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Something went wrong generating this response.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Retry\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Actions\n\n`ChatMessage.Actions` is a right-aligned row of buttons rendered inside the\nbody. Place it last so the actions pin to the bottom of the card.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>I drafted the date range for your report. Approve to apply.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Save as draft\n        </Button>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          Approve\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Meta\n\n`ChatMessage.Meta` is a `space-between` row rendered below the body, for a\ntimestamp, a trust/provenance link, or reaction icons.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Here is the summary you asked for.</Text>\n    </ChatMessage.Body>\n    <ChatMessage.Meta>\n      <Link href=\"#\">How was this generated?</Link>\n      <Stack direction=\"row\" alignItems=\"center\" gap=\"100\">\n        <Text color=\"neutral.11\">Apr 13, 11:56pm</Text>\n        <IconButton aria-label=\"Good response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbUp />\n        </IconButton>\n        <IconButton aria-label=\"Bad response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbDown />\n        </IconButton>\n        <IconButton aria-label=\"Copy\" variant=\"ghost\" size=\"xs\">\n          <Icons.ContentCopy />\n        </IconButton>\n      </Stack>\n    </ChatMessage.Meta>\n  </ChatMessage.Root>\n);\n```\n\n### Typing / streaming\n\n`ChatMessage.Typing` shows an animated \"generating…\" indicator as the body's\npayload while a reply streams. Pair it with `isStreaming` on the root, which\nsets `aria-busy`.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" isStreaming>\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <ChatMessage.Typing>\n        <Text color=\"neutral.11\">Agent is typing…</Text>\n      </ChatMessage.Typing>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Senders",
+          "href": "#senders",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tone",
+          "href": "#tone",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions",
+          "href": "#actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Meta",
+          "href": "#meta",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Typing / streaming",
+          "href": "#typing--streaming",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\n`ChatMessage` renders a **single message**. It intentionally does not own the\nsurrounding feed's container semantics or its live region — those are the\nconsumer's to compose. This page documents both halves: what the component does\nfor you, and what you're responsible for wiring up around it.\n\n```jsx live\nconst App = () => (\n  <ChatMessage.Root sender=\"user\" aria-label=\"Message from Ada Lovelace\">\n    <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n    <ChatMessage.Body>\n      <Text>Can you summarise last week's orders?</Text>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Naming a message\n\n`ChatMessage.Root` renders a semantic `<article>` by default (a feed item, per\nthe ARIA APG), so each message is a discrete node in the accessibility tree. An\n`<article>` needs its own accessible name — give it one explicitly with\n`aria-label` or `aria-labelledby`. Don't rely on the avatar to convey who sent\nthe message: it is decorative by default (see below), and even when named, a\nrepeated \"Avatar\" node is a worse accessible name for the message than a label\non the message itself.\n\n### The avatar is decorative by default\n\n`ChatMessage.Avatar` sets `aria-hidden` unless you pass `firstName`/`lastName` or\nan explicit `aria-label`. This is deliberate: an unnamed avatar would otherwise\nannounce a generic, unhelpful label (or leak initials/an icon with no context),\nand the sender is already better conveyed by the message's own accessible name\nand position. Because the avatar is not the accessible-name carrier, it must\nnever be the _only_ place sender identity is expressed — pair it with a named\n`Root`, not instead of one.\n\n### Composing the transcript: `log` vs. `feed`\n\nTwo ARIA container roles fit a message transcript, and they are not\ninterchangeable:\n\n- **`role=\"log\"` with `aria-live=\"polite\"`** (recommended) — a live region that\n  announces appended content, including streamed replies, without re-announcing\n  the whole history on every token. It has no constraint on child roles, so a\n  log can validly contain `<article>` messages, dividers, date separators, or\n  anything else you need.\n- **`role=\"feed\"`** — the ARIA APG's dedicated pattern for scrollable article\n  collections, with built-in \"read next/previous article\" keyboard support. Its\n  trade-off: `feed` has an `aria-required-children` constraint — **every** child\n  must have role `article`. Nesting a `log`, a plain `div` with non-article\n  content, or a date separator inside a `feed` is an accessibility violation,\n  not just a lint warning.\n\nUnless you're building the feed's article-to-article keyboard navigation,\n`role=\"log\"` is the simpler, safer default:\n\n```jsx live\nconst App = () => (\n  <Box\n    role=\"log\"\n    aria-live=\"polite\"\n    aria-label=\"Conversation with the agent\"\n    display=\"flex\"\n    flexDirection=\"column\"\n    gap=\"600\"\n  >\n    <ChatMessage.Root sender=\"user\" aria-label=\"Message from Ada Lovelace\">\n      <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n      <ChatMessage.Body>\n        <Text>Can you summarise last week's orders?</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n\n    <ChatMessage.Root sender=\"agent\" aria-label=\"Message from the agent\">\n      <ChatMessage.Avatar aria-label=\"Agent\">\n        <Icons.AutoAwesome />\n      </ChatMessage.Avatar>\n      <ChatMessage.Body>\n        <Text>Revenue is up 12% week-over-week.</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n  </Box>\n);\n```\n\nIf you do reach for `role=\"feed\"`, keep every direct child an `<article>` —\n`ChatMessage.Root`'s default element already satisfies that — and don't mix in\nnon-article children.\n\n### Streaming state\n\n`isStreaming` on `ChatMessage.Root` sets `aria-busy=\"true\"`, flagging the\nmessage's content as still in flux. It intentionally does **not** create its own\nlive region: a live region mounted at the same time as its content is not\nannounced reliably by every screen reader (the region must already exist before\nits content changes). Keep the live region on your transcript container\n(`role=\"log\"` `aria-live=\"polite\"`, as above) so it persists across messages,\nand use `ChatMessage.Typing`'s `children` for a visible \"Agent is typing…\"\naffordance while streaming.\n\n### Conveying the sender\n\nSender is visually encoded by body color and column position (leading vs.\ntrailing vs. centered) — neither of which reaches assistive technology on its\nown. Per **WCAG 1.4.1 (Use of Color)** and **WCAG 1.3.1 (Info and\nRelationships)**, that information must also be available through another\nchannel: the message's accessible name (`aria-label`/`aria-labelledby`) is that\nchannel. Always name messages rather than depending on their look.\n\n### Reading order\n\nThe root's layout is CSS Grid with explicit per-slot placement, and the `sender`\nvariant swaps which grid column the avatar and body occupy — for\n`sender=\"user\"` the body is visually first and the avatar trails, independent\nof DOM order. Because grid placement doesn't reorder the underlying DOM,\nscreen-reader reading order follows DOM order, not visual order. Keeping the\navatar non-interactive (no focusable content, decorative by default) means this\ndivergence never affects keyboard tab order or gets in the way of reading the\nmessage content; it's only a concern if you make the avatar interactive, which\nisn't a supported pattern.\n\n### Accessibility standards\n\n- **Name, role, value:** `ChatMessage.Root` is an `<article>` by default; always\n  give it an accessible name via `aria-label` or `aria-labelledby`.\n- **Info and relationships:** Sender and status information conveyed visually\n  (body color, column position) must also be exposed through the message's\n  accessible name, not color/position alone.\n- **Use of color:** `tone=\"error\"` is a visual cue only — pair it with visible\n  text describing the failure (as in the error-tone example), not color alone.\n- **Non-text content:** The avatar is decorative (`aria-hidden`) unless named;\n  when named, its label should identify the sender, not restate \"avatar\".\n- **Status messages:** Compose the transcript with `role=\"log\"`\n  `aria-live=\"polite\"` (or a fully-`article`-only `role=\"feed\"`) so new and\n  streamed messages are announced without the consumer building custom\n  live-region logic.\n- **Focus order / no keyboard trap:** The avatar carries no focusable content,\n  so the sender-dependent column swap never disrupts tab order.\n\n### Resources\n\n- [ARIA APG: Feed Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/feed/)\n- [WAI-ARIA: `log` role](https://www.w3.org/TR/wai-aria-1.2/#log)\n- [WCAG 2.1: Use of Color (1.4.1)](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)\n- [WCAG 2.1: Info and Relationships (1.3.1)](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Naming a message",
+          "href": "#naming-a-message",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "The avatar is decorative by default",
+          "href": "#the-avatar-is-decorative-by-default",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composing the transcript: log vs. feed",
+          "href": "#composing-the-transcript-log-vs-feed",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Streaming state",
+          "href": "#streaming-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conveying the sender",
+          "href": "#conveying-the-sender",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Reading order",
+          "href": "#reading-order",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { ChatMessage, type ChatMessageProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`ChatMessage` is a compound component: wrap `ChatMessage.Avatar` and\n`ChatMessage.Body` in `ChatMessage.Root`. `sender` defaults to `\"agent\"`.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Here is the summary you asked for.</Text>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n## Usage examples\n\n### User and agent messages\n\n`sender=\"user\"` trails the avatar and uses the `colorPalette.2` surface\n(`primary` by default);\n`sender=\"agent\"` (the default) leads with the avatar. Name a message with\n`aria-label` (or `aria-labelledby`) — the avatar itself stays decorative unless\nyou give it `firstName`/`lastName` or its own `aria-label`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"600\">\n    <ChatMessage.Root sender=\"user\" aria-label=\"Message from Ada Lovelace\">\n      <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n      <ChatMessage.Body>\n        <Text>Can you summarise last week's orders for me?</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n    <ChatMessage.Root sender=\"agent\" aria-label=\"Message from the agent\">\n      <ChatMessage.Avatar aria-label=\"Agent\">\n        <Icons.AutoAwesome />\n      </ChatMessage.Avatar>\n      <ChatMessage.Body>\n        <Text>Revenue is up 12% week-over-week.</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n  </Stack>\n);\n```\n\n### System notices\n\nSystem notices and dividers aren't standardized in this release. There's no\ndedicated Nimbus component for them — because `ChatMessageList` is\ncontent-agnostic, a consumer renders their own centered, subdued content inside a\n`ChatMessageList.Item`.\n\n```jsx live-dev\nconst App = () => (\n  <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n    Conversation history was cleared.\n  </Box>\n);\n```\n\n### Tool output\n\nTool / function-call output is content _inside_ an `agent` message (there is no\n`sender=\"tool\"`) — for example a JSON code block rendered by `Markdown`.\n\n````jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Markdown>\n        {[\"```json\", '{ \"orders\": 42, \"revenue\": 12890 }', \"```\"].join(\"\\n\")}\n      </Markdown>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n````\n\n### Error tone\n\n`tone=\"error\"` is orthogonal to `sender` — it tints the body to flag a failed\ngeneration, so an `agent` message can be both `sender=\"agent\"` and\n`tone=\"error\"`.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" tone=\"error\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Something went wrong generating this response.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Retry\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Actions\n\n`ChatMessage.Actions` renders a right-aligned button row inside the body.\nPlace it as the last child of `ChatMessage.Body` so it pins to the bottom of\nthe card.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>I drafted the date range for your report. Approve to apply.</Text>\n      <ChatMessage.Actions>\n        <Button variant=\"outline\" colorPalette=\"primary\">\n          Save as draft\n        </Button>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          Approve\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Meta: timestamp and reactions\n\n`ChatMessage.Meta` renders a `space-between` row below the body — a trust link\non the start side, a timestamp and reaction `IconButton`s on the end side. With\na single child, `space-between` leaves it at the start of the row.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Text>Here is the summary you asked for.</Text>\n    </ChatMessage.Body>\n    <ChatMessage.Meta>\n      <Link href=\"#\">How was this generated?</Link>\n      <Stack direction=\"row\" alignItems=\"center\" gap=\"100\">\n        <Text color=\"neutral.11\">Apr 13, 11:56pm</Text>\n        <IconButton aria-label=\"Good response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbUp />\n        </IconButton>\n        <IconButton aria-label=\"Bad response\" variant=\"ghost\" size=\"xs\">\n          <Icons.ThumbDown />\n        </IconButton>\n        <IconButton aria-label=\"Copy\" variant=\"ghost\" size=\"xs\">\n          <Icons.ContentCopy />\n        </IconButton>\n      </Stack>\n    </ChatMessage.Meta>\n  </ChatMessage.Root>\n);\n```\n\n### Markdown payload\n\nThe body's payload is arbitrary content — render a `Markdown` string for\nformatted replies (lists, links, inline code, code blocks).\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\">\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <Markdown>\n        {[\n          \"Here's what I found:\",\n          \"\",\n          \"- **Revenue** is up 12% week-over-week\",\n          \"- Top SKU: `ABC-123`\",\n          \"\",\n          \"See the [full report](#) for details.\",\n        ].join(\"\\n\")}\n      </Markdown>\n      <ChatMessage.Actions>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          Approve\n        </Button>\n      </ChatMessage.Actions>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Streaming replies\n\nWhile a reply generates, set `isStreaming` on `ChatMessage.Root` (which sets\n`aria-busy`). Before the first token, render `ChatMessage.Typing` as the\nbody's payload; once text starts streaming, render it with\n`<Markdown isStreaming>` — the `Markdown` component owns safe incremental\nrendering (completing unterminated markdown, re-parsing only the final block per\ntoken), so `ChatMessage` never re-implements streamed-text rendering itself.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessage.Root sender=\"agent\" isStreaming>\n    <ChatMessage.Avatar>\n      <Icons.AutoAwesome />\n    </ChatMessage.Avatar>\n    <ChatMessage.Body>\n      <ChatMessage.Typing>\n        <Text color=\"neutral.11\">Agent is typing…</Text>\n      </ChatMessage.Typing>\n    </ChatMessage.Body>\n  </ChatMessage.Root>\n);\n```\n\n### Accessible transcript (recommended composition)\n\n`ChatMessage` renders one message; you compose the transcript. Wrap the messages\nin a `role=\"log\"` `aria-live=\"polite\"` container so streamed replies are\nannounced without per-token spam, and name each message for assistive tech. See\nthe Accessibility tab for the full rationale, including why `role=\"feed\"` is not\na drop-in replacement here.\n\n```jsx live-dev\nconst App = () => (\n  <Box\n    role=\"log\"\n    aria-live=\"polite\"\n    aria-label=\"Conversation with the agent\"\n    display=\"flex\"\n    flexDirection=\"column\"\n    gap=\"600\"\n  >\n    <ChatMessage.Root sender=\"user\" aria-label=\"Message from Ada Lovelace\">\n      <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n      <ChatMessage.Body>\n        <Text>Can you summarise last week's orders?</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n\n    <ChatMessage.Root sender=\"agent\" aria-label=\"Message from the agent\">\n      <ChatMessage.Avatar aria-label=\"Agent\">\n        <Icons.AutoAwesome />\n      </ChatMessage.Avatar>\n      <ChatMessage.Body>\n        <Text>Revenue is up 12% week-over-week.</Text>\n      </ChatMessage.Body>\n    </ChatMessage.Root>\n  </Box>\n);\n```\n\n## Component requirements\n\n- Render `ChatMessage.Avatar` and `ChatMessage.Body` as direct children of\n  `ChatMessage.Root`; add `ChatMessage.Meta` as a sibling after the body for a\n  below-body row.\n- Nest `ChatMessage.Actions` inside `ChatMessage.Body`, as the last child, so\n  it pins to the bottom of the card.\n- Non-message interjections (system notices, dividers) aren't standardized in\n  this release — render your own centered, subdued content inside a\n  `ChatMessageList.Item`; it is not a `sender` variant.\n- `ChatMessage.Root` renders a semantic `<article>` by default; override the\n  element with `as` (for example `as=\"li\"` inside a list) when composing a\n  transcript that needs a different tag.\n\n## Accessibility\n\n`ChatMessage` is a single-message primitive — it does not own the surrounding\nfeed's container semantics or live region. In brief: name each message with\n`aria-label`/`aria-labelledby`, keep the avatar decorative unless you give it a\nreal name, and set `isStreaming` for streamed replies (it sets `aria-busy`). See\nthe **Accessibility tab** for the full guidance on composing an accessible\ntranscript.\n\n## API reference\n\n<PropsTable id=\"ChatMessage\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nChatMessage within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic rendering\n\nCompose a single agent message from the ChatMessage parts.\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  ChatMessage,\n  NimbusProvider,\n  Text,\n  Button,\n  Link,\n  Box,\n} from \"@commercetools/nimbus\";\nimport { AutoAwesome } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ChatMessage - Basic rendering\", () => {\n  it(\"composes an agent message from its parts\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender=\"agent\">\n          <ChatMessage.Avatar>\n            <AutoAwesome />\n          </ChatMessage.Avatar>\n          <ChatMessage.Body>\n            <Text>Here is the summary you asked for.</Text>\n          </ChatMessage.Body>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"Here is the summary you asked for.\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Senders and tone\n\nEach sender lays out differently; `tone=\"error\"` flags a failed generation.\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  ChatMessage,\n  NimbusProvider,\n  Text,\n  Button,\n  Link,\n  Box,\n} from \"@commercetools/nimbus\";\nimport { AutoAwesome } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ChatMessage - Senders and tone\", () => {\n  it.each([\"user\", \"agent\"] as const)(\"renders the %s sender\", (sender) => {\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender={sender} data-testid=\"body\">\n          <ChatMessage.Body>\n            <Text>{sender} message</Text>\n          </ChatMessage.Body>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"body\")).toHaveTextContent(`${sender} message`);\n  });\n\n  it(\"renders an error-toned agent message with a retry action\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender=\"agent\" tone=\"error\" data-testid=\"body\">\n          <ChatMessage.Body>\n            <Text>Something went wrong.</Text>\n            <ChatMessage.Actions>\n              <Button variant=\"outline\">Retry</Button>\n            </ChatMessage.Actions>\n          </ChatMessage.Body>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"body\")).toHaveTextContent(\n      \"Something went wrong.\"\n    );\n    expect(screen.getByRole(\"button\", { name: \"Retry\" })).toBeInTheDocument();\n  });\n});\n```\n\n### Actions and meta\n\nWire action buttons to your own handlers; the meta row sits below the body.\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  ChatMessage,\n  NimbusProvider,\n  Text,\n  Button,\n  Link,\n  Box,\n} from \"@commercetools/nimbus\";\nimport { AutoAwesome } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ChatMessage - Actions and meta\", () => {\n  it(\"wires action buttons to consumer handlers\", async () => {\n    const user = userEvent.setup();\n    const onApprove = vi.fn();\n    const onDismiss = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender=\"agent\">\n          <ChatMessage.Body>\n            <Text>Apply the suggested changes?</Text>\n            <ChatMessage.Actions>\n              <Button variant=\"outline\" onPress={onDismiss}>\n                Dismiss\n              </Button>\n              <Button variant=\"solid\" onPress={onApprove}>\n                Approve\n              </Button>\n            </ChatMessage.Actions>\n          </ChatMessage.Body>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Approve\" }));\n    expect(onApprove).toHaveBeenCalledTimes(1);\n    expect(onDismiss).not.toHaveBeenCalled();\n\n    await user.click(screen.getByRole(\"button\", { name: \"Dismiss\" }));\n    expect(onDismiss).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"renders meta content below the body\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender=\"agent\">\n          <ChatMessage.Body>\n            <Text>Done.</Text>\n          </ChatMessage.Body>\n          <ChatMessage.Meta>\n            <Link href=\"#\">How was this generated?</Link>\n            <Text>Apr 13, 11:56pm</Text>\n          </ChatMessage.Meta>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"link\", { name: \"How was this generated?\" })\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"Apr 13, 11:56pm\")).toBeInTheDocument();\n  });\n});\n```\n\n### Streaming replies\n\nWhile generating, render ChatMessage.Typing and set isStreaming.\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  ChatMessage,\n  NimbusProvider,\n  Text,\n  Button,\n  Link,\n  Box,\n} from \"@commercetools/nimbus\";\nimport { AutoAwesome } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ChatMessage - Streaming\", () => {\n  it(\"shows a typing affordance while streaming\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessage.Root sender=\"agent\" isStreaming>\n          <ChatMessage.Avatar>\n            <AutoAwesome />\n          </ChatMessage.Avatar>\n          <ChatMessage.Body>\n            <ChatMessage.Typing>\n              <Text>Agent is typing…</Text>\n            </ChatMessage.Typing>\n          </ChatMessage.Body>\n        </ChatMessage.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Agent is typing…\")).toBeInTheDocument();\n  });\n});\n```\n\n### Accessible transcript\n\nChatMessage renders one message; name each message and compose several inside a live log region.\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  ChatMessage,\n  NimbusProvider,\n  Text,\n  Button,\n  Link,\n  Box,\n} from \"@commercetools/nimbus\";\nimport { AutoAwesome } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ChatMessage - Accessible transcript\", () => {\n  it(\"composes several named messages into a transcript\", () => {\n    render(\n      <NimbusProvider>\n        <Box role=\"log\" aria-live=\"polite\" aria-label=\"Conversation\">\n          <ChatMessage.Root\n            sender=\"user\"\n            aria-label=\"Message from Ada Lovelace\"\n          >\n            <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n            <ChatMessage.Body>\n              <Text>Summarise last week's orders?</Text>\n            </ChatMessage.Body>\n          </ChatMessage.Root>\n\n          <ChatMessage.Root sender=\"agent\" aria-label=\"Message from the agent\">\n            <ChatMessage.Avatar>\n              <AutoAwesome />\n            </ChatMessage.Avatar>\n            <ChatMessage.Body>\n              <Text>Revenue is up 12%.</Text>\n            </ChatMessage.Body>\n          </ChatMessage.Root>\n        </Box>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"Summarise last week's orders?\")\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"Revenue is up 12%.\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-chatmessage--docs)\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": "User and agent messages",
+          "href": "#user-and-agent-messages",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "System notices",
+          "href": "#system-notices",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tool output",
+          "href": "#tool-output",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Error tone",
+          "href": "#error-tone",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions",
+          "href": "#actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Meta: timestamp and reactions",
+          "href": "#meta-timestamp-and-reactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Markdown payload",
+          "href": "#markdown-payload",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Streaming replies",
+          "href": "#streaming-replies",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible transcript (recommended composition)",
+          "href": "#accessible-transcript-recommended-composition",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Senders and tone",
+          "href": "#senders-and-tone",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions and meta",
+          "href": "#actions-and-meta",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Streaming replies",
+          "href": "#streaming-replies-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible transcript",
+          "href": "#accessible-transcript",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}