@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,594 @@
+{
+  "meta": {
+    "id": "Components-IconToggleButton",
+    "title": "Icon toggle button",
+    "exportName": "IconToggleButton",
+    "description": "An interactive icon button that toggles between two binary states such as active and inactive.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/icon-toggle-button/icon-toggle-button.mdx",
+    "menu": [
+      "Components",
+      "Buttons",
+      "Icon toggle button"
+    ],
+    "route": "components/buttons/icon-toggle-button",
+    "tags": [
+      "component",
+      "buttons",
+      "toggle",
+      "icon",
+      "controls"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visuals",
+        "href": "#visuals",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Outlined",
+        "href": "#outlined",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ghost",
+        "href": "#ghost",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=5921-47629&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\nAn icon toggle button is used similarly to a checkbox or a radio button, but\nsupports a smaller interactive component that can be used to give a binary\nactive state choice to users that can be used alone or in combination with other\nchoices. A toggle button or icon toggle button gives a user a new way of\nvisualizing the information in the interface. It does not typically perform an\naction. Please use a button or an icon button for these uses.\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=5921-47629&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Outlined\n\nMost common styling of the icon toggle button.\n\n```jsx live\nconst App = () => (\n  <IconToggleButton variant=\"outline\" aria-label=\"Pin item\">\n    <Icons.SentimentSatisfied />\n  </IconToggleButton>\n)\n```\n\n#### Ghost\n\nGhost styled buttons are helpful for UI simplification.\n\n```jsx live\nconst App = () => (\n  <IconToggleButton variant=\"ghost\" aria-label=\"Pin item\">\n    <Icons.SentimentSatisfied />\n  </IconToggleButton>\n)\n```\n\n### Size\n\nThere are three sizes to icon toggle buttons, the default size is medium (md),\nextra small (xs), and 2x-small (2xs).\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <IconToggleButton size=\"md\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n    <IconToggleButton size=\"xs\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n    <IconToggleButton size=\"2xs\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n  </Stack>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nAn icon toggle button is used similarly to a checkbox or a radio button, but\nsupports a smaller interactive component that can be used to give a binary\nactive state choice to users that can be used alone or in combination with other\nchoices. A toggle button or icon toggle button gives a user a new way of\nvisualizing the information in the interface. It does not typically perform an\naction. Please use a button or an icon button for these uses.\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=5921-47629&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Outlined\n\nMost common styling of the icon toggle button.\n\n```jsx live\nconst App = () => (\n  <IconToggleButton variant=\"outline\" aria-label=\"Pin item\">\n    <Icons.SentimentSatisfied />\n  </IconToggleButton>\n)\n```\n\n#### Ghost\n\nGhost styled buttons are helpful for UI simplification.\n\n```jsx live\nconst App = () => (\n  <IconToggleButton variant=\"ghost\" aria-label=\"Pin item\">\n    <Icons.SentimentSatisfied />\n  </IconToggleButton>\n)\n```\n\n### Size\n\nThere are three sizes to icon toggle buttons, the default size is medium (md),\nextra small (xs), and 2x-small (2xs).\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <IconToggleButton size=\"md\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n    <IconToggleButton size=\"xs\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n    <IconToggleButton size=\"2xs\" aria-label=\"Pin favorite\">\n      <Icons.SentimentSatisfied />\n    </IconToggleButton>\n  </Stack>\n)\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visuals",
+          "href": "#visuals",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Outlined",
+          "href": "#outlined",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ghost",
+          "href": "#ghost",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <IconToggleButton aria-label=\"Toggle favorite\">\n    <Icons.SentimentSatisfied />\n  </IconToggleButton>\n)\n```\n\n### Accessibility standards\n\n- **Use aria-pressed:** The most crucial accessibility attribute for a icon\n  toggle button is `aria-pressed`. When the button is \"on,\" set\n  `aria-pressed=\"true\"`. When it's \"off,\" set `aria-pressed=\"false\"`. This tells\n  screen readers that the button's function is to toggle.\n- **Provide a clear aria-label:** Since the button lacks visible text, provide a\n  descriptive `aria-label` (e.g., `aria-label=\"Toggle Bold\"` or\n  `aria-label=\"Show Advanced Settings\"`). This is what a screen reader will\n  announce to the user.\n- **Ensure keyboard operability:** Users must be able to navigate to the button\n  using the Tab key and toggle its state using the Enter or Spacebar keys.\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 { IconToggleButton, type IconToggleButtonProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe IconToggleButton component is a specialized toggle button designed for icon-only interactions. It extends the ToggleButton component with required accessibility labeling for icon content.\n\n```jsx live-dev\nconst App = () => (\n  <IconToggleButton aria-label=\"Like\" onChange={(isSelected) => console.log(isSelected)}>\n    <Icons.ThumbUp />\n  </IconToggleButton>\n)\n```\n\n## Usage examples\n\n### Visual variants\n\nIconToggleButton supports two visual variants. The `outline` variant is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconToggleButton variant=\"outline\" aria-label=\"Star (outline)\">\n      <Icons.Star />\n    </IconToggleButton>\n    <IconToggleButton variant=\"ghost\" aria-label=\"Star (ghost)\">\n      <Icons.Star />\n    </IconToggleButton>\n  </Stack>\n)\n```\n\n### Size options\n\nIconToggleButton supports three size variants. The `md` size is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconToggleButton size=\"2xs\" aria-label=\"Bookmark (2xs)\">\n      <Icons.Bookmark />\n    </IconToggleButton>\n    <IconToggleButton size=\"xs\" aria-label=\"Bookmark (xs)\">\n      <Icons.Bookmark />\n    </IconToggleButton>\n    <IconToggleButton size=\"md\" aria-label=\"Bookmark (md)\">\n      <Icons.Bookmark />\n    </IconToggleButton>\n  </Stack>\n)\n```\n\n### Color palette options\n\nUse color palettes to convey meaning and state. The `primary` color palette is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <IconToggleButton colorPalette=\"primary\" aria-label=\"Like (primary)\">\n      <Icons.ThumbUp />\n    </IconToggleButton>\n    <IconToggleButton colorPalette=\"critical\" aria-label=\"Like (critical)\">\n      <Icons.ThumbUp />\n    </IconToggleButton>\n    <IconToggleButton colorPalette=\"info\" aria-label=\"Like (info)\">\n      <Icons.Star />\n    </IconToggleButton>\n    <IconToggleButton colorPalette=\"positive\" aria-label=\"Like (positive)\">\n      <Icons.ThumbUp />\n    </IconToggleButton>\n  </Stack>\n)\n```\n\n### Controlled state\n\nUse `isSelected` and `onChange` to control the toggle state explicitly. This pattern is useful when you need to synchronize state with other parts of your application.\n\n```jsx live-dev\nconst App = () => {\n  const [isLiked, setIsLiked] = useState(false);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <IconToggleButton\n        isSelected={isLiked}\n        onChange={setIsLiked}\n        aria-label=\"Like\"\n        colorPalette=\"critical\"\n      >\n        <Icons.ThumbUp />\n      </IconToggleButton>\n      <Text>Status: {isLiked ? 'Liked' : 'Not liked'}</Text>\n    </Stack>\n  );\n}\n```\n\n### Uncontrolled state\n\nUse `defaultSelected` for uncontrolled mode when you don't need to track the state externally.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconToggleButton\n      defaultSelected={true}\n      onChange={(isSelected) => console.log('Changed to:', isSelected)}\n      aria-label=\"Star\"\n      colorPalette=\"info\"\n    >\n      <Icons.Star />\n    </IconToggleButton>\n    <Text fontSize=\"sm\">Check console for state changes</Text>\n  </Stack>\n)\n```\n\n### Disabled state\n\nUse the `isDisabled` prop to prevent interaction. This removes the button from the tab order and prevents state changes.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <IconToggleButton isDisabled aria-label=\"Like (disabled)\">\n      <Icons.ThumbUp />\n    </IconToggleButton>\n    <IconToggleButton isDisabled isSelected aria-label=\"Like (disabled selected)\">\n      <Icons.ThumbUp />\n    </IconToggleButton>\n  </Stack>\n)\n```\n\n### Multiple toggle buttons\n\nA common pattern for managing multiple independent toggle states:\n\n```jsx live-dev\nconst App = () => {\n  const [liked, setLiked] = useState(false);\n  const [starred, setStarred] = useState(false);\n  const [bookmarked, setBookmarked] = useState(false);\n\n  return (\n    <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n      <IconToggleButton\n        isSelected={liked}\n        onChange={setLiked}\n        aria-label=\"Like\"\n        colorPalette=\"critical\"\n      >\n        <Icons.ThumbUp />\n      </IconToggleButton>\n      <IconToggleButton\n        isSelected={starred}\n        onChange={setStarred}\n        aria-label=\"Star\"\n        colorPalette=\"info\"\n      >\n        <Icons.Star />\n      </IconToggleButton>\n      <IconToggleButton\n        isSelected={bookmarked}\n        onChange={setBookmarked}\n        aria-label=\"Bookmark\"\n      >\n        <Icons.Bookmark />\n      </IconToggleButton>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe IconToggleButton component requires explicit accessibility labeling since it contains only an icon without visible text.\n\n- **Labeling (REQUIRED)**: Always provide an `aria-label` that describes the button's action. The label should be descriptive enough to convey the button's purpose without visual context.\n- **Role**: Automatically assigned `role=\"button\"` with `aria-pressed` to indicate toggle state.\n- **State announcements**: Screen readers announce the pressed/unpressed state when toggled.\n\n```tsx\n// Good - Clear, action-oriented label\n<IconToggleButton aria-label=\"Like this post\">\n  <Icons.ThumbUp />\n</IconToggleButton>\n\n// Good - Context-specific label\n<IconToggleButton aria-label=\"Add to favorites\">\n  <Icons.Star />\n</IconToggleButton>\n\n// Bad - Too generic\n<IconToggleButton aria-label=\"Icon\">\n  <Icons.ThumbUp />\n</IconToggleButton>\n```\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 = \"post-like-toggle\";\n\nexport const Example = () => (\n  <IconToggleButton id={PERSISTENT_ID} aria-label=\"Like\">\n    <Icons.ThumbUp />\n  </IconToggleButton>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab`: Focuses the button\n- `Enter` or `Space`: Toggles the button state (triggers `onChange`)\n\n## API reference\n\n<PropsTable id=\"IconToggleButton\" />\n\n## Common patterns\n\n### Like/favorite buttons\n\nA common use case for toggle buttons in social features:\n\n```jsx live-dev\nconst App = () => {\n  const [likeCount, setLikeCount] = useState(42);\n  const [isLiked, setIsLiked] = useState(false);\n\n  const handleLikeToggle = (selected) => {\n    setIsLiked(selected);\n    setLikeCount((count) => selected ? count + 1 : count - 1);\n  };\n\n  return (\n    <Stack direction=\"row\" gap=\"300\" alignItems=\"center\">\n      <IconToggleButton\n        isSelected={isLiked}\n        onChange={handleLikeToggle}\n        aria-label={isLiked ? \"Unlike\" : \"Like\"}\n        colorPalette=\"critical\"\n      >\n        <Icons.ThumbUp />\n      </IconToggleButton>\n      <Text fontSize=\"sm\">{likeCount} likes</Text>\n    </Stack>\n  );\n}\n```\n\n### Toolbar actions\n\nToggle buttons work well in toolbars for formatting and view options:\n\n```jsx live-dev\nconst App = () => {\n  const [bold, setBold] = useState(false);\n  const [italic, setItalic] = useState(false);\n  const [underline, setUnderline] = useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\">\n        <IconToggleButton\n          isSelected={bold}\n          onChange={setBold}\n          aria-label=\"Toggle bold\"\n          variant=\"ghost\"\n        >\n          <Icons.FormatBold />\n        </IconToggleButton>\n        <IconToggleButton\n          isSelected={italic}\n          onChange={setItalic}\n          aria-label=\"Toggle italic\"\n          variant=\"ghost\"\n        >\n          <Icons.FormatItalic />\n        </IconToggleButton>\n        <IconToggleButton\n          isSelected={underline}\n          onChange={setUnderline}\n          aria-label=\"Toggle underline\"\n          variant=\"ghost\"\n        >\n          <Icons.FormatUnderlined />\n        </IconToggleButton>\n      </Stack>\n      <Text fontSize=\"sm\">\n        Active: {[bold && 'Bold', italic && 'Italic', underline && 'Underline'].filter(Boolean).join(', ') || 'None'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n\n\n### Async state updates\n\nHandle asynchronous operations when toggling state:\n\n```jsx live-dev\nconst App = () => {\n  const [isSubscribed, setIsSubscribed] = useState(false);\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handleToggle = async (selected) => {\n    setIsLoading(true);\n    // Simulate API call\n    await new Promise(resolve => setTimeout(resolve, 1000));\n    setIsSubscribed(selected);\n    setIsLoading(false);\n  };\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <IconToggleButton\n        isSelected={isSubscribed}\n        onChange={handleToggle}\n        isDisabled={isLoading}\n        aria-label={isSubscribed ? \"Unsubscribe\" : \"Subscribe\"}\n        colorPalette=\"info\"\n      >\n        <Icons.Notifications />\n      </IconToggleButton>\n      <Text fontSize=\"sm\">\n        {isLoading ? 'Processing...' : isSubscribed ? 'Subscribed' : 'Not subscribed'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using IconToggleButton in your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the component renders with expected accessibility attributes\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Basic rendering\", () => {\n  it(\"renders with aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like this post\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /like this post/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with pressed state attribute\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /like/i });\n    expect(button).toHaveAttribute(\"aria-pressed\", \"false\");\n  });\n\n  it(\"renders unselected by default\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Star\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"false\");\n  });\n});\n```\n\n### Selection State Tests\n\nTest different selection states (selected/unselected)\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Selection states\", () => {\n  it(\"renders selected state\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" isSelected>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n\n  it(\"renders unselected state explicitly\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" isSelected={false}>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"false\");\n  });\n\n  it(\"applies default selected state\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Star\" defaultSelected>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the component\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Interactions\", () => {\n  it(\"toggles when clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"false\");\n\n    await user.click(button);\n\n    expect(button).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n\n  it(\"calls onChange callback when toggled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Star\" onChange={handleChange}>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    await user.click(button);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"toggles with spacebar when focused\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Bookmark\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\" \");\n\n    expect(screen.getByRole(\"button\")).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n\n  it(\"toggles with enter key when focused\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\"{Enter}\");\n\n    expect(screen.getByRole(\"button\")).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n});\n```\n\n### Testing Controlled Mode\n\nTest controlled component behavior\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton\n          aria-label=\"Like\"\n          isSelected={true}\n          onChange={() => {}}\n        >\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n\n  it(\"updates when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <IconToggleButton\n          aria-label=\"Star\"\n          isSelected={false}\n          onChange={() => {}}\n        >\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toHaveAttribute(\"aria-pressed\", \"false\");\n\n    rerender(\n      <NimbusProvider>\n        <IconToggleButton\n          aria-label=\"Star\"\n          isSelected={true}\n          onChange={() => {}}\n        >\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toHaveAttribute(\"aria-pressed\", \"true\");\n  });\n\n  it(\"calls onChange when user interacts with controlled button\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <IconToggleButton\n          aria-label=\"Like\"\n          isSelected={false}\n          onChange={handleChange}\n        >\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    await user.click(button);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Testing Validation States\n\nTest different validation and state variations\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" isDisabled>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toBeDisabled();\n  });\n\n  it(\"does not toggle when disabled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Star\" isDisabled onChange={handleChange}>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    await user.click(button);\n\n    expect(button).toHaveAttribute(\"aria-pressed\", \"false\");\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"renders selected and disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" isSelected isDisabled>\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\");\n    expect(button).toHaveAttribute(\"aria-pressed\", \"true\");\n    expect(button).toBeDisabled();\n  });\n});\n```\n\n### Testing Visual Variants\n\nTest that different visual variants render correctly\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 { IconToggleButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { ThumbUp } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"IconToggleButton - Visual variants\", () => {\n  it(\"renders outline variant\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" variant=\"outline\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders ghost variant\", () => {\n    render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Star\" variant=\"ghost\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders different size variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" size=\"2xs\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" size=\"xs\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" size=\"md\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with different color palettes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" colorPalette=\"primary\">\n          <ThumbUp />\n        </IconToggleButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <IconToggleButton aria-label=\"Like\" colorPalette=\"critical\">\n          <ThumbUp />\n        </IconToggleButton>\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-icontogglebutton--docs)\n- [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html)\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": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette options",
+          "href": "#color-palette-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled state",
+          "href": "#controlled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled state",
+          "href": "#uncontrolled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple toggle buttons",
+          "href": "#multiple-toggle-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "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": "Like/favorite buttons",
+          "href": "#likefavorite-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Toolbar actions",
+          "href": "#toolbar-actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async state updates",
+          "href": "#async-state-updates",
+          "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": "Selection State Tests",
+          "href": "#selection-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Controlled Mode",
+          "href": "#testing-controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Validation States",
+          "href": "#testing-validation-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Visual Variants",
+          "href": "#testing-visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nIcon toggle button guidelines aim to provide clear and consistent visual\nfeedback to users for compact binary states.\n\n### Best practices\n\n- **Avoid setting a default toggle as active:** Instead, let users choose their\n  preference. If one option is selected more frequently, make it the default,\n  while still allowing users to switch to the less popular choice.\n- **Intuitive icons:** Use icons that are universally recognized for the action\n  they represent. Consider adding a tooltip on hover to provide a text label to\n  help a user understand what is being chosen.\n- **Maintain visual consistency:** The icon's style (line weight, color, fill)\n  should be consistent with the rest of the icons in the design system to ensure\n  a cohesive look and feel.\n- **Provide immediate feedback:** The button should visually respond instantly\n  when a user clicks or taps it, providing reassurance that the action was\n  successful.\n- **Communicate meaningful changes:** If a toggle button makes a significant\n  change (ex: updating default payment) pair this toggled action with a toast\n  message to better communicate the change when needed.\n\n##### Toggle Groups (Segmented Controls)\n\n- **Enforce mutual exclusivity:** Use toggle groups (segmented controls) when\n  the user must select only one option from a small, defined set, similar to\n  radio button behavior (e.g., alignment controls, viewing modes).\n- **Limit options:** Keep the number of options within a group small (ideally 3\n  to 5) to prevent overcrowding and ensure each button is easily tappable.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Compact binary states:** Use them for on/off settings in toolbars or\n  space-limited areas (e.g., toggling bold text, muting).\n- **Clear, universal actions:** Use them for actions whose icon is immediately\n  understood without a text label (e.g., Pin, Star).\n- **Quick filtering:** Use them for providing quick, visual controls for\n  filtering items or selecting a mode.\n- **Frequent interactions:** Use them when an action is performed often to save\n  time and screen space.\n- **Instant application:** When the action takes effect immediately without\n  requiring the user to press a separate \"Save\" or \"Submit\" button.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Ambiguous actions:** Do not use them when the icon's meaning is unclear or\n  requires the user to guess; use a text label or tooltip.\n- **Complex or multi-state processes:** Avoid using them for actions that\n  require more than two states or sequential steps; use a segmented button or\n  switch.\n- **Critical, permanent actions:** Do not use them for destructive or major\n  actions; use a full text button with confirmation.\n- **Core navigation:** Avoid making primary navigation items toggle-able unless\n  they explicitly switch between two main views.\n- **Multi-select options:** If the user can select multiple items from a list,\n  use checkboxes instead.\n- **Multi-state options:** If the user needs to select one option from three or\n  more choices, use radio buttons or a segmented control instead.\n- **Actions requiring confirmation:** Do not use for actions that are\n  destructive, irreversible, or require confirmation (e.g., deleting an account,\n  submitting a payment). Use a standard button that triggers a confirmation\n  dialog.\n- **Complex settings:** Avoid using a toggle if the result of the action isn't\n  clear or if the setting requires additional input fields to be configured.\n- **Triggers for new pages:** Do not use a toggle to navigate to a new section\n  or page; use a link or standard button for navigation.\n- **Long-running processes:** For actions that take time to complete (e.g.,\n  \"Start Backup\"), a standard button that displays a loading spinner upon press\n  is more appropriate.\n\n### Icon toggle buttons in use\n\n> [!TIP]\\\n> **Do**\n>\n> - Do use icon toggle buttons for a simple binary choice (on/off).\n> - Do place them in toolbars or areas where space is limited.\n> - Do ensure the \"on\" state is clearly distinct from the \"off\" state.\n> - Do connect buttons that toggle one active state among a small selection of\n>   options.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" alignItems=\"start\">\n    <Toolbar orientation=\"horizontal\">\n      <Select.Root\n        size=\"sm\"\n        variant=\"ghost\"\n        aria-label=\"Select a text style\"\n        defaultSelectedKey=\"p\"\n        isClearable={false}\n      >\n        <Select.Options>\n          <Select.Option id=\"h1\">Heading 1</Select.Option>\n          <Select.Option id=\"h2\">Heading 2</Select.Option>\n          <Select.Option id=\"h3\">Heading 3</Select.Option>\n          <Select.Option id=\"p\">Paragraph</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Separator orientation=\"vertical\" />\n      <Group>\n        <IconToggleButton size=\"xs\" variant=\"ghost\" aria-label=\"Bold\">\n          <Icons.FormatBold />\n        </IconToggleButton>\n        <IconToggleButton size=\"xs\" variant=\"ghost\" aria-label=\"Italic\">\n          <Icons.FormatItalic />\n        </IconToggleButton>\n        <IconToggleButton size=\"xs\" variant=\"ghost\" aria-label=\"Underline\">\n          <Icons.FormatUnderlined />\n        </IconToggleButton>\n        <IconButton size=\"xs\" variant=\"ghost\">\n          <Icons.MoreHoriz />\n        </IconButton>\n      </Group>\n      <Separator orientation=\"vertical\" />\n      <Group>\n        <IconToggleButton size=\"xs\" variant=\"ghost\" aria-label=\"Bulleted list\">\n          <Icons.FormatListBulleted />\n        </IconToggleButton>\n        <IconToggleButton size=\"xs\" variant=\"ghost\" aria-label=\"Numbered list\">\n          <Icons.FormatListNumbered />\n        </IconToggleButton>\n      </Group>\n    </Toolbar>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't use them for multi-step processes or complex selections.\n> - Don't use an ambiguous icon without a tooltip or a text label.\n> - Don't use an icon toggle button, when you should use an icon button instead.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\">\n    <IconToggleButton aria-label=\"Sign language\">\n      <Icons.SignLanguage />\n    </IconToggleButton>\n    <IconToggleButton aria-label=\"Delete\">\n      <Icons.Delete />\n    </IconToggleButton>\n    <IconToggleButton aria-label=\"Copy\">\n      <Icons.FileCopy />\n    </IconToggleButton>\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Toggle Groups (Segmented Controls)",
+          "href": "#toggle-groups-segmented-controls",
+          "depth": 5,
+          "numbering": [
+            1,
+            1,
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icon toggle buttons in use",
+          "href": "#icon-toggle-buttons-in-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}