@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-buttons-icon-button.json

@@ -0,0 +1,852 @@
+{
+  "meta": {
+    "id": "Components-IconButton",
+    "title": "Icon button",
+    "exportName": "IconButton",
+    "description": "Provides a compact and visually efficient way to represent actions, especially when space is limited or the action is universally understood.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/icon-button/icon-button.mdx",
+    "menu": [
+      "Components",
+      "Buttons",
+      "Icon button"
+    ],
+    "route": "components/buttons/icon-button",
+    "tags": [
+      "component",
+      "buttons",
+      "actions",
+      "icons"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Hierarchy",
+        "href": "#hierarchy",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Most common: Ghost",
+        "href": "#most-common-ghost",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Use sparingly: Solid",
+        "href": "#use-sparingly-solid",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Least used: Outline",
+        "href": "#least-used-outline",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium (40px)",
+        "href": "#medium-40px",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "X-Small (32px)",
+        "href": "#x-small-32px",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "XX-Small (24px)",
+        "href": "#xx-small-24px",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Color palette",
+        "href": "#color-palette",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Primary",
+        "href": "#primary",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Critical",
+        "href": "#critical",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Tooltip",
+        "href": "#tooltip",
+        "depth": 4,
+        "numbering": [
+          1,
+          3,
+          2,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/New-Design-System?node-id=58-132&m=dev",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThese specifications define the standard styles and variations for icon buttons\nwithin our design system, covering different visual treatments for diverse use\ncases.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2570&m=dev)\n\n## Hierarchy\n\n#### Most common: Ghost\n\nGhost icon buttons are used most often, the represent familiar actions that\ndon't compete with a primary action on the page.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### Use sparingly: Solid\n\nSolid icon buttons are sparingly used, but represent commonly understood primary\nactions by the user.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### Least used: Outline\n\nOutline icon buttons are used as secondary buttons, used often in button groups\nto represent icon toggles and within data tables.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"outline\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium (40px)\n\nThese are the default and preferred size for icon buttons.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"md\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### X-Small (32px)\n\nPlaced in a small dense content areas, e.g., in pop-over or inside a data table.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"xs\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### XX-Small (24px)\n\n2XS is used sparingly mostly inside other components e.g, inside inputs or\nfilter badges.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"2xs\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n### Color palette\n\n#### Primary\n\nThis is the default color palette for the icon button. This styling should be\nused most commonly for all actions.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"primary\">\n      <Icons.ViewColumn/>\n    </IconButton>\n  );\n};\n```\n\n#### Critical\n\nUse this icon button when the user is approaching a permanent destructive\naction. See guidelines for more information.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"critical\">\n      <Icons.Delete/>\n    </IconButton>\n  );\n};\n```\n\n#### Tooltip\n\nFor accessibility compliance (and good user experience for all) icon buttons\nthat do not have a label must have a tooltip. Go to tooltips for more\ninformation about the component.\n\n```jsx live\nconst App = () => {\n  return (\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <IconButton variant=\"ghost\" colorPalette=\"primary\">\n        <Icons.Edit/>\n      </IconButton>\n      <Tooltip.Content>\n        Edit\n      </Tooltip.Content>\n    </Tooltip.Root>\n  );\n};\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThese specifications define the standard styles and variations for icon buttons\nwithin our design system, covering different visual treatments for diverse use\ncases.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2570&m=dev)\n\n## Hierarchy\n\n#### Most common: Ghost\n\nGhost icon buttons are used most often, the represent familiar actions that\ndon't compete with a primary action on the page.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### Use sparingly: Solid\n\nSolid icon buttons are sparingly used, but represent commonly understood primary\nactions by the user.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### Least used: Outline\n\nOutline icon buttons are used as secondary buttons, used often in button groups\nto represent icon toggles and within data tables.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"outline\" colorPalette=\"primary\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium (40px)\n\nThese are the default and preferred size for icon buttons.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"md\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### X-Small (32px)\n\nPlaced in a small dense content areas, e.g., in pop-over or inside a data table.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"xs\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n#### XX-Small (24px)\n\n2XS is used sparingly mostly inside other components e.g, inside inputs or\nfilter badges.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"solid\" colorPalette=\"primary\" size=\"2xs\">\n      <Icons.Edit/>\n    </IconButton>\n  );\n};\n```\n\n### Color palette\n\n#### Primary\n\nThis is the default color palette for the icon button. This styling should be\nused most commonly for all actions.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"primary\">\n      <Icons.ViewColumn/>\n    </IconButton>\n  );\n};\n```\n\n#### Critical\n\nUse this icon button when the user is approaching a permanent destructive\naction. See guidelines for more information.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton variant=\"ghost\" colorPalette=\"critical\">\n      <Icons.Delete/>\n    </IconButton>\n  );\n};\n```\n\n#### Tooltip\n\nFor accessibility compliance (and good user experience for all) icon buttons\nthat do not have a label must have a tooltip. Go to tooltips for more\ninformation about the component.\n\n```jsx live\nconst App = () => {\n  return (\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <IconButton variant=\"ghost\" colorPalette=\"primary\">\n        <Icons.Edit/>\n      </IconButton>\n      <Tooltip.Content>\n        Edit\n      </Tooltip.Content>\n    </Tooltip.Root>\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Hierarchy",
+          "href": "#hierarchy",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Most common: Ghost",
+          "href": "#most-common-ghost",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Use sparingly: Solid",
+          "href": "#use-sparingly-solid",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Least used: Outline",
+          "href": "#least-used-outline",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium (40px)",
+          "href": "#medium-40px",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "X-Small (32px)",
+          "href": "#x-small-32px",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "XX-Small (24px)",
+          "href": "#xx-small-24px",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Primary",
+          "href": "#primary",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical",
+          "href": "#critical",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tooltip",
+          "href": "#tooltip",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            2,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nThe component uses `onPress*` props to handle all user interactions—mouse\nclicks, touch taps, and keyboard presses—consistently. These props (`onPress`,\n`onPressStart`, `onPressEnd`, etc.) ensure a smooth and accessible experience\nregardless of the user's input method or device.\n\n```jsx live\nconst App = () => {\n  return (\n    <IconButton colorPalette=\"primary\" variant=\"solid\" onPress={() => alert('Button pressed!')}>\n      <Icons.Edit />\n    </IconButton>\n  )\n}\n```\n\n### Accessibility standards\n\n- **Color contrast:** Ensure enough contrast between the icon and its\n  background. WCAG requires a contrast ratio of at least 3:1 for graphical\n  elements and 4.5:1 for text. Tools like WebAIM's color contrast checker can\n  help you verify this.\n- **Non-text content:** Icons are considered non-text content. WCAG requires\n  that all non-text content has a text alternative that serves the equivalent\n  purpose. This usually means providing an alternative text (alt text) for the\n  icon.\n- **Visual cues:** Don't rely solely on color to convey information. Use\n  additional visual cues like shapes, patterns, or text labels to ensure that\n  the icon's meaning is clear to everyone, including people with color\n  blindness.\n- **Keyboard accessibility:** Icon buttons must be operable using a keyboard.\n  Users should be able to navigate to the button using the Tab key and activate\n  it using the Enter or Space key.\n- **Target size:** Ensure that the icon button is large enough to be easily\n  clickable, especially on touchscreens. WCAG recommends a minimum target size\n  of 24x24 CSS pixels.\n- **Focus indicator:** Provide a clear visual indicator when the icon button\n  receives keyboard focus. This helps users understand which element is\n  currently active.\n- **Clear labels:** If the icon's meaning isn't universally understood, provide\n  a text label or tooltip to clarify its purpose. This is especially important\n  for less common icons.\n- **Consistent design:** Use icons consistently throughout your website. This\n  helps users learn the meaning of each icon and makes it easier for them to\n  navigate your site.\n- **Assistive technology compatibility:** Ensure that icon buttons are\n  compatible with assistive technologies like screen readers. This often\n  involves using proper HTML markup and ARIA attributes to provide semantic\n  information about the button.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { IconButton, type IconButtonProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nIconButton displays a button containing only an icon as its child. It requires an `aria-label` for accessibility since there is no visible text:\n\n```jsx live-dev\nconst App = () => (\n  <IconButton aria-label=\"Open menu\">\n    <Icons.Menu />\n  </IconButton>\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconButton size=\"2xs\" aria-label=\"Extra small button\">\n      <Icons.Add />\n    </IconButton>\n    <IconButton size=\"xs\" aria-label=\"Small button\">\n      <Icons.Add />\n    </IconButton>\n    <IconButton size=\"md\" aria-label=\"Medium button\">\n      <Icons.Add />\n    </IconButton>\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between `solid`, `subtle`, `outline`, `ghost`, and `link` variants to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconButton variant=\"solid\" aria-label=\"Solid button\">\n      <Icons.Edit />\n    </IconButton>\n    <IconButton variant=\"subtle\" aria-label=\"Subtle button\">\n      <Icons.Edit />\n    </IconButton>\n    <IconButton variant=\"outline\" aria-label=\"Outline button\">\n      <Icons.Edit />\n    </IconButton>\n    <IconButton variant=\"ghost\" aria-label=\"Ghost button\">\n      <Icons.Edit />\n    </IconButton>\n    <IconButton variant=\"link\" aria-label=\"Link button\">\n      <Icons.Edit />\n    </IconButton>\n  </Stack>\n)\n```\n\n### Color palettes\n\nUse semantic color palettes to convey meaning or match your brand:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconButton colorPalette=\"primary\" aria-label=\"Primary action\">\n      <Icons.Send />\n    </IconButton>\n    <IconButton colorPalette=\"critical\" aria-label=\"Delete item\">\n      <Icons.Delete />\n    </IconButton>\n    <IconButton colorPalette=\"positive\" aria-label=\"Approve\">\n      <Icons.Check />\n    </IconButton>\n    <IconButton colorPalette=\"warning\" aria-label=\"Warning action\">\n      <Icons.Warning />\n    </IconButton>\n  </Stack>\n)\n```\n\n### Disabled state\n\nDisable user interaction when an action is temporarily unavailable:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconButton aria-label=\"Enabled button\">\n      <Icons.Save />\n    </IconButton>\n    <IconButton isDisabled aria-label=\"Disabled button\">\n      <Icons.Save />\n    </IconButton>\n  </Stack>\n)\n```\n\n### Press handling\n\nHandle user interactions with the `onPress` callback:\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"center\">\n      <IconButton\n        aria-label=\"Increment counter\"\n        onPress={() => setCount(count + 1)}\n      >\n        <Icons.Add />\n      </IconButton>\n      <Text fontSize=\"sm\">Clicked {count} times</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nIconButton requires a **mandatory `aria-label` prop** since icon-only buttons lack visible text for screen readers. This label should:\n- Clearly describe the button's action\n- Be concise but descriptive\n\n**Setting the aria-label:**\n\n```tsx\n<IconButton aria-label=\"Open menu\">\n  <Icons.Menu />\n</IconButton>\n```\n\nFor icon buttons with visible tooltips, the `aria-label` is still required for screen reader users who may not trigger the tooltip:\n\n```tsx\n<Tooltip.Root>\n  <IconButton aria-label=\"Settings\">\n    <Icons.Settings />\n  </IconButton>\n  <Tooltip.Content>Settings</Tooltip.Content>\n</Tooltip.Root>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-icon-button\";\n\nexport const Example = () => (\n  <IconButton id={PERSISTENT_ID} aria-label=\"Open settings\">\n    <Icons.Settings />\n  </IconButton>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus to/from the button\n- `Enter` / `Space`: Activate the button\n- `Escape`: Remove focus (when focused)\n\n## API reference\n\n<PropsTable id=\"IconButton\" />\n\n## Common patterns\n\n### With Tooltip\n\nIcon buttons should typically include a tooltip to provide additional context for sighted users:\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"center\">\n      <Stack direction=\"row\" gap=\"300\">\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Add item\"\n            onPress={() => setCount(count + 1)}\n          >\n            <Icons.Add />\n          </IconButton>\n          <Tooltip.Content>Add item</Tooltip.Content>\n        </Tooltip.Root>\n\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Remove item\"\n            onPress={() => setCount(Math.max(0, count - 1))}\n            isDisabled={count === 0}\n          >\n            <Icons.Remove />\n          </IconButton>\n          <Tooltip.Content>Remove item</Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n      <Text fontSize=\"sm\">Count: {count}</Text>\n    </Stack>\n  );\n}\n```\n\n### Loading state\n\nShow a loading state during asynchronous operations:\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handlePress = () => {\n    setIsLoading(true);\n    setTimeout(() => setIsLoading(false), 2000);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"center\">\n      <IconButton\n        aria-label=\"Save changes\"\n        onPress={handlePress}\n        isLoading={isLoading}\n      >\n        <Icons.Save />\n      </IconButton>\n      <Text fontSize=\"sm\">\n        {isLoading ? 'Saving...' : 'Click to save'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Icon button group\n\nGroup related icon buttons using Stack:\n\n```jsx live-dev\nconst App = () => {\n  const [alignment, setAlignment] = useState('left');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\">\n        <IconButton\n          aria-label=\"Align left\"\n          variant={alignment === 'left' ? 'solid' : 'ghost'}\n          onPress={() => setAlignment('left')}\n        >\n          <Icons.FormatAlignLeft />\n        </IconButton>\n        <IconButton\n          aria-label=\"Align center\"\n          variant={alignment === 'center' ? 'solid' : 'ghost'}\n          onPress={() => setAlignment('center')}\n        >\n          <Icons.FormatAlignCenter />\n        </IconButton>\n        <IconButton\n          aria-label=\"Align right\"\n          variant={alignment === 'right' ? 'solid' : 'ghost'}\n          onPress={() => setAlignment('right')}\n        >\n          <Icons.FormatAlignRight />\n        </IconButton>\n      </Stack>\n      <Text fontSize=\"sm\">Alignment: {alignment}</Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using IconButton 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 IconButton renders correctly with required props\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 { IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconButton - Basic rendering\", () => {\n  it(\"renders button with icon\", () => {\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    expect(button).toBeInTheDocument();\n  });\n\n  it(\"renders with required aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Open menu\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /open menu/i });\n    expect(button).toHaveAttribute(\"aria-label\", \"Open menu\");\n  });\n\n  it(\"renders with custom data attributes\", () => {\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Test button\" data-testid=\"custom-button\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"custom-button\")).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the IconButton\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 { IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconButton - Interactions\", () => {\n  it(\"calls onPress when clicked\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\" onPress={handlePress}>\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    await user.click(button);\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"does not call onPress when disabled\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\" onPress={handlePress} isDisabled>\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    await user.click(button);\n\n    expect(handlePress).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions with the IconButton\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 { IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconButton - Keyboard navigation\", () => {\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n\n    await user.tab();\n\n    expect(button).toHaveFocus();\n  });\n\n  it(\"can be activated with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\" onPress={handlePress}>\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    button.focus();\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"can be activated with Space key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\" onPress={handlePress}>\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    button.focus();\n\n    await user.keyboard(\" \");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n### State Tests\n\nTest different states of the IconButton\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 { IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconButton - States\", () => {\n  it(\"applies disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Add item\" isDisabled>\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /add item/i });\n    expect(button).toBeDisabled();\n  });\n});\n```\n\n### Visual Variant Tests\n\nTest different visual variants and sizes\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 { IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconButton - Visual variants\", () => {\n  it(\"renders with different size variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Small button\" size=\"xs\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <IconButton aria-label=\"Medium button\" size=\"md\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with different visual variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Solid button\" variant=\"solid\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <IconButton aria-label=\"Outline button\" variant=\"outline\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with color palettes\", () => {\n    render(\n      <NimbusProvider>\n        <IconButton aria-label=\"Primary action\" colorPalette=\"primary\">\n          <AddIcon />\n        </IconButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-buttons-iconbutton--docs)\n- [Button Component](../components/inputs/button)\n- [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html)\n- [ARIA Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palettes",
+          "href": "#color-palettes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Press handling",
+          "href": "#press-handling",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With Tooltip",
+          "href": "#with-tooltip",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Loading state",
+          "href": "#loading-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icon button group",
+          "href": "#icon-button-group",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation Tests",
+          "href": "#keyboard-navigation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual Variant Tests",
+          "href": "#visual-variant-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nIcon buttons are interactive elements that empower users to trigger actions and\nnavigate within your product. They serve as clear calls to action, guiding users\nthrough key flows and enabling them to interact with content in meaningful ways.\nThese guidelines ensure consistent styling and behavior for all buttons,\ncontributing to a cohesive and predictable user experience.\n\n### Writing guidelines\n\n- Use\n  [Material Icons](https://mui.com/material-ui/material-icons/?theme=Outlined&query=access#search-material-icons)\n  in outline style before adding a new custom icon.\n- Use standard icons.\n- Provide tooltips.\n- Combine with text when needed.\n- Be consistent.\n- Test with users.\n\n#### Preferred words\n\n| **Example**                                                   | **Description**                                                                                                                                                                                 |\n| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| <Icon id=\"Edit\" color=\"primary.11\" boxSize=\"24px\" />          | Use for \"edit\".                                                                                                                                                                                 |\n| <Icon id=\"FileUpload\" color=\"primary.11\" boxSize=\"24px\" />    | Upload.                                                                                                                                                                                         |\n| <Icon id=\"FileDownload\" color=\"primary.11\" boxSize=\"24px\" />  | Download.                                                                                                                                                                                       |\n| <Icon id=\"ViewColumn\" color=\"primary.11\" boxSize=\"24px\" />    | \"Table settings\" Shows customizable elements for tables.                                                                                                                                        |\n| <Icon id=\"MoreVert\" color=\"primary.11\" boxSize=\"24px\" />      | \"More options\" shows a list of other features or tools that are not primary or secondary actions. Usually paired with buttons in a button group. For consistency, use the vertical dot version. |\n| <Icon id=\"DragIndicator\" color=\"primary.11\" boxSize=\"24px\" /> | \"Drag\" allows a user to drag elements to reorder.                                                                                                                                               |\n| <Icon id=\"Clear\" color=\"primary.11\" boxSize=\"24px\" />         | Use for \"remove\". This removes the relationship but does **not** delete this item completely.                                                                                                   |\n| <Icon id=\"Delete\" color=\"primary.11\" boxSize=\"24px\" />        | Use for \"delete\". This is a destructive action, removes item completely.                                                                                                                        |\n\n#### Avoid these words\n\n| **Avoid Icon/Concept**                                                                                                                                                                                                                              | **Use this instead**                                                    |\n| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |\n| <Icon id=\"Check\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"CheckCircle\" color=\"primary.11\" boxSize=\"24px\" />                                                                                                                                    | Use a button with \"Save\" instead of an icon button.                     |\n| <Icon id=\"MoreHoriz\" color=\"primary.11\" boxSize=\"24px\" />                                                                                                                                                                                           | Use the vertical dot version to show more options.                      |\n| <Icon id=\"HighlightOff\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"DeleteForever\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"DoNotDisturb\" color=\"primary.11\" boxSize=\"24px\" />                                                               | If using for the same function as \"delete\" use consistent icon above.   |\n| <Icon id=\"Upload\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"CloudUpload\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"Upgrade\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"DriveFolderUpload\" color=\"primary.11\" boxSize=\"24px\" />           | If using for the same function as \"upload\" use consistent icon above.   |\n| <Icon id=\"ArrowCircleDown\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"Download\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"SimCardDownload\" color=\"primary.11\" boxSize=\"24px\" /><Icon id=\"CloudDownload\" color=\"primary.11\" boxSize=\"24px\" /> | If using for the same function as \"download\" use consistent icon above. |\n\n### Usage\n\n#### Common & effective placements:\n\n- **Toolbars**: Icon buttons are perfect for toolbars due to their compact size.\n  They allow for many actions to be readily available without cluttering the\n  interface.\n- **Navigation** bars/headers: Often used for actions like search, settings, or\n  menu access. Placement here makes these key functions easily accessible\n  throughout the app.\n- **Within** lists/grids: Icon buttons can be placed next to list items or grid\n  elements to provide actions specific to that item (e.g., edit, delete, share).\n- **Contextual** menus: Icon buttons can be used within dropdown menus or\n  context menus to provide a visual representation of available actions.\n\n#### Placement considerations:\n\n- **Related to content**: Place icon buttons close to the content they affect.\n  For example, an edit button should be near the text it's used to edit.\n- **Consistency**: Maintain consistent placement of similar icon buttons. Users\n  expect to find common actions in the same place.\n- **Groupings**: If you have multiple related icon buttons, grouping them\n  together visually. Helps users understand the relationships between the\n  actions.\n- **Avoid clutter**: Don't overcrowd your UI with too many icon buttons.\n\n> [!TIP]\\\n> When to use\n\n- Space is limited.\n- Actions are universally recognized.\n- Reinforcing meaning.\n- Adding visual appeal.\n- Supporting multiple languages.\n- Interfaces are simple and consistent.\n\n> [!CAUTION]\\\n> When not to use\n\n- Actions are ambiguous.\n- Context is crucial.\n- Actions are critical.\n- Space is plentiful.\n- Interfaces are complex.\n- Testing reveals confusion.\n\n### Color palette and style usage\n\nIcons that are on the left are the best placement. Icons are used to lead the\nuser to the right action quickly by scanning. Ok ways to break this rule are\nwith drop downs and right pointing arrows.\n\n#### Most common: Ghost\n\nThey are often seen next to tables, fields, and toolbars.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" justifyContent=\"center\">\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.ViewColumn />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.Clear />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n#### Solid and outline\n\nSolid icon buttons are most commonly seen in navigation. Outline buttons are\nmost commonly seen in groups of two representing views that can be toggled.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" justifyContent=\"center\">\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.Edit />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"outline\">\n        <Icons.Add />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n#### Critical color palette\n\nReserved for destructive actions, such as deleting something or removing a\nconnection.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" justifyContent=\"center\">\n      <IconButton colorPalette=\"critical\" variant=\"outline\">\n        <Icons.Delete />\n      </IconButton>\n      <IconButton colorPalette=\"critical\" variant=\"solid\">\n        <Icons.Delete />\n      </IconButton>\n      <IconButton colorPalette=\"critical\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n### Icon placement\n\nThe ideal placement of an icon button depends heavily on its function and the\noverall UI design. Think about the button's function, the content it relates to,\nand how users will expect to find it. Consistency and user testing are key to\noptimizing icon button placement.\n\n> [!TIP]\\\n> **Do**\n>\n> - Tools are grouped together, and adhere to current common page pattern\n>   design.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <Heading>Organization name</Heading>\n    <Tabs.Root size=\"lg\">\n      <Box position=\"relative\">\n        <Tabs.List>\n          <Tabs.Tab id=\"teams\">Teams</Tabs.Tab>\n          <Tabs.Tab id=\"settings\">Settings</Tabs.Tab>\n          <Tabs.Tab id=\"views\">Views</Tabs.Tab>\n        </Tabs.List>\n        <Stack\n          direction=\"horizontal\"\n          gap=\"0\"\n          position=\"absolute\"\n          top=\"0\"\n          right=\"0\"\n          alignItems=\"center\"\n        >\n          <IconButton colorPalette=\"primary\" variant=\"ghost\" aria-label=\"Edit\">\n            <Icons.Edit />\n          </IconButton>\n          <IconButton\n            colorPalette=\"primary\"\n            variant=\"ghost\"\n            aria-label=\"Delete\"\n          >\n            <Icons.Delete />\n          </IconButton>\n        </Stack>\n      </Box>\n      <Tabs.Panels pt=\"400\">\n        <Tabs.Panel id=\"teams\">Teams</Tabs.Panel>\n        <Tabs.Panel id=\"settings\">Settings</Tabs.Panel>\n        <Tabs.Panel id=\"views\">Views</Tabs.Panel>\n      </Tabs.Panels>\n    </Tabs.Root>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Navigation is higher hierarchy than icon button tools, this is not a common\n>   pattern.\n\n```jsx live\nconst App = () => (\n  <Stack>\n    <Heading>Organization name</Heading>\n    <Tabs.Root size=\"lg\">\n      <Box position=\"relative\">\n        <Stack\n          direction=\"horizontal\"\n          gap=\"0\"\n          position=\"absolute\"\n          top=\"0\"\n          left=\"0\"\n          alignItems=\"center\"\n        >\n          <IconButton colorPalette=\"primary\" variant=\"ghost\" aria-label=\"Edit\">\n            <Icons.Edit />\n          </IconButton>\n          <IconButton\n            colorPalette=\"primary\"\n            variant=\"ghost\"\n            aria-label=\"Delete\"\n          >\n            <Icons.Delete />\n          </IconButton>\n        </Stack>\n        <Tabs.List paddingStart=\"2000\">\n          <Tabs.Tab id=\"teams\">Teams</Tabs.Tab>\n          <Tabs.Tab id=\"settings\">Settings</Tabs.Tab>\n          <Tabs.Tab id=\"views\">Views</Tabs.Tab>\n        </Tabs.List>\n      </Box>\n      <Tabs.Panels pt=\"400\">\n        <Tabs.Panel id=\"teams\">Teams</Tabs.Panel>\n        <Tabs.Panel id=\"settings\">Settings</Tabs.Panel>\n        <Tabs.Panel id=\"views\">Views</Tabs.Panel>\n      </Tabs.Panels>\n    </Tabs.Root>\n  </Stack>\n);\n```\n\n### Button groupings\n\nButton groups are UI elements that organize multiple buttons together, often\nvisually as a single unit. They serve to present users with a set of related\nchoices or actions in a compact and organized way.\n\n> [!TIP]\\\n> **Do**\n>\n> - If you use a stack of icon buttons for actions, use max 4 and hide the rest\n>   within a \"more\" icon.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" gap=\"0\">\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.Edit />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.PushPin />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.MoreVert />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid having all the options as solid primary filled buttons.\n> - Try not to have icon buttons sandwiched between buttons.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\">\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.MoreVert />\n      </IconButton>\n      <Button colorPalette=\"primary\" variant=\"solid\">\n        Save changes\n      </Button>\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.ManageSearch />\n      </IconButton>\n      <Button colorPalette=\"primary\" variant=\"solid\">\n        <Icons.Undo />\n        Revert\n      </Button>\n    </Stack>\n  );\n};\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - When offering a toggle experience, connect these icon buttons\n> - Include a tooltip explaining the options.\n> - Selected option is using the \"Solid\" state.\n\n```jsx live\nconst App = () => {\n  return (\n    <ToggleButtonGroup.Root colorPalette=\"primary\" selectedKeys={[\"left\"]}>\n      <ToggleButtonGroup.Button id=\"left\">\n        <Icons.AccountTree />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">\n        <Icons.Search />\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - If offering a toggle like option view, do not show options as separate\n> - Does not include tooltips or labels, makes it confusing to users to\n>   understand this is a either/or choice.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" gap=\"100\">\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.AccountTree />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"outline\">\n        <Icons.Search />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - When pairing icon buttons together, use the ghost style.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" gap=\"100\">\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.Edit />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid having two primary solid icon buttons in the same area.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack direction=\"horizontal\" gap=\"100\">\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.Edit />\n      </IconButton>\n      <IconButton colorPalette=\"primary\" variant=\"solid\">\n        <Icons.Delete />\n      </IconButton>\n    </Stack>\n  );\n};\n```\n\n### Tooltips\n\nMake sure to place tooltips in areas where they will be seen easily.\n\n> [!TIP]\\\n> **Do**\n>\n> - Place tooltips so that it makes information easy to read.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack width=\"185px\">\n      <Tooltip.Root delay={0} closeDelay={0} isOpen>\n        <IconButton variant=\"ghost\" colorPalette=\"primary\" alignSelf=\"end\">\n          <Icons.ViewColumn />\n        </IconButton>\n        <Tooltip.Content placement=\"top\" offset={-37} crossOffset={-100}>\n          Table settings\n        </Tooltip.Content>\n      </Tooltip.Root>\n      <Select.Root aria-label=\"Select a category\" selectedKey=\"\">\n        <Select.Options>\n          <Select.Option id=\"productColumns\" value=\"productColumns\">\n            Product columns\n          </Select.Option>\n          <Select.Option id=\"variantColumns\" value=\"variantColumns\">\n            Variant columns\n          </Select.Option>\n          <Select.Option id=\"layoutSettings\" value=\"layoutSettings\">\n            Layout settings\n          </Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </Stack>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Be aware of overlap of element placements.\n> - Place tooltips so that it makes information easy to read.\n> - Don't use tooltips to cover the icon button.\n\n```jsx live\nconst App = () => {\n  return (\n    <Stack width=\"144px\">\n      <Tooltip.Root delay={0} closeDelay={0} isOpen>\n        <IconButton variant=\"ghost\" colorPalette=\"primary\" alignSelf=\"end\">\n          <Icons.ViewColumn />\n        </IconButton>\n        <Tooltip.Content placement=\"top\" offset={-70} crossOffset={-40}>\n          Table settings\n        </Tooltip.Content>\n      </Tooltip.Root>\n      <Select.Root aria-label=\"Select a category\" selectedKey=\"\">\n        <Select.Options>\n          <Select.Option id=\"productColumns\" value=\"productColumns\">\n            Product columns\n          </Select.Option>\n          <Select.Option id=\"variantColumns\" value=\"variantColumns\">\n            Variant columns\n          </Select.Option>\n          <Select.Option id=\"layoutSettings\" value=\"layoutSettings\">\n            Layout settings\n          </Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Box>\n        <Tooltip.Root delay={0} closeDelay={0} isOpen>\n          <IconButton variant=\"ghost\" colorPalette=\"primary\">\n            <Icons.ViewColumn />\n          </IconButton>\n          <Tooltip.Content placement=\"bottom\" crossOffset={50} offset={-25}>\n            Table settings\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Writing guidelines",
+          "href": "#writing-guidelines",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Preferred words",
+          "href": "#preferred-words",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Avoid these words",
+          "href": "#avoid-these-words",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common & effective placements:",
+          "href": "#common--effective-placements",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement considerations:",
+          "href": "#placement-considerations",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette and style usage",
+          "href": "#color-palette-and-style-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Most common: Ghost",
+          "href": "#most-common-ghost",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Solid and outline",
+          "href": "#solid-and-outline",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical color palette",
+          "href": "#critical-color-palette",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icon placement",
+          "href": "#icon-placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Button groupings",
+          "href": "#button-groupings",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tooltips",
+          "href": "#tooltips",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}