@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-layout-splitter.json

@@ -136,10 +136,10 @@
       }
     ]
   },
-  "mdx": "\n## Overview\n\nThe Splitter lets people resize two adjacent regions by dragging the handle\nbetween them — a sidebar next to a content area, a list next to a detail view,\nan editor next to a preview. It is intentionally a **two-pane** primitive: the\nboundary is a single position, which keeps the interaction predictable and the\naccessibility model clean. Layouts with three or more regions are composed by\n**nesting** one Splitter inside another's pane.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n- [Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1793-8790&m=dev)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n\n## Variables\n\nGet familiar with the visual options.\n\n### Orientation\n\n`horizontal` (default) places the panes side by side with a vertical handle;\n`vertical` stacks them with a horizontal handle. The handle is keyboard operable\nin both orientations.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"horizontal\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Left</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n            <Text>Right</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Top</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Bottom</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Collapse\n\nThe aside can be made collapsible so a region — usually a sidebar or panel — can\nbe hidden and brought back. Collapsing animates the boundary to the aside's\ncollapsed size: fully hidden by default, or a thin rail when a collapsed size is\nset. The freed space goes to the main pane. Surface a visible control (a button)\nto toggle it; on the handle, Enter toggles collapse and double-click restores\nthe default split.\n\n```jsx live\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show nav\" : \"Hide nav\"}\n      </Button>\n      <Box height=\"240px\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={12}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Nav</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n## Guidelines\n\n### Best practices\n\n- **Two panes per Splitter.** Nest splitters for layouts with three or more\n  regions; each nested splitter is independently focusable and announced to\n  assistive technology as its own widget.\n- **Bound the aside.** Set `minSize` and `maxSize` so dragging can't shrink the\n  aside — or, via `maxSize`, the main pane — below its usable content width. Pair\n  the bounds with content that scrolls inside the pane.\n- **Use collapsing for chrome.** A navigation or panel the user may want hidden\n  should be the `collapsible` aside; surface a visible control (a button) for the\n  mouse, since double-click is reserved for restoring the default split.\n- **Persist the layout** when the split is part of the user's workflow, so it\n  survives across sessions.\n\n### When to use\n\n> [!TIP]\\\n> Use when\n\n- Side-by-side content the user benefits from resizing themselves.\n- App shells that pair a flexible navigation with a main content area.\n- Master/detail views where the relative split is part of the workflow.\n\n### When not to use\n\n> [!CAUTION]\\\n> When not to use\n\n- Static two-column layouts — use a flex or grid layout directly.\n- Narrow, mobile-first viewports — dragging is awkward; use a Drawer or stack\n  the regions vertically.\n- More than two peer regions in one splitter — nest splitters instead.\n",
+  "mdx": "\n## Overview\n\nThe Splitter lets people resize two adjacent regions by dragging the handle\nbetween them — a sidebar next to a content area, a list next to a detail view,\nan editor next to a preview. It is intentionally a **two-pane** primitive: the\nboundary is a single position, which keeps the interaction predictable and the\naccessibility model clean. Layouts with three or more regions are composed by\n**nesting** one Splitter inside another's pane.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n- [Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1793-8790&m=dev)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n\n## Variables\n\nGet familiar with the visual options.\n\n### Orientation\n\n`horizontal` (default) places the panes side by side with a vertical handle;\n`vertical` stacks them with a horizontal handle. The handle is keyboard operable\nin both orientations.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"horizontal\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Left</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n            <Text>Right</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Top</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Bottom</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Collapse\n\nThe aside can be made collapsible so a region — usually a sidebar or panel — can\nbe hidden and brought back. Collapsing animates the boundary to the aside's\ncollapsed size: fully hidden by default, or a thin rail when a collapsed size is\nset. The freed space goes to the main pane.\n\nWhile **expanded**, the handle resizes (drag, arrows, Home/End), Enter collapses,\nand double-click restores the default split. While **collapsed**, the handle is a\n**keyboard-only toggle**: Enter expands it again. It advertises no mouse-resize\naffordances — there is no hover track and double-click does nothing — because\nresizing is locked until the aside is reopened.\n\nBecause `collapsedSize` defaults to `0` (the aside fully disappears, pinning the\nhandle to the container edge), a collapsed aside has **no visible mouse target to\nreopen it**. Always surface your own visible control — a button outside the\nsplitter that drives the `collapsed` prop (as below), or a trigger near the\ncollapsed aside — so mouse users can expand it.\n\n```jsx live\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show nav\" : \"Hide nav\"}\n      </Button>\n      <Box height=\"240px\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={12}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Nav</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n## Guidelines\n\n### Best practices\n\n- **Two panes per Splitter.** Nest splitters for layouts with three or more\n  regions; each nested splitter is independently focusable and announced to\n  assistive technology as its own widget.\n- **Bound the aside.** Set `minSize` and `maxSize` so dragging can't shrink the\n  aside — or, via `maxSize`, the main pane — below its usable content width. Pair\n  the bounds with content that scrolls inside the pane.\n- **Use collapsing for chrome.** A navigation or panel the user may want hidden\n  should be the `collapsible` aside; surface a visible control (a button) for the\n  mouse, since double-click is reserved for restoring the default split.\n- **Persist the layout** when the split is part of the user's workflow, so it\n  survives across sessions.\n\n### When to use\n\n> [!TIP]\\\n> Use when\n\n- Side-by-side content the user benefits from resizing themselves.\n- App shells that pair a flexible navigation with a main content area.\n- Master/detail views where the relative split is part of the workflow.\n\n### When not to use\n\n> [!CAUTION]\\\n> When not to use\n\n- Static two-column layouts — use a flex or grid layout directly.\n- Narrow, mobile-first viewports — dragging is awkward; use a Drawer or stack\n  the regions vertically.\n- More than two peer regions in one splitter — nest splitters instead.\n",
   "views": {
     "overview": {
-      "mdx": "\n## Overview\n\nThe Splitter lets people resize two adjacent regions by dragging the handle\nbetween them — a sidebar next to a content area, a list next to a detail view,\nan editor next to a preview. It is intentionally a **two-pane** primitive: the\nboundary is a single position, which keeps the interaction predictable and the\naccessibility model clean. Layouts with three or more regions are composed by\n**nesting** one Splitter inside another's pane.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n- [Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1793-8790&m=dev)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n\n## Variables\n\nGet familiar with the visual options.\n\n### Orientation\n\n`horizontal` (default) places the panes side by side with a vertical handle;\n`vertical` stacks them with a horizontal handle. The handle is keyboard operable\nin both orientations.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"horizontal\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Left</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n            <Text>Right</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Top</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Bottom</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Collapse\n\nThe aside can be made collapsible so a region — usually a sidebar or panel — can\nbe hidden and brought back. Collapsing animates the boundary to the aside's\ncollapsed size: fully hidden by default, or a thin rail when a collapsed size is\nset. The freed space goes to the main pane. Surface a visible control (a button)\nto toggle it; on the handle, Enter toggles collapse and double-click restores\nthe default split.\n\n```jsx live\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show nav\" : \"Hide nav\"}\n      </Button>\n      <Box height=\"240px\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={12}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Nav</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n## Guidelines\n\n### Best practices\n\n- **Two panes per Splitter.** Nest splitters for layouts with three or more\n  regions; each nested splitter is independently focusable and announced to\n  assistive technology as its own widget.\n- **Bound the aside.** Set `minSize` and `maxSize` so dragging can't shrink the\n  aside — or, via `maxSize`, the main pane — below its usable content width. Pair\n  the bounds with content that scrolls inside the pane.\n- **Use collapsing for chrome.** A navigation or panel the user may want hidden\n  should be the `collapsible` aside; surface a visible control (a button) for the\n  mouse, since double-click is reserved for restoring the default split.\n- **Persist the layout** when the split is part of the user's workflow, so it\n  survives across sessions.\n\n### When to use\n\n> [!TIP]\\\n> Use when\n\n- Side-by-side content the user benefits from resizing themselves.\n- App shells that pair a flexible navigation with a main content area.\n- Master/detail views where the relative split is part of the workflow.\n\n### When not to use\n\n> [!CAUTION]\\\n> When not to use\n\n- Static two-column layouts — use a flex or grid layout directly.\n- Narrow, mobile-first viewports — dragging is awkward; use a Drawer or stack\n  the regions vertically.\n- More than two peer regions in one splitter — nest splitters instead.\n",
+      "mdx": "\n## Overview\n\nThe Splitter lets people resize two adjacent regions by dragging the handle\nbetween them — a sidebar next to a content area, a list next to a detail view,\nan editor next to a preview. It is intentionally a **two-pane** primitive: the\nboundary is a single position, which keeps the interaction predictable and the\naccessibility model clean. Layouts with three or more regions are composed by\n**nesting** one Splitter inside another's pane.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n- [Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1793-8790&m=dev)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n\n## Variables\n\nGet familiar with the visual options.\n\n### Orientation\n\n`horizontal` (default) places the panes side by side with a vertical handle;\n`vertical` stacks them with a horizontal handle. The handle is keyboard operable\nin both orientations.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"horizontal\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Left</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n            <Text>Right</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"240px\" width=\"320px\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Top</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Bottom</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Collapse\n\nThe aside can be made collapsible so a region — usually a sidebar or panel — can\nbe hidden and brought back. Collapsing animates the boundary to the aside's\ncollapsed size: fully hidden by default, or a thin rail when a collapsed size is\nset. The freed space goes to the main pane.\n\nWhile **expanded**, the handle resizes (drag, arrows, Home/End), Enter collapses,\nand double-click restores the default split. While **collapsed**, the handle is a\n**keyboard-only toggle**: Enter expands it again. It advertises no mouse-resize\naffordances — there is no hover track and double-click does nothing — because\nresizing is locked until the aside is reopened.\n\nBecause `collapsedSize` defaults to `0` (the aside fully disappears, pinning the\nhandle to the container edge), a collapsed aside has **no visible mouse target to\nreopen it**. Always surface your own visible control — a button outside the\nsplitter that drives the `collapsed` prop (as below), or a trigger near the\ncollapsed aside — so mouse users can expand it.\n\n```jsx live\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show nav\" : \"Hide nav\"}\n      </Button>\n      <Box height=\"240px\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={12}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Nav</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n## Guidelines\n\n### Best practices\n\n- **Two panes per Splitter.** Nest splitters for layouts with three or more\n  regions; each nested splitter is independently focusable and announced to\n  assistive technology as its own widget.\n- **Bound the aside.** Set `minSize` and `maxSize` so dragging can't shrink the\n  aside — or, via `maxSize`, the main pane — below its usable content width. Pair\n  the bounds with content that scrolls inside the pane.\n- **Use collapsing for chrome.** A navigation or panel the user may want hidden\n  should be the `collapsible` aside; surface a visible control (a button) for the\n  mouse, since double-click is reserved for restoring the default split.\n- **Persist the layout** when the split is part of the user's workflow, so it\n  survives across sessions.\n\n### When to use\n\n> [!TIP]\\\n> Use when\n\n- Side-by-side content the user benefits from resizing themselves.\n- App shells that pair a flexible navigation with a main content area.\n- Master/detail views where the relative split is part of the workflow.\n\n### When not to use\n\n> [!CAUTION]\\\n> When not to use\n\n- Static two-column layouts — use a flex or grid layout directly.\n- Narrow, mobile-first viewports — dragging is awkward; use a Drawer or stack\n  the regions vertically.\n- More than two peer regions in one splitter — nest splitters instead.\n",
       "toc": [
         {
           "value": "Overview",
@@ -277,7 +277,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Splitter, type SplitterRootProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`Splitter.Root` wraps one `Splitter.Aside` and one `Splitter.Main` with a\n`Splitter.Handle` between them. `Splitter.Aside` is the configurable pane you\nsize; `Splitter.Main` takes the remaining space. The initial split is set with\n`defaultSize` — a single percentage that always refers to the aside (the main\npane is `100 − size`).\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} minSize={15} maxSize={75}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>\n            Drag the handle to resize. Tab to it, then use the arrow keys.\n          </Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n## Usage examples\n\n### Orientation\n\n`orientation=\"vertical\"` stacks the panes and makes ArrowUp / ArrowDown the\nactive keys. The handle's `aria-orientation` reflects this (W3C separator\nsemantics describe the boundary axis, not the layout axis).\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n          <Text>Aside</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Aside constraints\n\n`minSize` and `maxSize` bound the single aside dimension. `minSize` (default\n`0`) is the aside's floor; `maxSize` (default `100`) caps how far the aside can\ngrow — which in turn fixes the main pane's floor at `100 − maxSize`. Because\nthere is one boundary, this single `[minSize, maxSize]` window on the aside\nfully describes both sides; there is no main-specific prop.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} minSize={15} maxSize={75}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (min 15, max 75)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main (floor 25)</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Collapsible aside\n\nSet `collapsible` to let the aside collapse, and control its collapsed state\nwith the boolean `collapsed`. Because collapse is plain controlled state, any\ncontrol can drive it; Enter on the focused handle toggles it too.\n`onCollapsedChange` fires on every transition. Only the aside collapses.\n\nWhile the aside is collapsed the handle can't be resized (drag and the arrow\nkeys are inactive) — a collapsed aside sits below its `minSize`, so a resize\ncould only snap. Reopen it with the control, Enter, or a double-click; the\ncollapsed state holds until you explicitly leave it.\n\n```jsx live-dev\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show aside\" : \"Hide aside\"}\n      </Button>\n      <Box height=\"2xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={10}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Collapsing to a rail\n\nCollapse is a two-tier model. `minSize` is the floor for _dragging_ and the\narrow keys; `collapsedSize` is a distinct discrete state that collapse snaps to,\nbelow `minSize`. It defaults to `0` (the aside hides entirely) — set it to leave\na thin rail behind, e.g. an icon strip the user can click to expand.\n\n```jsx live-dev\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Expand aside\" : \"Collapse aside to a rail\"}\n      </Button>\n      <Box height=\"2xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={15}\n          maxSize={80}\n          collapsible\n          collapsedSize={6}\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Uncontrolled collapse\n\nWhen you don't need to drive collapse from outside the splitter, seed the\ninitial collapsed state with `defaultCollapsed` and let the splitter own it.\nEnter on the handle toggles it from there, and double-click restores the default\nsplit.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root\n      defaultSize={30}\n      minSize={10}\n      maxSize={80}\n      collapsible\n      defaultCollapsed\n    >\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (starts collapsed)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Tab to the handle and press Enter to toggle</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Keyboard step\n\nArrow keys move the boundary by `keyboardStep` percentage points (default `5`);\nHome / End jump it to the bounds. Accepts floats for finer control.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} keyboardStep={10}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>\n            Tab to the handle — each arrow press moves the boundary 10%\n          </Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Restoring the default split\n\nDouble-click the handle to restore the boundary to the sizes resolved on mount.\nSet `isDoubleClickDisabled` to turn that off; drag and keyboard stay active.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root defaultSize={50}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Drag, then double-click the handle to restore</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\" />\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root defaultSize={50} isDoubleClickDisabled>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Double-click restore disabled</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\" />\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Disabled state\n\n`isDisabled` makes the whole splitter non-interactive: the handle leaves the tab\norder, gets `aria-disabled`, and ignores drag, keyboard, and collapse input.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root isDisabled defaultSize={30}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Persistence\n\nSize is uncontrolled by default, so persist it in your app with any storage:\nhydrate `defaultSize` from stored state and write the settled value back in\n`onSizeChangeEnd` (it fires once per settled **resize** — drag end, each\nkeypress, double-click restore — so no debouncing is needed; collapse/expand are\nsignalled by `onCollapsedChange`, not here). A\nsingle `number` round-trips: the value `onSizeChangeEnd` emits is exactly the\nshape `defaultSize` accepts. Collapse persists through its controlled boolean\nstate.\n\n```tsx\n// `useLocalStorage` is any storage hook of your choosing.\nconst [size, setSize] = useLocalStorage(\"ide-layout\", 30);\nconst [collapsed, setCollapsed] = useLocalStorage(\"ide-collapsed\", false);\n\n<Splitter.Root\n  defaultSize={size}\n  onSizeChangeEnd={setSize}\n  minSize={10}\n  maxSize={80}\n  collapsible\n  collapsed={collapsed}\n  onCollapsedChange={setCollapsed}\n>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n`onSizeChange` (live, every drag tick ~60Hz) is also available when you need a\nreal-time read-out; prefer `onSizeChangeEnd` for persistence.\n\n### Controlled size\n\nPass `size` instead of `defaultSize` to drive the layout from outside — useful\nfor responsive layouts that swap the proportion per breakpoint, since external\nchanges apply in place (no remount, so pane content keeps its scroll and focus).\nControl is settled, not live: drag and keyboard stay smooth from internal state\nand report once via `onSizeChangeEnd`. Wire that callback and feed the value\nback, or the splitter keeps the last interactive size and behaves as\nuncontrolled from then on.\n\n```tsx\nconst [size, setSize] = useState(30);\n\n<Splitter.Root size={size} onSizeChangeEnd={setSize}>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n### Pixel-precise sizes\n\nThe aside percentage carries full float precision end-to-end (nothing in the\nsize pipeline is rounded — only the handle's `aria-valuenow` is rounded, for\nassistive technology). To land on an exact pixel at a known container width,\npass the computed float — `250px` in an `800px` container is `31.25`.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={31.25}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>31.25%</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>68.75%</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Responsive pixel & token sizes with `useResponsiveSplitterSizes`\n\n`Splitter.Root` is percentage-native — it has no pixel code path. When you'd\nrather think in pixels (a fixed-width sidebar, an icon rail) or size per device,\nreach for the companion hook `useResponsiveSplitterSizes`. It is a **pixel/token\n→ percentage translator**: it measures the splitter's container, converts your\nconfig to the percentage the component wants, drives the controlled `size`\nchannel, and persists the result — all without the component gaining a pixel\npath.\n\nSpread its `rootProps` onto `Splitter.Root` and attach the `ref` it returns (the\n`ref` is required — the hook measures the container through it):\n\n```tsx\nconst { rootProps } = useResponsiveSplitterSizes({\n  orientation: \"horizontal\",\n  persistKey: \"app:main-splitter\",\n  size: \"xs\",          // 320px — size tokens resolve to pixels\n  minSize: \"3xs\",      // 224px\n  maxSize: \"lg\",       // 512px\n});\n\n<Splitter.Root {...rootProps} collapsible>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n**Units.** A value is a `number` (pixels), a size token (`3xs`–`8xl` or\n`breakpoint-sm`…`breakpoint-2xl`, resolving to pixels), or a `\"N%\"` string\n(passed through untranslated). Note the contrast with `Splitter.Root`'s own\n`size` / `minSize` / … props, which are **percentages**: through the hook, a\nbare number means pixels. Because the hook owns the full facade (`size` plus\n`minSize` / `maxSize` / `collapsedSize`), you don't hand-write percentages on\nthe root when you use it.\n\n**Responsive by container width.** Any dimension can be a map keyed by container\n**min-width thresholds** (pixels or tokens) — a min-width cascade resolved\nagainst the splitter's own width, not the viewport. The largest threshold `≤`\nthe measured width wins; the smallest entry also applies below it.\n\n```tsx\nconst { rootProps } = useResponsiveSplitterSizes({\n  size: { 0: \"xs\", \"breakpoint-md\": \"30%\" }, // \"xs\" (320px) below 768px, 30% above\n});\n```\n\n**Persistence.** Pass a `persistKey` (and optionally a `storage` adapter,\ndefaulting to `localStorage`) and the hook stores the settled size **in pixels**\nper band, so a dragged `320px` re-pins to `320px` across reloads and container\nresizes. `collapsedSize` is static config and is never persisted; the latest\nexpanded size survives collapse and expand.\n\n### Three or more regions\n\nThe Splitter is two-pane by design. For additional regions, nest a Splitter\ninside a pane's children; each splitter owns its own state independently. The\ninner aside can sit on either side of its main pane — here it trails as a right\npanel.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={25}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (outer)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Splitter.Root defaultSize={35}>\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n          <Splitter.Handle />\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n              <Text>Aside (inner)</Text>\n            </Box>\n          </Splitter.Aside>\n        </Splitter.Root>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n## Common patterns\n\n### IDE-style layout\n\nThe most common real-world composition: a persisted split (`defaultSize` +\n`onSizeChangeEnd`) with a `collapsible` aside that snaps to a rail\n(`collapsedSize`), driven by both a toolbar button and the handle, plus aside\nbounds and a specific handle label.\n\n```jsx live-dev\nconst App = () => {\n  const [size, setSize] = useState(22);\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show aside\" : \"Hide aside\"}\n      </Button>\n      <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={size}\n          onSizeChangeEnd={setSize}\n          minSize={15}\n          maxSize={70}\n          collapsible\n          collapsedSize={4}\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle aria-label=\"Resize aside\" />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Vertical with persistence\n\nA vertical split with a persisted boundary and aside bounds so neither region\ncollapses to nothing while dragging.\n\n```jsx live-dev\nconst App = () => {\n  const [size, setSize] = useState(60);\n\n  return (\n    <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root\n        orientation=\"vertical\"\n        defaultSize={size}\n        onSizeChangeEnd={setSize}\n        minSize={25}\n        maxSize={80}\n      >\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Aside</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Main</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  );\n};\n```\n\n## Component requirements\n\n### Structure\n\n- `Splitter.Root` must contain exactly one `Splitter.Aside` and one\n  `Splitter.Main` with one `Splitter.Handle` between them; a development-time\n  warning is emitted otherwise. The aside may be placed before or after the main\n  pane (a leading or trailing panel) — `size` always refers to the aside.\n- All sizing and collapse configuration (`defaultSize` / `size`, `minSize`,\n  `maxSize`, `collapsible`, `collapsedSize`) lives on `Splitter.Root`. Panes\n  take only their content and an optional `id` for analytics/testing — nothing\n  is configured on the pane itself.\n\n## Accessibility\n\nThe Splitter handles the W3C window-splitter semantics internally: the handle is\n`role=\"separator\"` with `aria-orientation`, `aria-valuenow` / `aria-valuemin` /\n`aria-valuemax`, `aria-valuetext`, and `aria-controls` pointing at the leading\npane. For the full conformance details, see the Accessibility tab.\n\n#### Labeling\n\nThe handle ships a localized default `aria-label` (\"Resize panes\"); override it\nper handle with `aria-label` or `aria-labelledby` for a more specific label:\n\n```tsx\n<Splitter.Handle aria-label={msg.format(\"resizeAside\")} />\n```\n\n#### Persistent ID\n\nIf your use case requires tracking and analytics, it is good practice to add a\n**persistent**, **unique** id to the handle:\n\n```tsx\nconst PERSISTENT_ID = \"ide-layout-splitter-handle\";\n\nexport const Example = () => (\n  <Splitter.Root defaultSize={30}>\n    <Splitter.Aside>…</Splitter.Aside>\n    <Splitter.Handle id={PERSISTENT_ID} />\n    <Splitter.Main>…</Splitter.Main>\n  </Splitter.Root>\n);\n```\n\n#### Keyboard navigation\n\nWhen the handle has focus:\n\n- `Tab` / `Shift+Tab`: Move focus to/from the handle (in DOM order).\n- `ArrowLeft` / `ArrowRight` (horizontal) or `ArrowUp` / `ArrowDown` (vertical):\n  Move the boundary by `keyboardStep` percentage points (inactive while the\n  aside is collapsed).\n- `Home` / `End`: Jump the boundary to the aside's minimum / maximum (inactive\n  while the aside is collapsed).\n- `Enter`: Toggle collapse of the aside (when `collapsible`).\n\n## API reference\n\n<PropsTable id=\"Splitter\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Splitter\nin your application. As the component's internal functionality is already tested\nby Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering\n\nMinimal Splitter — a configurable aside and a main pane —\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - Basic rendering\", () => {\n  it(\"renders an aside, a main pane, and one handle\", async () => {\n    render(\n      <NimbusProvider>\n        <Splitter.Root defaultSize={30}>\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>Main</Splitter.Main>\n        </Splitter.Root>\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    expect(handle).toBeInTheDocument();\n  });\n});\n```\n\n### Persistence with any storage\n\nHydrate `defaultSize` from stored state and persist the\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - persistence\", () => {\n  it(\"hydrates from the stored size on first render\", async () => {\n    // Stand-in for a `useLocalStorage`-style hook seeded from storage.\n    const Demo = () => {\n      const [size, setSize] = useState(25);\n      return (\n        <Splitter.Root\n          defaultSize={size}\n          onSizeChangeEnd={setSize}\n          minSize={5}\n          maxSize={95}\n        >\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>Main</Splitter.Main>\n        </Splitter.Root>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(25);\n    });\n  });\n});\n```\n\n### Controlled size from anywhere\n\nDrive the layout with the `size` prop and update it from\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - controlled size\", () => {\n  it(\"reflects an external size change in place\", async () => {\n    const user = userEvent.setup();\n    const Demo = () => {\n      const [size, setSize] = useState(30);\n      return (\n        <>\n          <button type=\"button\" onClick={() => setSize(60)}>\n            widen-aside\n          </button>\n          <Splitter.Root\n            size={size}\n            onSizeChangeEnd={setSize}\n            minSize={5}\n            maxSize={95}\n          >\n            <Splitter.Aside>Aside</Splitter.Aside>\n            <Splitter.Handle />\n            <Splitter.Main>Main</Splitter.Main>\n          </Splitter.Root>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(30);\n    });\n\n    await user.click(screen.getByText(\"widen-aside\"));\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(60);\n    });\n  });\n});\n```\n\n### Controlled collapse from anywhere\n\nCollapse is plain controlled boolean state, so a button\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - controlled collapse\", () => {\n  it(\"collapses the aside from a button outside the subtree\", async () => {\n    const user = userEvent.setup();\n    const Demo = () => {\n      const [collapsed, setCollapsed] = useState(false);\n      return (\n        <>\n          <button type=\"button\" onClick={() => setCollapsed((c) => !c)}>\n            toggle-aside\n          </button>\n          <Splitter.Root\n            defaultSize={30}\n            minSize={5}\n            maxSize={95}\n            collapsible\n            collapsed={collapsed}\n            onCollapsedChange={setCollapsed}\n          >\n            <Splitter.Aside>Aside</Splitter.Aside>\n            <Splitter.Handle />\n            <Splitter.Main>Main</Splitter.Main>\n          </Splitter.Root>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByText(\"toggle-aside\"));\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(0);\n    });\n  });\n});\n```\n\n### Nested splitters for 3+ regions\n\nEach nested Splitter is an independent widget.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - Nested\", () => {\n  it(\"nests inside a pane to express three regions\", async () => {\n    render(\n      <NimbusProvider>\n        <Splitter.Root defaultSize={25}>\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Splitter.Root defaultSize={35}>\n              <Splitter.Main>Main</Splitter.Main>\n              <Splitter.Handle />\n              <Splitter.Aside>Aside</Splitter.Aside>\n            </Splitter.Root>\n          </Splitter.Main>\n        </Splitter.Root>\n      </NimbusProvider>\n    );\n\n    const handles = await screen.findAllByRole(\"separator\");\n    expect(handles).toHaveLength(2);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-splitter--docs)\n- [React Aria useSeparator](https://react-spectrum.adobe.com/react-aria/useSeparator.html)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Splitter, type SplitterRootProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`Splitter.Root` wraps one `Splitter.Aside` and one `Splitter.Main` with a\n`Splitter.Handle` between them. `Splitter.Aside` is the configurable pane you\nsize; `Splitter.Main` takes the remaining space. The initial split is set with\n`defaultSize` — a single percentage that always refers to the aside (the main\npane is `100 − size`).\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} minSize={15} maxSize={75}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>\n            Drag the handle to resize. Tab to it, then use the arrow keys.\n          </Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n## Usage examples\n\n### Orientation\n\n`orientation=\"vertical\"` stacks the panes and makes ArrowUp / ArrowDown the\nactive keys. The handle's `aria-orientation` reflects this (W3C separator\nsemantics describe the boundary axis, not the layout axis).\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root orientation=\"vertical\" defaultSize={40}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n          <Text>Aside</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Aside constraints\n\n`minSize` and `maxSize` bound the single aside dimension. `minSize` (default\n`0`) is the aside's floor; `maxSize` (default `100`) caps how far the aside can\ngrow — which in turn fixes the main pane's floor at `100 − maxSize`. Because\nthere is one boundary, this single `[minSize, maxSize]` window on the aside\nfully describes both sides; there is no main-specific prop.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} minSize={15} maxSize={75}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (min 15, max 75)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main (floor 25)</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Collapsible aside\n\nSet `collapsible` to let the aside collapse, and control its collapsed state\nwith the boolean `collapsed`. Because collapse is plain controlled state, any\ncontrol can drive it; Enter on the focused handle toggles it too.\n`onCollapsedChange` fires on every transition. Only the aside collapses.\n\nWhile the aside is collapsed the handle can't be resized (drag and the arrow\nkeys are inactive) — a collapsed aside sits below its `minSize`, so a resize\ncould only snap. The collapsed handle is **keyboard-only**: it advertises no\nmouse-resize affordances (no hover track, and double-click does nothing), but\n**Enter** still expands it. Reopen it with Enter or your own control; the\ncollapsed state holds until you explicitly leave it. Since `collapsedSize`\ndefaults to `0` (the aside fully disappears), provide a visible control — a\nbutton driving `collapsed`, or a trigger near the collapsed aside — so mouse\nusers have a way to reopen it.\n\n```jsx live-dev\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show aside\" : \"Hide aside\"}\n      </Button>\n      <Box height=\"2xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={10}\n          maxSize={80}\n          collapsible\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Collapsing to a rail\n\nCollapse is a two-tier model. `minSize` is the floor for _dragging_ and the\narrow keys; `collapsedSize` is a distinct discrete state that collapse snaps to,\nbelow `minSize`. It defaults to `0` (the aside hides entirely) — set it to leave\na thin rail behind, e.g. an icon strip the user can click to expand.\n\n```jsx live-dev\nconst App = () => {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Expand aside\" : \"Collapse aside to a rail\"}\n      </Button>\n      <Box height=\"2xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={30}\n          minSize={15}\n          maxSize={80}\n          collapsible\n          collapsedSize={6}\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Uncontrolled collapse\n\nWhen you don't need to drive collapse from outside the splitter, seed the\ninitial collapsed state with `defaultCollapsed` and let the splitter own it.\nEnter on the handle toggles it from there. While expanded, double-click restores\nthe default split; while collapsed, the handle is keyboard-only (Enter to\nexpand) and double-click does nothing.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root\n      defaultSize={30}\n      minSize={10}\n      maxSize={80}\n      collapsible\n      defaultCollapsed\n    >\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (starts collapsed)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Tab to the handle and press Enter to toggle</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Keyboard step\n\nArrow keys move the boundary by `keyboardStep` percentage points (default `5`);\nHome / End jump it to the bounds. Accepts floats for finer control.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={30} keyboardStep={10}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>\n            Tab to the handle — each arrow press moves the boundary 10%\n          </Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Restoring the default split\n\nDouble-click the handle to restore the boundary to the sizes resolved on mount.\nSet `isDoubleClickDisabled` to turn that off; drag and keyboard stay active.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root defaultSize={50}>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n            <Text>Drag, then double-click the handle to restore</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"amber.3\" h=\"100%\" />\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n    <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root defaultSize={50} isDoubleClickDisabled>\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Double-click restore disabled</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\" />\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  </Stack>\n);\n```\n\n### Disabled state\n\n`isDisabled` makes the whole splitter non-interactive: the handle leaves the tab\norder, gets `aria-disabled`, and ignores drag, keyboard, and collapse input.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root isDisabled defaultSize={30}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>Main</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Persistence\n\nSize is uncontrolled by default, so persist it in your app with any storage:\nhydrate `defaultSize` from stored state and write the settled value back in\n`onSizeChangeEnd` (it fires once per settled **resize** — drag end, each\nkeypress, double-click restore — so no debouncing is needed; collapse/expand are\nsignalled by `onCollapsedChange`, not here). A\nsingle `number` round-trips: the value `onSizeChangeEnd` emits is exactly the\nshape `defaultSize` accepts. Collapse persists through its controlled boolean\nstate.\n\n```tsx\n// `useLocalStorage` is any storage hook of your choosing.\nconst [size, setSize] = useLocalStorage(\"ide-layout\", 30);\nconst [collapsed, setCollapsed] = useLocalStorage(\"ide-collapsed\", false);\n\n<Splitter.Root\n  defaultSize={size}\n  onSizeChangeEnd={setSize}\n  minSize={10}\n  maxSize={80}\n  collapsible\n  collapsed={collapsed}\n  onCollapsedChange={setCollapsed}\n>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n`onSizeChange` (live, every drag tick ~60Hz) is also available when you need a\nreal-time read-out; prefer `onSizeChangeEnd` for persistence.\n\n### Controlled size\n\nPass `size` instead of `defaultSize` to drive the layout from outside — useful\nfor responsive layouts that swap the proportion per breakpoint, since external\nchanges apply in place (no remount, so pane content keeps its scroll and focus).\nControl is settled, not live: drag and keyboard stay smooth from internal state\nand report once via `onSizeChangeEnd`. Wire that callback and feed the value\nback, or the splitter keeps the last interactive size and behaves as\nuncontrolled from then on.\n\n```tsx\nconst [size, setSize] = useState(30);\n\n<Splitter.Root size={size} onSizeChangeEnd={setSize}>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n### Pixel-precise sizes\n\nThe aside percentage carries full float precision end-to-end (nothing in the\nsize pipeline is rounded — only the handle's `aria-valuenow` is rounded, for\nassistive technology). To land on an exact pixel at a known container width,\npass the computed float — `250px` in an `800px` container is `31.25`.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"3xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={31.25}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>31.25%</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n          <Text>68.75%</Text>\n        </Box>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n### Responsive pixel & token sizes with `useResponsiveSplitterSizes`\n\n`Splitter.Root` is percentage-native — it has no pixel code path. When you'd\nrather think in pixels (a fixed-width sidebar, an icon rail) or size per device,\nreach for the companion hook `useResponsiveSplitterSizes`. It is a **pixel/token\n→ percentage translator**: it measures the splitter's container, converts your\nconfig to the percentage the component wants, drives the controlled `size`\nchannel, and persists the result — all without the component gaining a pixel\npath.\n\nSpread its `rootProps` onto `Splitter.Root` and attach the `ref` it returns (the\n`ref` is required — the hook measures the container through it):\n\n```tsx\nconst { rootProps } = useResponsiveSplitterSizes({\n  orientation: \"horizontal\",\n  persistKey: \"app:main-splitter\",\n  size: \"xs\",          // 320px — size tokens resolve to pixels\n  minSize: \"3xs\",      // 224px\n  maxSize: \"lg\",       // 512px\n});\n\n<Splitter.Root {...rootProps} collapsible>\n  <Splitter.Aside>…</Splitter.Aside>\n  <Splitter.Handle />\n  <Splitter.Main>…</Splitter.Main>\n</Splitter.Root>;\n```\n\n**Units.** A value is a `number` (pixels), a size token (`3xs`–`8xl` or\n`breakpoint-sm`…`breakpoint-2xl`, resolving to pixels), or a `\"N%\"` string\n(passed through untranslated). Note the contrast with `Splitter.Root`'s own\n`size` / `minSize` / … props, which are **percentages**: through the hook, a\nbare number means pixels. Because the hook owns the full facade (`size` plus\n`minSize` / `maxSize` / `collapsedSize`), you don't hand-write percentages on\nthe root when you use it.\n\n**Responsive by container width.** Any dimension can be a map keyed by container\n**min-width thresholds** (pixels or tokens) — a min-width cascade resolved\nagainst the splitter's own width, not the viewport. The largest threshold `≤`\nthe measured width wins; the smallest entry also applies below it.\n\n```tsx\nconst { rootProps } = useResponsiveSplitterSizes({\n  size: { 0: \"xs\", \"breakpoint-md\": \"30%\" }, // \"xs\" (320px) below 768px, 30% above\n});\n```\n\n**Persistence.** Pass a `persistKey` (and optionally a `storage` adapter,\ndefaulting to `localStorage`) and the hook stores the settled size **in pixels**\nper band, so a dragged `320px` re-pins to `320px` across reloads and container\nresizes. `collapsedSize` is static config and is never persisted; the latest\nexpanded size survives collapse and expand.\n\n### Three or more regions\n\nThe Splitter is two-pane by design. For additional regions, nest a Splitter\ninside a pane's children; each splitter owns its own state independently. The\ninner aside can sit on either side of its main pane — here it trails as a right\npanel.\n\n```jsx live-dev\nconst App = () => (\n  <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n    <Splitter.Root defaultSize={25}>\n      <Splitter.Aside>\n        <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n          <Text>Aside (outer)</Text>\n        </Box>\n      </Splitter.Aside>\n      <Splitter.Handle />\n      <Splitter.Main>\n        <Splitter.Root defaultSize={35}>\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Main</Text>\n            </Box>\n          </Splitter.Main>\n          <Splitter.Handle />\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n              <Text>Aside (inner)</Text>\n            </Box>\n          </Splitter.Aside>\n        </Splitter.Root>\n      </Splitter.Main>\n    </Splitter.Root>\n  </Box>\n);\n```\n\n## Common patterns\n\n### IDE-style layout\n\nThe most common real-world composition: a persisted split (`defaultSize` +\n`onSizeChangeEnd`) with a `collapsible` aside that snaps to a rail\n(`collapsedSize`), driven by both a toolbar button and the handle, plus aside\nbounds and a specific handle label.\n\n```jsx live-dev\nconst App = () => {\n  const [size, setSize] = useState(22);\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <Button alignSelf=\"start\" onPress={() => setCollapsed((c) => !c)}>\n        {collapsed ? \"Show aside\" : \"Hide aside\"}\n      </Button>\n      <Box height=\"xs\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n        <Splitter.Root\n          defaultSize={size}\n          onSizeChangeEnd={setSize}\n          minSize={15}\n          maxSize={70}\n          collapsible\n          collapsedSize={4}\n          collapsed={collapsed}\n          onCollapsedChange={setCollapsed}\n        >\n          <Splitter.Aside>\n            <Box p=\"400\" bg=\"indigo.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Aside>\n          <Splitter.Handle aria-label=\"Resize aside\" />\n          <Splitter.Main>\n            <Box p=\"400\" bg=\"amber.3\" h=\"100%\">\n              <Text>Aside</Text>\n            </Box>\n          </Splitter.Main>\n        </Splitter.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n### Vertical with persistence\n\nA vertical split with a persisted boundary and aside bounds so neither region\ncollapses to nothing while dragging.\n\n```jsx live-dev\nconst App = () => {\n  const [size, setSize] = useState(60);\n\n  return (\n    <Box height=\"sm\" width=\"100%\" borderWidth=\"25\" borderColor=\"neutral.6\">\n      <Splitter.Root\n        orientation=\"vertical\"\n        defaultSize={size}\n        onSizeChangeEnd={setSize}\n        minSize={25}\n        maxSize={80}\n      >\n        <Splitter.Aside>\n          <Box p=\"400\" bg=\"teal.3\" h=\"100%\">\n            <Text>Aside</Text>\n          </Box>\n        </Splitter.Aside>\n        <Splitter.Handle />\n        <Splitter.Main>\n          <Box p=\"400\" bg=\"rose.3\" h=\"100%\">\n            <Text>Main</Text>\n          </Box>\n        </Splitter.Main>\n      </Splitter.Root>\n    </Box>\n  );\n};\n```\n\n## Component requirements\n\n### Structure\n\n- `Splitter.Root` must contain exactly one `Splitter.Aside` and one\n  `Splitter.Main` with one `Splitter.Handle` between them; a development-time\n  warning is emitted otherwise. The aside may be placed before or after the main\n  pane (a leading or trailing panel) — `size` always refers to the aside.\n- All sizing and collapse configuration (`defaultSize` / `size`, `minSize`,\n  `maxSize`, `collapsible`, `collapsedSize`) lives on `Splitter.Root`. Panes\n  take only their content and an optional `id` for analytics/testing — nothing\n  is configured on the pane itself.\n\n## Accessibility\n\nThe Splitter handles the W3C window-splitter semantics internally: the handle is\n`role=\"separator\"` with `aria-orientation`, `aria-valuenow` / `aria-valuemin` /\n`aria-valuemax`, `aria-valuetext`, and `aria-controls` pointing at the leading\npane. For the full conformance details, see the Accessibility tab.\n\n#### Labeling\n\nThe handle ships a localized default `aria-label` (\"Resize panes\"); override it\nper handle with `aria-label` or `aria-labelledby` for a more specific label:\n\n```tsx\n<Splitter.Handle aria-label={msg.format(\"resizeAside\")} />\n```\n\n#### Persistent ID\n\nIf your use case requires tracking and analytics, it is good practice to add a\n**persistent**, **unique** id to the handle:\n\n```tsx\nconst PERSISTENT_ID = \"ide-layout-splitter-handle\";\n\nexport const Example = () => (\n  <Splitter.Root defaultSize={30}>\n    <Splitter.Aside>…</Splitter.Aside>\n    <Splitter.Handle id={PERSISTENT_ID} />\n    <Splitter.Main>…</Splitter.Main>\n  </Splitter.Root>\n);\n```\n\n#### Keyboard navigation\n\nWhen the handle has focus:\n\n- `Tab` / `Shift+Tab`: Move focus to/from the handle (in DOM order).\n- `ArrowLeft` / `ArrowRight` (horizontal) or `ArrowUp` / `ArrowDown` (vertical):\n  Move the boundary by `keyboardStep` percentage points (inactive while the\n  aside is collapsed).\n- `Home` / `End`: Jump the boundary to the aside's minimum / maximum (inactive\n  while the aside is collapsed).\n- `Enter`: Toggle collapse of the aside (when `collapsible`).\n\n## API reference\n\n<PropsTable id=\"Splitter\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Splitter\nin your application. As the component's internal functionality is already tested\nby Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering\n\nMinimal Splitter — a configurable aside and a main pane —\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - Basic rendering\", () => {\n  it(\"renders an aside, a main pane, and one handle\", async () => {\n    render(\n      <NimbusProvider>\n        <Splitter.Root defaultSize={30}>\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>Main</Splitter.Main>\n        </Splitter.Root>\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    expect(handle).toBeInTheDocument();\n  });\n});\n```\n\n### Persistence with any storage\n\nHydrate `defaultSize` from stored state and persist the\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - persistence\", () => {\n  it(\"hydrates from the stored size on first render\", async () => {\n    // Stand-in for a `useLocalStorage`-style hook seeded from storage.\n    const Demo = () => {\n      const [size, setSize] = useState(25);\n      return (\n        <Splitter.Root\n          defaultSize={size}\n          onSizeChangeEnd={setSize}\n          minSize={5}\n          maxSize={95}\n        >\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>Main</Splitter.Main>\n        </Splitter.Root>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(25);\n    });\n  });\n});\n```\n\n### Controlled size from anywhere\n\nDrive the layout with the `size` prop and update it from\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - controlled size\", () => {\n  it(\"reflects an external size change in place\", async () => {\n    const user = userEvent.setup();\n    const Demo = () => {\n      const [size, setSize] = useState(30);\n      return (\n        <>\n          <button type=\"button\" onClick={() => setSize(60)}>\n            widen-aside\n          </button>\n          <Splitter.Root\n            size={size}\n            onSizeChangeEnd={setSize}\n            minSize={5}\n            maxSize={95}\n          >\n            <Splitter.Aside>Aside</Splitter.Aside>\n            <Splitter.Handle />\n            <Splitter.Main>Main</Splitter.Main>\n          </Splitter.Root>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(30);\n    });\n\n    await user.click(screen.getByText(\"widen-aside\"));\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(60);\n    });\n  });\n});\n```\n\n### Controlled collapse from anywhere\n\nCollapse is plain controlled boolean state, so a button\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - controlled collapse\", () => {\n  it(\"collapses the aside from a button outside the subtree\", async () => {\n    const user = userEvent.setup();\n    const Demo = () => {\n      const [collapsed, setCollapsed] = useState(false);\n      return (\n        <>\n          <button type=\"button\" onClick={() => setCollapsed((c) => !c)}>\n            toggle-aside\n          </button>\n          <Splitter.Root\n            defaultSize={30}\n            minSize={5}\n            maxSize={95}\n            collapsible\n            collapsed={collapsed}\n            onCollapsedChange={setCollapsed}\n          >\n            <Splitter.Aside>Aside</Splitter.Aside>\n            <Splitter.Handle />\n            <Splitter.Main>Main</Splitter.Main>\n          </Splitter.Root>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Demo />\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByText(\"toggle-aside\"));\n    const handle = await screen.findByRole(\"separator\");\n    await waitFor(() => {\n      expect(Number(handle.getAttribute(\"aria-valuenow\"))).toBe(0);\n    });\n  });\n});\n```\n\n### Nested splitters for 3+ regions\n\nEach nested Splitter is an independent widget.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { NimbusProvider, Splitter } from \"@commercetools/nimbus\";\n\ndescribe(\"Splitter - Nested\", () => {\n  it(\"nests inside a pane to express three regions\", async () => {\n    render(\n      <NimbusProvider>\n        <Splitter.Root defaultSize={25}>\n          <Splitter.Aside>Aside</Splitter.Aside>\n          <Splitter.Handle />\n          <Splitter.Main>\n            <Splitter.Root defaultSize={35}>\n              <Splitter.Main>Main</Splitter.Main>\n              <Splitter.Handle />\n              <Splitter.Aside>Aside</Splitter.Aside>\n            </Splitter.Root>\n          </Splitter.Main>\n        </Splitter.Root>\n      </NimbusProvider>\n    );\n\n    const handles = await screen.findAllByRole(\"separator\");\n    expect(handles).toHaveLength(2);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-splitter--docs)\n- [React Aria useSeparator](https://react-spectrum.adobe.com/react-aria/useSeparator.html)\n- [W3C ARIA window splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/)\n",
       "toc": [
         {
           "value": "Getting started",

package/data/docs/routes/components-media-avatar.json

@@ -206,7 +206,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Avatar, type AvatarProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe simplest implementation displays an avatar with initials derived from first\nand last names:\n\n```jsx live-dev\nconst App = () => (\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface\ndensity:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n  </Stack>\n)\n```\n\n### Color palettes\n\nAvatars support different color palettes to convey semantic meaning or match\nyour design theme:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" colorPalette=\"primary\" />\n    <Avatar firstName=\"Jane\" lastName=\"Smith\" colorPalette=\"positive\" />\n    <Avatar firstName=\"Alex\" lastName=\"Chen\" colorPalette=\"info\" />\n    <Avatar firstName=\"Maria\" lastName=\"Garcia\" colorPalette=\"critical\" />\n    <Avatar firstName=\"Sam\" lastName=\"Wilson\" colorPalette=\"cyan\" />\n  </Stack>\n)\n```\n\n### With image\n\nWhen a `src` prop is provided, the Avatar displays the image. If the image fails\nto load, it automatically falls back to initials:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Jane\"\n      lastName=\"Smith\"\n      src=\"https://i.pravatar.cc/150?img=1\"\n      alt=\"Jane Smith's profile picture\"\n    />\n    <Avatar\n      firstName=\"Alex\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=2\"\n      alt=\"Alex Johnson's profile picture\"\n    />\n  </Stack>\n)\n```\n\n### Initials fallback\n\nThe Avatar automatically extracts and displays initials from the provided first\nand last names. This serves as a fallback when no image is available or when the\nimage fails to load:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Avatar\n      firstName=\"Maria\"\n      lastName=\"Garcia\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Chen\"\n      lastName=\"Wei\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Aisha\"\n      lastName=\"Patel\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n  </Stack>\n)\n```\n\n### Missing or partial names\n\n`firstName` and `lastName` are both **optional**. The Avatar handles missing,\nempty, and whitespace-only values defensively:\n\n- If only one name is usable (after trimming whitespace), a single initial\n  is rendered.\n- If neither name yields a usable character, a generic `Person` icon is\n  rendered as the fallback and a localized generic `aria-label`\n  (`\"User avatar\"`) is applied.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" />            {/* renders \"J\" */}\n    <Avatar lastName=\"Doe\" />              {/* renders \"D\" */}\n    <Avatar firstName=\"\" lastName=\"\" />    {/* renders the Person icon */}\n    <Avatar />                             {/* renders the Person icon */}\n  </Stack>\n)\n```\n\nThis is intended for cases where user records have incomplete name data —\ncommon in legacy systems and partial profiles. The component's TypeScript\ncontract permits `undefined` so call sites do not need non-null assertions\nor empty-string fallbacks.\n\nInitials extraction is also Unicode codepoint-safe (emoji and astral-plane\ncharacters are not split mid-surrogate) and trim-aware (leading/trailing\nwhitespace is discarded before extracting the first character).\n\n## Component requirements\n\n## Accessibility\n\nThe Avatar component handles most accessibility requirements internally,\nincluding automatic labeling with the user's full name.\n\n- **Labeling**: The component automatically generates an internationalized\n  accessible label from the `firstName` and `lastName` props. When providing an\n  image via the `src` prop, always include an `alt` attribute for screen\n  readers.\n- **Role**: Renders as a `<figure>` element with an `aria-label` that includes\n  the full name (e.g., \"Avatar image for John Doe\").\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-avatar\";\n\nexport const Example = () => (\n  <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n);\n```\n\n#### Keyboard navigation\n\nAvatars are non-interactive elements and do not receive focus or support\nkeyboard interaction by default. If you need to make an avatar interactive\n(e.g., clickable), wrap it in a button or interactive element:\n\n```tsx\n<button onClick={handleClick} aria-label=\"View profile\">\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n</button>\n```\n\n## API reference\n\n<PropsTable id=\"Avatar\" />\n\n## Common patterns\n\n### User profile header\n\nCombine Avatar with text components to create a user profile header:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Sarah\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=5\"\n      size=\"md\"\n    />\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"md\" fontWeight=\"600\">Sarah Johnson</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Product Manager</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n### Comment or message list\n\nDisplay avatars alongside user content in comments or messages:\n\n```jsx live-dev\nconst App = () => {\n  const comments = [\n    { id: 1, author: { firstName: \"Alex\", lastName: \"Chen\" }, text: \"Great work on this feature!\", time: \"2 hours ago\" },\n    { id: 2, author: { firstName: \"Maria\", lastName: \"Garcia\" }, text: \"I agree, this is really helpful.\", time: \"1 hour ago\" },\n    { id: 3, author: { firstName: \"James\", lastName: \"Wilson\" }, text: \"Looking forward to the next update.\", time: \"30 minutes ago\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      {comments.map((comment) => (\n        <Stack key={comment.id} direction=\"row\" gap=\"400\">\n          <Avatar\n            firstName={comment.author.firstName}\n            lastName={comment.author.lastName}\n            size=\"xs\"\n          />\n          <Stack direction=\"column\" gap=\"100\" flex=\"1\">\n            <Stack direction=\"row\" gap=\"200\" alignItems=\"baseline\">\n              <Text fontSize=\"sm\" fontWeight=\"600\">\n                {comment.author.firstName} {comment.author.lastName}\n              </Text>\n              <Text fontSize=\"xs\" color=\"neutral.11\">{comment.time}</Text>\n            </Stack>\n            <Text fontSize=\"sm\">{comment.text}</Text>\n          </Stack>\n        </Stack>\n      ))}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Avatar\nwithin your application. As the component's internal functionality is already\ntested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic rendering tests\n\nVerify the Avatar renders with expected elements and labels\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Basic rendering\", () => {\n  it(\"renders avatar with initials\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"figure\")).toBeInTheDocument();\n    expect(screen.getByLabelText(/John Doe/i)).toBeInTheDocument();\n    expect(screen.getByText(\"JD\")).toBeInTheDocument();\n  });\n\n  it(\"renders avatar with image\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar\n          firstName=\"Jane\"\n          lastName=\"Smith\"\n          src=\"https://example.com/avatar.jpg\"\n          alt=\"Jane Smith profile\"\n        />\n      </NimbusProvider>\n    );\n\n    const image = screen.getByAltText(\"Jane Smith profile\");\n    expect(image).toBeInTheDocument();\n    expect(image).toHaveAttribute(\"src\", \"https://example.com/avatar.jpg\");\n  });\n});\n```\n\n### Size variant tests\n\nTest different size options\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Size variants\", () => {\n  it(\"renders different sizes correctly\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n      </NimbusProvider>\n    );\n\n    let avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility tests\n\nVerify accessibility attributes and labeling\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Accessibility\", () => {\n  it(\"has correct aria-label with full name\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"Maria\" lastName=\"Garcia\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByLabelText(/Maria Garcia/i);\n    expect(avatar).toBeInTheDocument();\n    expect(avatar.tagName).toBe(\"FIGURE\");\n  });\n\n  it(\"applies custom id for tracking\", () => {\n    const PERSISTENT_ID = \"test-avatar-id\";\n\n    render(\n      <NimbusProvider>\n        <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n### Missing-name fallback tests\n\nVerify the Avatar renders a generic icon and label when\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Missing names\", () => {\n  it(\"renders the Person icon and generic aria-label when both names are missing\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    // Generic localized aria-label (\"Generic user avatar\" in English)\n    expect(avatar).toHaveAttribute(\"aria-label\", \"Generic user avatar\");\n    // Person icon is rendered as the visual fallback\n    expect(avatar.querySelector(\"svg\")).not.toBeNull();\n    // No initials text is rendered\n    expect(avatar.textContent?.trim()).toBe(\"\");\n  });\n\n  it(\"renders a single initial when only firstName is provided\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar.textContent?.trim()).toBe(\"J\");\n    expect(avatar.querySelector(\"svg\")).toBeNull();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-avatar--docs)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Avatar, type AvatarProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe simplest implementation displays an avatar with initials derived from first\nand last names:\n\n```jsx live-dev\nconst App = () => (\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface\ndensity:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n  </Stack>\n)\n```\n\n### Style variants\n\nTwo visual variants are available. `subtle` (the default) uses a soft tinted\nbackground, while `solid` fills the avatar with the palette's solid color —\nmatching the equivalent Button variant:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" variant=\"subtle\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" variant=\"solid\" />\n  </Stack>\n)\n```\n\n### Color palettes\n\nAvatars support different color palettes to convey semantic meaning or match\nyour design theme:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" colorPalette=\"primary\" />\n    <Avatar firstName=\"Jane\" lastName=\"Smith\" colorPalette=\"positive\" />\n    <Avatar firstName=\"Alex\" lastName=\"Chen\" colorPalette=\"info\" />\n    <Avatar firstName=\"Maria\" lastName=\"Garcia\" colorPalette=\"critical\" />\n    <Avatar firstName=\"Sam\" lastName=\"Wilson\" colorPalette=\"cyan\" />\n  </Stack>\n)\n```\n\n### With image\n\nWhen a `src` prop is provided, the Avatar displays the image. If the image fails\nto load, it automatically falls back to initials:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Jane\"\n      lastName=\"Smith\"\n      src=\"https://i.pravatar.cc/150?img=1\"\n      alt=\"Jane Smith's profile picture\"\n    />\n    <Avatar\n      firstName=\"Alex\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=2\"\n      alt=\"Alex Johnson's profile picture\"\n    />\n  </Stack>\n)\n```\n\n### Initials fallback\n\nThe Avatar automatically extracts and displays initials from the provided first\nand last names. This serves as a fallback when no image is available or when the\nimage fails to load:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Avatar\n      firstName=\"Maria\"\n      lastName=\"Garcia\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Chen\"\n      lastName=\"Wei\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Aisha\"\n      lastName=\"Patel\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n  </Stack>\n)\n```\n\n### Missing or partial names\n\n`firstName` and `lastName` are both **optional**. The Avatar handles missing,\nempty, and whitespace-only values defensively:\n\n- If only one name is usable (after trimming whitespace), a single initial\n  is rendered.\n- If neither name yields a usable character, a generic `Person` icon is\n  rendered as the fallback and a localized generic `aria-label`\n  (`\"User avatar\"`) is applied.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" />            {/* renders \"J\" */}\n    <Avatar lastName=\"Doe\" />              {/* renders \"D\" */}\n    <Avatar firstName=\"\" lastName=\"\" />    {/* renders the Person icon */}\n    <Avatar />                             {/* renders the Person icon */}\n  </Stack>\n)\n```\n\nThis is intended for cases where user records have incomplete name data —\ncommon in legacy systems and partial profiles. The component's TypeScript\ncontract permits `undefined` so call sites do not need non-null assertions\nor empty-string fallbacks.\n\nInitials extraction is also Unicode codepoint-safe (emoji and astral-plane\ncharacters are not split mid-surrogate) and trim-aware (leading/trailing\nwhitespace is discarded before extracting the first character).\n\n## Component requirements\n\n## Accessibility\n\nThe Avatar component handles most accessibility requirements internally,\nincluding automatic labeling with the user's full name.\n\n- **Labeling**: The component automatically generates an internationalized\n  accessible label from the `firstName` and `lastName` props. When providing an\n  image via the `src` prop, always include an `alt` attribute for screen\n  readers.\n- **Role**: Renders as a `<figure>` element with an `aria-label` that includes\n  the full name (e.g., \"Avatar image for John Doe\").\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-avatar\";\n\nexport const Example = () => (\n  <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n);\n```\n\n#### Keyboard navigation\n\nAvatars are non-interactive elements and do not receive focus or support\nkeyboard interaction by default. If you need to make an avatar interactive\n(e.g., clickable), wrap it in a button or interactive element:\n\n```tsx\n<button onClick={handleClick} aria-label=\"View profile\">\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n</button>\n```\n\n## API reference\n\n<PropsTable id=\"Avatar\" />\n\n## Common patterns\n\n### User profile header\n\nCombine Avatar with text components to create a user profile header:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Sarah\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=5\"\n      size=\"md\"\n    />\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"md\" fontWeight=\"600\">Sarah Johnson</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Product Manager</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n### Comment or message list\n\nDisplay avatars alongside user content in comments or messages:\n\n```jsx live-dev\nconst App = () => {\n  const comments = [\n    { id: 1, author: { firstName: \"Alex\", lastName: \"Chen\" }, text: \"Great work on this feature!\", time: \"2 hours ago\" },\n    { id: 2, author: { firstName: \"Maria\", lastName: \"Garcia\" }, text: \"I agree, this is really helpful.\", time: \"1 hour ago\" },\n    { id: 3, author: { firstName: \"James\", lastName: \"Wilson\" }, text: \"Looking forward to the next update.\", time: \"30 minutes ago\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      {comments.map((comment) => (\n        <Stack key={comment.id} direction=\"row\" gap=\"400\">\n          <Avatar\n            firstName={comment.author.firstName}\n            lastName={comment.author.lastName}\n            size=\"xs\"\n          />\n          <Stack direction=\"column\" gap=\"100\" flex=\"1\">\n            <Stack direction=\"row\" gap=\"200\" alignItems=\"baseline\">\n              <Text fontSize=\"sm\" fontWeight=\"600\">\n                {comment.author.firstName} {comment.author.lastName}\n              </Text>\n              <Text fontSize=\"xs\" color=\"neutral.11\">{comment.time}</Text>\n            </Stack>\n            <Text fontSize=\"sm\">{comment.text}</Text>\n          </Stack>\n        </Stack>\n      ))}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Avatar\nwithin your application. As the component's internal functionality is already\ntested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic rendering tests\n\nVerify the Avatar renders with expected elements and labels\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Basic rendering\", () => {\n  it(\"renders avatar with initials\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"figure\")).toBeInTheDocument();\n    expect(screen.getByLabelText(/John Doe/i)).toBeInTheDocument();\n    expect(screen.getByText(\"JD\")).toBeInTheDocument();\n  });\n\n  it(\"renders avatar with image\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar\n          firstName=\"Jane\"\n          lastName=\"Smith\"\n          src=\"https://example.com/avatar.jpg\"\n          alt=\"Jane Smith profile\"\n        />\n      </NimbusProvider>\n    );\n\n    const image = screen.getByAltText(\"Jane Smith profile\");\n    expect(image).toBeInTheDocument();\n    expect(image).toHaveAttribute(\"src\", \"https://example.com/avatar.jpg\");\n  });\n});\n```\n\n### Size variant tests\n\nTest different size options\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Size variants\", () => {\n  it(\"renders different sizes correctly\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n      </NimbusProvider>\n    );\n\n    let avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility tests\n\nVerify accessibility attributes and labeling\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Accessibility\", () => {\n  it(\"has correct aria-label with full name\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"Maria\" lastName=\"Garcia\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByLabelText(/Maria Garcia/i);\n    expect(avatar).toBeInTheDocument();\n    expect(avatar.tagName).toBe(\"FIGURE\");\n  });\n\n  it(\"applies custom id for tracking\", () => {\n    const PERSISTENT_ID = \"test-avatar-id\";\n\n    render(\n      <NimbusProvider>\n        <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n### Missing-name fallback tests\n\nVerify the Avatar renders a generic icon and label when\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Missing names\", () => {\n  it(\"renders the Person icon and generic aria-label when both names are missing\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    // Generic localized aria-label (\"Generic user avatar\" in English)\n    expect(avatar).toHaveAttribute(\"aria-label\", \"Generic user avatar\");\n    // Person icon is rendered as the visual fallback\n    expect(avatar.querySelector(\"svg\")).not.toBeNull();\n    // No initials text is rendered\n    expect(avatar.textContent?.trim()).toBe(\"\");\n  });\n\n  it(\"renders a single initial when only firstName is provided\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar.textContent?.trim()).toBe(\"J\");\n    expect(avatar.querySelector(\"svg\")).toBeNull();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-avatar--docs)\n",
       "toc": [
         {
           "value": "Getting started",
@@ -261,6 +261,17 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Style variants",
+          "href": "#style-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
         {
           "value": "Color palettes",
           "href": "#color-palettes",
@@ -268,7 +279,7 @@
           "numbering": [
             1,
             2,
-            2
+            3
           ],
           "parent": "root"
         },
@@ -279,7 +290,7 @@
           "numbering": [
             1,
             2,
-            3
+            4
           ],
           "parent": "root"
         },
@@ -290,7 +301,7 @@
           "numbering": [
             1,
             2,
-            4
+            5
           ],
           "parent": "root"
         },
@@ -301,7 +312,7 @@
           "numbering": [
             1,
             2,
-            5
+            6
           ],
           "parent": "root"
         },