@commercetools/nimbus-mcp 3.1.0 → 3.3.0

package/data/docs/routes/components-navigation-tabnav.json

@@ -61,6 +61,28 @@
         ],
         "parent": "root"
       },
+      {
+        "value": "Variants",
+        "href": "#variants",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Animated highlight",
+        "href": "#animated-highlight",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
       {
         "value": "Active item",
         "href": "#active-item",
@@ -68,7 +90,7 @@
         "numbering": [
           1,
           2,
-          2
+          4
         ],
         "parent": "root"
       },
@@ -79,7 +101,7 @@
         "numbering": [
           1,
           2,
-          3
+          5
         ],
         "parent": "root"
       },
@@ -90,7 +112,7 @@
         "numbering": [
           1,
           2,
-          4
+          6
         ],
         "parent": "root"
       }
@@ -114,10 +136,10 @@
       }
     ]
   },
-  "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
+  "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Variants\n\n`TabNav` ships with three visual variants:\n\n- **`line`** (default) — an underline strip beneath the active item.\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline and add a small gap\nbetween items. Their active highlight is themeable via `colorPalette` (it\ndefaults to `primary`).\n\nThe active highlight always slides smoothly between items as the active item\nchanges — a single sliding indicator rather than a static per-item highlight.\nThe motion automatically respects `prefers-reduced-motion: reduce`: when reduced\nmotion is requested, the highlight snaps into place instead of sliding.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"line\", \"rounded\", \"pill\"].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{variant}</Text>\n        <TabNav.Root aria-label={`Order navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Animated highlight\n\nThe active highlight slides between items whenever the active item changes (an\nunderline bar for `line`, a filled highlight for `rounded`/`pill`) — no prop\nrequired. The slide respects `prefers-reduced-motion: reduce` (the highlight\nsnaps into place), and `aria-current`, focus, and keyboard order are unaffected.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { href: \"/orders/123/general\", label: \"General\" },\n    { href: \"/orders/123/items\", label: \"Items\" },\n    { href: \"/orders/123/shipping\", label: \"Shipping\" },\n  ];\n  const [activePath, setActivePath] = React.useState(items[0].href);\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => {\n            e.preventDefault();\n            setActivePath(item.href);\n          }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n}\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
   "views": {
     "overview": {
-      "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
+      "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Variants\n\n`TabNav` ships with three visual variants:\n\n- **`line`** (default) — an underline strip beneath the active item.\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline and add a small gap\nbetween items. Their active highlight is themeable via `colorPalette` (it\ndefaults to `primary`).\n\nThe active highlight always slides smoothly between items as the active item\nchanges — a single sliding indicator rather than a static per-item highlight.\nThe motion automatically respects `prefers-reduced-motion: reduce`: when reduced\nmotion is requested, the highlight snaps into place instead of sliding.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"line\", \"rounded\", \"pill\"].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{variant}</Text>\n        <TabNav.Root aria-label={`Order navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Animated highlight\n\nThe active highlight slides between items whenever the active item changes (an\nunderline bar for `line`, a filled highlight for `rounded`/`pill`) — no prop\nrequired. The slide respects `prefers-reduced-motion: reduce` (the highlight\nsnaps into place), and `aria-current`, focus, and keyboard order are unaffected.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { href: \"/orders/123/general\", label: \"General\" },\n    { href: \"/orders/123/items\", label: \"Items\" },\n    { href: \"/orders/123/shipping\", label: \"Shipping\" },\n  ];\n  const [activePath, setActivePath] = React.useState(items[0].href);\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => {\n            e.preventDefault();\n            setActivePath(item.href);\n          }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n}\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
       "toc": [
         {
           "value": "Overview",
@@ -161,6 +183,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Animated highlight",
+          "href": "#animated-highlight",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
         {
           "value": "Active item",
           "href": "#active-item",
@@ -168,7 +212,7 @@
           "numbering": [
             1,
             2,
-            2
+            4
           ],
           "parent": "root"
         },
@@ -179,7 +223,7 @@
           "numbering": [
             1,
             2,
-            3
+            5
           ],
           "parent": "root"
         },
@@ -190,7 +234,7 @@
           "numbering": [
             1,
             2,
-            4
+            6
           ],
           "parent": "root"
         }
@@ -223,7 +267,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { TabNav, type TabNavProps, type TabNavItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`TabNav` is a compound component for **page-level route-based navigation** that renders a `<nav>` landmark containing `<a>` anchor elements. The active item is identified with `aria-current=\"page\"`.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## TabNav vs Tabs\n\n`TabNav` and `Tabs` look similar but serve fundamentally different purposes:\n\n| | `TabNav` | `Tabs` |\n|---|---|---|\n| **Use case** | Page-level navigation between routes | Switching content panels within a page |\n| **HTML semantics** | `<nav>` + `<a>` | `role=\"tablist\"` + `role=\"tab\"` |\n| **Active state** | `aria-current=\"page\"` | `aria-selected=\"true\"` |\n| **Keyboard** | Sequential Tab key | Arrow keys (roving tabindex) |\n| **Content** | No panel — content managed by router | Owns associated `TabPanel` |\n| **URL** | Always (`href` required) | Optional (`href` prop) |\n\nBoth `TabNav` and `Tabs` support client-side routing — the deciding factor is whether the component owns its content panels or delegates to the router. Use `TabNav` when each item navigates to a different route and the router manages what's rendered. Use `Tabs` when the content lives alongside the tab list.\n\n## Usage examples\n\n### Client-side view switching\n\nThe most common TabNav pattern: a persistent nav bar where clicking an item swaps the visible content without a full page reload. In a real app, `isCurrent` is derived from the router and the `href` triggers a route change. The example below simulates this with local state to show the interaction.\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst content = {\n  '/orders/123/general': 'General settings and order details.',\n  '/orders/123/items': 'Line items and quantities.',\n  '/orders/123/shipping': 'Shipping address and carrier information.',\n};\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <Stack gap=\"400\">\n      <TabNav.Root aria-label=\"Order navigation\">\n        {items.map((item) => (\n          <TabNav.Item\n            key={item.href}\n            href={item.href}\n            isCurrent={activePath === item.href}\n            onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n          >\n            {item.label}\n          </TabNav.Item>\n        ))}\n      </TabNav.Root>\n      <Box padding=\"400\">{content[activePath]}</Box>\n    </Stack>\n  );\n};\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This sets `aria-current=\"page\"` on the anchor element, which screen readers announce as \"current page\".\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\nWhen using a client-side router, set `isCurrent` based on the active route:\n\n```tsx\nimport { useLocation } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => {\n  const { pathname } = useLocation();\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\">\n      <TabNav.Item\n        href={`/orders/${orderId}/general`}\n        isCurrent={pathname.endsWith('/general')}\n      >\n        General\n      </TabNav.Item>\n      <TabNav.Item\n        href={`/orders/${orderId}/items`}\n        isCurrent={pathname.endsWith('/items')}\n      >\n        Items\n      </TabNav.Item>\n    </TabNav.Root>\n  );\n};\n```\n\n### Size variants\n\nThe `size` prop controls font size and padding. Available sizes: `sm`, `md` (default), `lg`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Small</Text>\n      <TabNav.Root aria-label=\"Navigation (sm)\" size=\"sm\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Medium (default)</Text>\n      <TabNav.Root aria-label=\"Navigation (md)\" size=\"md\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Large</Text>\n      <TabNav.Root aria-label=\"Navigation (lg)\" size=\"lg\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n### Disabled items\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible. Disabled items are visually dimmed, removed from the tab sequence, and their `href` is stripped.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### External links\n\nUse `target` and `rel` to open a navigation item in a new browser tab. Always pair `target=\"_blank\"` with `rel=\"noopener noreferrer\"` for security.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item\n      href=\"https://docs.example.com/orders\"\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n    >\n      Docs ↗\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### With icons\n\nTab items support inline icons alongside text via the `gap` built into the item layout.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Component requirements\n\n### Accessibility\n\nThe TabNav component uses semantic HTML for navigation — it does not use ARIA roles for the tablist pattern. Accessibility is handled natively by the browser's `<nav>` landmark and `<a>` anchor semantics. `TabNav.Item` uses `useLink` from React Aria for consistent interaction handling.\n\n#### Role\n\n- `TabNav.Root` renders a `<nav>` HTML element — a navigation landmark, **not** `role=\"tablist\"`\n- `TabNav.Item` renders an `<a>` HTML element with the implicit `link` role — **not** `role=\"tab\"`\n- The active item uses `aria-current=\"page\"` — **not** `aria-selected`\n\n#### Labeling\n\nAlways provide an `aria-label` on `TabNav.Root` to describe the navigation region. This is especially important when a page contains multiple `<nav>` landmarks.\n\n```tsx\n<TabNav.Root aria-label=\"Order navigation\">\n  ...\n</TabNav.Root>\n```\n\n#### Keyboard navigation\n\nTabNav uses standard sequential keyboard navigation — no roving tabindex, no arrow key cycling.\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to the next link |\n| `Shift + Tab` | Move focus to the previous link |\n| `Enter` | Activate the focused link |\n\nArrow keys (`ArrowRight`, `ArrowLeft`) do **not** move focus between items. This is intentional — TabNav is a `<nav>` with standard anchor links, not a `role=\"tablist\"` widget.\n\n#### Persistent ID\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"order-detail-tab-nav\";\n\nexport const OrderTabNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root id={PERSISTENT_ID} aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## API reference\n\n<PropsTable id=\"TabNav\" />\n\n## Common patterns\n\n### Syncing active item with router\n\nIn most routing setups you derive `isCurrent` from the current URL rather than managing it in state.\n\n```tsx\n// React Router v6\nimport { useMatch } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item\n      href={`/orders/${orderId}/general`}\n      isCurrent={!!useMatch(`/orders/${orderId}/general`)}\n    >\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/items`}\n      isCurrent={!!useMatch(`/orders/${orderId}/items`)}\n    >\n      Items\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isCurrent={!!useMatch(`/orders/${orderId}/shipping`)}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### Conditionally disabling items\n\nDisable items based on permissions or loading state rather than hiding them — this preserves the layout and communicates to users that the section exists.\n\n```tsx\nconst OrderNav = ({ orderId, canViewShipping }: { orderId: string; canViewShipping: boolean }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isDisabled={!canViewShipping}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TabNav within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the TabNav component renders a nav landmark with anchor links\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Basic rendering\", () => {\n  it(\"renders a navigation landmark with links\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n    expect(screen.getAllByRole(\"link\")).toHaveLength(3);\n  });\n\n  it(\"renders items as anchor elements with correct href\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/general\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/items\"\n    );\n  });\n});\n```\n\n### Active Item Tests\n\nVerify aria-current=\"page\" is applied correctly to the active navigation item\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Active item\", () => {\n  it(\"sets aria-current='page' on the active item\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n\n  it(\"does not set aria-current on inactive items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Shipping\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n  });\n\n  it(\"does not use aria-selected (navigation, not widget)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).not.toHaveAttribute(\n      \"aria-selected\"\n    );\n  });\n});\n```\n\n### Disabled Item Tests\n\nVerify disabled items are marked inaccessible and removed from tab order\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Disabled items\", () => {\n  it(\"marks disabled items with aria-disabled='true'\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"disabled items have no tabIndex (excluded from tab sequence by browser)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    // React Aria sets no tabIndex on the disabled anchor — the browser excludes it\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).not.toHaveAttribute(\"tabindex\");\n  });\n});\n```\n\n### External Link Tests\n\nVerify target and rel attributes for external navigation items\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - External links\", () => {\n  it(\"applies target and rel to external link items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item\n            href=\"https://docs.example.com\"\n            target=\"_blank\"\n            rel=\"noopener noreferrer\"\n          >\n            Docs ↗\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const externalLink = screen.getByRole(\"link\", { name: \"Docs ↗\" });\n    expect(externalLink).toHaveAttribute(\"target\", \"_blank\");\n    expect(externalLink).toHaveAttribute(\"rel\", \"noopener noreferrer\");\n  });\n});\n```\n\n### Interaction Tests\n\nVerify click handling and keyboard activation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Interactions\", () => {\n  it(\"calls onClick handler when a link is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleClick = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" onClick={handleClick}>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"link\", { name: \"General\" }));\n    expect(handleClick).toHaveBeenCalled();\n  });\n\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveFocus();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessible labels and ID support\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Accessibility\", () => {\n  it(\"supports aria-label on the root for landmark identification\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"supports a persistent id on the root for tracking\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root id=\"order-tab-nav\" aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"navigation\")).toHaveAttribute(\n      \"id\",\n      \"order-tab-nav\"\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n- [ARIA: navigation landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)\n- [aria-current attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)\n- [Tabs](/components/navigation/tabs) — use when switching content panels on the same page\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { TabNav, type TabNavProps, type TabNavItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`TabNav` is a compound component for **page-level route-based navigation** that renders a `<nav>` landmark containing `<a>` anchor elements. The active item is identified with `aria-current=\"page\"`.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## TabNav vs Tabs\n\n`TabNav` and `Tabs` look similar but serve fundamentally different purposes:\n\n| | `TabNav` | `Tabs` |\n|---|---|---|\n| **Use case** | Page-level navigation between routes | Switching content panels within a page |\n| **HTML semantics** | `<nav>` + `<a>` | `role=\"tablist\"` + `role=\"tab\"` |\n| **Active state** | `aria-current=\"page\"` | `aria-selected=\"true\"` |\n| **Keyboard** | Sequential Tab key | Arrow keys (roving tabindex) |\n| **Content** | No panel — content managed by router | Owns associated `TabPanel` |\n| **URL** | Always (`href` required) | Optional (`href` prop) |\n\nBoth `TabNav` and `Tabs` support client-side routing — the deciding factor is whether the component owns its content panels or delegates to the router. Use `TabNav` when each item navigates to a different route and the router manages what's rendered. Use `Tabs` when the content lives alongside the tab list.\n\n## Usage examples\n\n### Client-side view switching\n\nThe most common TabNav pattern: a persistent nav bar where clicking an item swaps the visible content without a full page reload. In a real app, `isCurrent` is derived from the router and the `href` triggers a route change. The example below simulates this with local state to show the interaction.\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst content = {\n  '/orders/123/general': 'General settings and order details.',\n  '/orders/123/items': 'Line items and quantities.',\n  '/orders/123/shipping': 'Shipping address and carrier information.',\n};\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <Stack gap=\"400\">\n      <TabNav.Root aria-label=\"Order navigation\">\n        {items.map((item) => (\n          <TabNav.Item\n            key={item.href}\n            href={item.href}\n            isCurrent={activePath === item.href}\n            onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n          >\n            {item.label}\n          </TabNav.Item>\n        ))}\n      </TabNav.Root>\n      <Box padding=\"400\">{content[activePath]}</Box>\n    </Stack>\n  );\n};\n```\n\n### Variants\n\nThe `variant` prop controls the visual style. Available variants: `line` (default), `rounded`, `pill`. (`Tabs` exposes the same three variants.)\n\n- **`line`** — an underline strip beneath the active item (visually twinned with the `Tabs` `line` variant).\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline, add a small gap between items, and drive their active highlight off `colorPalette` (defaulting to `primary`), so they theme with the surrounding palette.\n\nThe legacy `tabs` variant name is accepted as a deprecated alias for `line`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {['line', 'rounded', 'pill'].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"500\">{variant}</Text>\n        <TabNav.Root aria-label={`Navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n          <TabNav.Item href=\"/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n);\n```\n\n### Animated highlight\n\nThe active highlight always slides between items as the active item changes — a single indicator instead of a static per-item highlight. It adapts to the variant: a sliding underline bar for `line`, and a sliding filled highlight for `rounded`/`pill`. No prop is required.\n\nThe indicator is an `aria-hidden`, non-focusable element, so `aria-current`, focus rings, and keyboard order are unaffected. Its position is measured from the live DOM (`aria-current=\"page\"`) and kept in sync as the active item changes or the layout resizes. The recipe's static marker is the SSR / no-JS fallback.\n\nThe slide transition is automatically disabled under `prefers-reduced-motion: reduce` — the highlight snaps into place. (To disable the motion, the user sets the OS-level reduced-motion preference; there is no per-instance prop.)\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n};\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This sets `aria-current=\"page\"` on the anchor element, which screen readers announce as \"current page\".\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\nWhen using a client-side router, set `isCurrent` based on the active route:\n\n```tsx\nimport { useLocation } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => {\n  const { pathname } = useLocation();\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\">\n      <TabNav.Item\n        href={`/orders/${orderId}/general`}\n        isCurrent={pathname.endsWith('/general')}\n      >\n        General\n      </TabNav.Item>\n      <TabNav.Item\n        href={`/orders/${orderId}/items`}\n        isCurrent={pathname.endsWith('/items')}\n      >\n        Items\n      </TabNav.Item>\n    </TabNav.Root>\n  );\n};\n```\n\n### Size variants\n\nThe `size` prop controls font size and padding. Available sizes: `sm`, `md` (default), `lg`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Small</Text>\n      <TabNav.Root aria-label=\"Navigation (sm)\" size=\"sm\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Medium (default)</Text>\n      <TabNav.Root aria-label=\"Navigation (md)\" size=\"md\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Large</Text>\n      <TabNav.Root aria-label=\"Navigation (lg)\" size=\"lg\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n### Disabled items\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible. Disabled items are visually dimmed, removed from the tab sequence, and their `href` is stripped.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### External links\n\nUse `target` and `rel` to open a navigation item in a new browser tab. Always pair `target=\"_blank\"` with `rel=\"noopener noreferrer\"` for security.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item\n      href=\"https://docs.example.com/orders\"\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n    >\n      Docs ↗\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### With icons\n\nTab items support inline icons alongside text via the `gap` built into the item layout.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Component requirements\n\n### Accessibility\n\nThe TabNav component uses semantic HTML for navigation — it does not use ARIA roles for the tablist pattern. Accessibility is handled natively by the browser's `<nav>` landmark and `<a>` anchor semantics. `TabNav.Item` uses `useLink` from React Aria for consistent interaction handling.\n\n#### Role\n\n- `TabNav.Root` renders a `<nav>` HTML element — a navigation landmark, **not** `role=\"tablist\"`\n- `TabNav.Item` renders an `<a>` HTML element with the implicit `link` role — **not** `role=\"tab\"`\n- The active item uses `aria-current=\"page\"` — **not** `aria-selected`\n\n#### Labeling\n\nAlways provide an `aria-label` on `TabNav.Root` to describe the navigation region. This is especially important when a page contains multiple `<nav>` landmarks.\n\n```tsx\n<TabNav.Root aria-label=\"Order navigation\">\n  ...\n</TabNav.Root>\n```\n\n#### Keyboard navigation\n\nTabNav uses standard sequential keyboard navigation — no roving tabindex, no arrow key cycling.\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to the next link |\n| `Shift + Tab` | Move focus to the previous link |\n| `Enter` | Activate the focused link |\n\nArrow keys (`ArrowRight`, `ArrowLeft`) do **not** move focus between items. This is intentional — TabNav is a `<nav>` with standard anchor links, not a `role=\"tablist\"` widget.\n\n#### Persistent ID\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"order-detail-tab-nav\";\n\nexport const OrderTabNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root id={PERSISTENT_ID} aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## API reference\n\n<PropsTable id=\"TabNav\" />\n\n## Common patterns\n\n### Syncing active item with router\n\nIn most routing setups you derive `isCurrent` from the current URL rather than managing it in state.\n\n```tsx\n// React Router v6\nimport { useMatch } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item\n      href={`/orders/${orderId}/general`}\n      isCurrent={!!useMatch(`/orders/${orderId}/general`)}\n    >\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/items`}\n      isCurrent={!!useMatch(`/orders/${orderId}/items`)}\n    >\n      Items\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isCurrent={!!useMatch(`/orders/${orderId}/shipping`)}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### Conditionally disabling items\n\nDisable items based on permissions or loading state rather than hiding them — this preserves the layout and communicates to users that the section exists.\n\n```tsx\nconst OrderNav = ({ orderId, canViewShipping }: { orderId: string; canViewShipping: boolean }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isDisabled={!canViewShipping}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TabNav within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the TabNav component renders a nav landmark with anchor links\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Basic rendering\", () => {\n  it(\"renders a navigation landmark with links\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n    expect(screen.getAllByRole(\"link\")).toHaveLength(3);\n  });\n\n  it(\"renders items as anchor elements with correct href\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/general\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/items\"\n    );\n  });\n});\n```\n\n### Active Item Tests\n\nVerify aria-current=\"page\" is applied correctly to the active navigation item\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Active item\", () => {\n  it(\"sets aria-current='page' on the active item\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n\n  it(\"does not set aria-current on inactive items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Shipping\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n  });\n\n  it(\"does not use aria-selected (navigation, not widget)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).not.toHaveAttribute(\n      \"aria-selected\"\n    );\n  });\n});\n```\n\n### Disabled Item Tests\n\nVerify disabled items are marked inaccessible and removed from tab order\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Disabled items\", () => {\n  it(\"marks disabled items with aria-disabled='true'\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"disabled items have no tabIndex (excluded from tab sequence by browser)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    // React Aria sets no tabIndex on the disabled anchor — the browser excludes it\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).not.toHaveAttribute(\"tabindex\");\n  });\n});\n```\n\n### External Link Tests\n\nVerify target and rel attributes for external navigation items\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - External links\", () => {\n  it(\"applies target and rel to external link items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item\n            href=\"https://docs.example.com\"\n            target=\"_blank\"\n            rel=\"noopener noreferrer\"\n          >\n            Docs ↗\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const externalLink = screen.getByRole(\"link\", { name: \"Docs ↗\" });\n    expect(externalLink).toHaveAttribute(\"target\", \"_blank\");\n    expect(externalLink).toHaveAttribute(\"rel\", \"noopener noreferrer\");\n  });\n});\n```\n\n### Interaction Tests\n\nVerify click handling and keyboard activation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Interactions\", () => {\n  it(\"calls onClick handler when a link is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleClick = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" onClick={handleClick}>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"link\", { name: \"General\" }));\n    expect(handleClick).toHaveBeenCalled();\n  });\n\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveFocus();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessible labels and ID support\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Accessibility\", () => {\n  it(\"supports aria-label on the root for landmark identification\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"supports a persistent id on the root for tracking\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root id=\"order-tab-nav\" aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"navigation\")).toHaveAttribute(\n      \"id\",\n      \"order-tab-nav\"\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n- [ARIA: navigation landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)\n- [aria-current attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)\n- [Tabs](/components/navigation/tabs) — use when switching content panels on the same page\n",
       "toc": [
         {
           "value": "Getting started",
@@ -288,6 +332,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Animated highlight",
+          "href": "#animated-highlight",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
         {
           "value": "Active item",
           "href": "#active-item",
@@ -295,7 +361,7 @@
           "numbering": [
             1,
             3,
-            2
+            4
           ],
           "parent": "root"
         },
@@ -306,7 +372,7 @@
           "numbering": [
             1,
             3,
-            3
+            5
           ],
           "parent": "root"
         },
@@ -317,7 +383,7 @@
           "numbering": [
             1,
             3,
-            4
+            6
           ],
           "parent": "root"
         },
@@ -328,7 +394,7 @@
           "numbering": [
             1,
             3,
-            5
+            7
           ],
           "parent": "root"
         },
@@ -339,7 +405,7 @@
           "numbering": [
             1,
             3,
-            6
+            8
           ],
           "parent": "root"
         },