@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,715 @@
+{
+  "meta": {
+    "id": "Components-Button",
+    "title": "Button",
+    "exportName": "Button",
+    "description": "A button serves as a standardized, reusable component for triggering actions and navigating.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/button/button.mdx",
+    "menu": [
+      "Components",
+      "Buttons",
+      "Button"
+    ],
+    "route": "components/buttons/button",
+    "tags": [
+      "component",
+      "buttons",
+      "forms"
+    ],
+    "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": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Primary actions",
+        "href": "#primary-actions",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Secondary actions",
+        "href": "#secondary-actions",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Tertiary actions",
+        "href": "#tertiary-actions",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Icons in buttons",
+        "href": "#icons-in-buttons",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Icons before or after in buttons",
+        "href": "#icons-before-or-after-in-buttons",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          4,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Color palette",
+        "href": "#color-palette",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Primary",
+        "href": "#primary",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          6,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Critical",
+        "href": "#critical",
+        "depth": 4,
+        "numbering": [
+          1,
+          1,
+          6,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2569",
+    "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": "## Overview\n\nButtons are clickable elements that initiate actions. They're how we encourage\nusers to take action and explore different parts of our interface.\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-2569)\n\n### Hierarchy\n\n#### Primary actions\n\nPrimary colorPalette, filled style, medium size. For the principal call to action on the\npage. Primary buttons should only appear once per screen.\n\n- **A solid button** should be used as a primary action on a page used to\n  highlight the most important or most common action a user is likely to take in\n  that context. It serves to guide the user towards the desired path and make\n  the key interaction clear and prominent.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"primary\" size=\"md\" variant=\"solid\">\n   <Icons.Add />\n   Primary action\n </Button>\n)\n```\n\n#### Secondary actions\n\nPrimary color palette, outline style, medium size. Represents a less important or\nalternative action compared to the primary button.\n\n- **An outlined button** should be used as for secondary actions that are less\n  important or less frequent than the primary action. They provide users with\n  alternative options without distracting from the main call to action.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"primary\" variant=\"outline\" size=\"md\">\n   <Icons.Replay />\n   Secondary action\n </Button>\n)\n```\n\n#### Tertiary actions\n\nPrimary color palette, link styled, xsmall size. For lesser-performed actions or a\ncollection of actions — those that users are unlikely to perform.\n\n- **Ghost buttons** are used when you want a button to be visible but less\n  visually prominent than a primary or secondary button. These can apply to\n  tertiary actions such as drop downs and contextual actions.\n- **Link buttons** can be used when the focus should be on the content rather\n  than the UI controls themselves. They are less visually distracting and allow\n  the content to take center stage. This is common in content-heavy applications\n  or dashboards. Link and Ghost styled buttons are most used in tertiary\n  actions, and are styled in X-small or 2X-small sizes.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\">\n    <Button size=\"md\" variant=\"ghost\">\n      Filter\n    </Button>\n    <Button size=\"xs\" variant=\"link\">\n      Expand options\n      <Icons.KeyboardArrowDown />\n   </Button>\n </Stack>\n)\n```\n\n### Variables\n\nGet familiar with the features.\n\n### Icons in buttons\n\n#### Icons before or after in buttons\n\nThe default position of icons in primary and secondary buttons are to the left\nof the text, but we allow for icons to follow for special uses such as drop\ndowns, steppers, and expansion links. For icon placement best practices refer to\nour guidelines.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.SentimentSatisfied />\n      Solid\n      <Icons.SentimentSatisfied />\n    </Button>\n    <Button size=\"md\" variant=\"outline\">\n      <Icons.SentimentSatisfied />\n      Outline\n      <Icons.SentimentSatisfied />\n   </Button>\n    <Button size=\"md\" variant=\"ghost\">\n      <Icons.SentimentSatisfied />\n      Ghost\n      <Icons.SentimentSatisfied />\n   </Button>\n    <Button size=\"md\" variant=\"link\">\n      <Icons.SentimentSatisfied />\n      Link\n      <Icons.SentimentSatisfied />\n   </Button>\n </Stack>\n)\n```\n\n### Size\n\n**Medium** (40px)\n\nThis is the default and preferred size for buttons.\n\n```jsx live\nconst App = () => (\n  <Button size=\"md\" variant=\"solid\">\n   Save\n </Button>\n)\n```\n\n**X-Small** (32px)\n\nIf there is a space constraint, use these buttons. Ideally will be used\nsparingly.\n\n```jsx live\nconst App = () => (\n <Button size=\"xs\" variant=\"solid\">\n   Apply filters\n </Button>\n)\n```\n\n**2x-Small** (24px)\n\nUsed mainly for Ghost and Link buttons, these buttons can be seen in filters\nwhere the size constraint is tightest.\n\n```jsx live\nconst App = () => (\n  <Button size=\"2xs\" variant=\"ghost\">\n   <Icons.Edit />\n   Edit Filters\n </Button>\n)\n```\n\n### Color palette\n\n#### Primary\n\nThis is the default `colorPalette` for the primary button. This styling should be used\nmost commonly for all actions.\n\n```jsx live\nconst App = () => (\n  <Button size=\"md\" variant=\"solid\">\n    <Icons.SentimentSatisfied />\n      Button\n    <Icons.SentimentSatisfied />\n  </Button>\n)\n```\n\n#### Critical\n\nUse this button when the user is approaching a permanent destructive action.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"critical\" size=\"md\" variant=\"solid\">\n    <Icons.SentimentSatisfied />\n      Button\n    <Icons.SentimentSatisfied />\n  </Button>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "## Overview\n\nButtons are clickable elements that initiate actions. They're how we encourage\nusers to take action and explore different parts of our interface.\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-2569)\n\n### Hierarchy\n\n#### Primary actions\n\nPrimary colorPalette, filled style, medium size. For the principal call to action on the\npage. Primary buttons should only appear once per screen.\n\n- **A solid button** should be used as a primary action on a page used to\n  highlight the most important or most common action a user is likely to take in\n  that context. It serves to guide the user towards the desired path and make\n  the key interaction clear and prominent.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"primary\" size=\"md\" variant=\"solid\">\n   <Icons.Add />\n   Primary action\n </Button>\n)\n```\n\n#### Secondary actions\n\nPrimary color palette, outline style, medium size. Represents a less important or\nalternative action compared to the primary button.\n\n- **An outlined button** should be used as for secondary actions that are less\n  important or less frequent than the primary action. They provide users with\n  alternative options without distracting from the main call to action.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"primary\" variant=\"outline\" size=\"md\">\n   <Icons.Replay />\n   Secondary action\n </Button>\n)\n```\n\n#### Tertiary actions\n\nPrimary color palette, link styled, xsmall size. For lesser-performed actions or a\ncollection of actions — those that users are unlikely to perform.\n\n- **Ghost buttons** are used when you want a button to be visible but less\n  visually prominent than a primary or secondary button. These can apply to\n  tertiary actions such as drop downs and contextual actions.\n- **Link buttons** can be used when the focus should be on the content rather\n  than the UI controls themselves. They are less visually distracting and allow\n  the content to take center stage. This is common in content-heavy applications\n  or dashboards. Link and Ghost styled buttons are most used in tertiary\n  actions, and are styled in X-small or 2X-small sizes.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\">\n    <Button size=\"md\" variant=\"ghost\">\n      Filter\n    </Button>\n    <Button size=\"xs\" variant=\"link\">\n      Expand options\n      <Icons.KeyboardArrowDown />\n   </Button>\n </Stack>\n)\n```\n\n### Variables\n\nGet familiar with the features.\n\n### Icons in buttons\n\n#### Icons before or after in buttons\n\nThe default position of icons in primary and secondary buttons are to the left\nof the text, but we allow for icons to follow for special uses such as drop\ndowns, steppers, and expansion links. For icon placement best practices refer to\nour guidelines.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.SentimentSatisfied />\n      Solid\n      <Icons.SentimentSatisfied />\n    </Button>\n    <Button size=\"md\" variant=\"outline\">\n      <Icons.SentimentSatisfied />\n      Outline\n      <Icons.SentimentSatisfied />\n   </Button>\n    <Button size=\"md\" variant=\"ghost\">\n      <Icons.SentimentSatisfied />\n      Ghost\n      <Icons.SentimentSatisfied />\n   </Button>\n    <Button size=\"md\" variant=\"link\">\n      <Icons.SentimentSatisfied />\n      Link\n      <Icons.SentimentSatisfied />\n   </Button>\n </Stack>\n)\n```\n\n### Size\n\n**Medium** (40px)\n\nThis is the default and preferred size for buttons.\n\n```jsx live\nconst App = () => (\n  <Button size=\"md\" variant=\"solid\">\n   Save\n </Button>\n)\n```\n\n**X-Small** (32px)\n\nIf there is a space constraint, use these buttons. Ideally will be used\nsparingly.\n\n```jsx live\nconst App = () => (\n <Button size=\"xs\" variant=\"solid\">\n   Apply filters\n </Button>\n)\n```\n\n**2x-Small** (24px)\n\nUsed mainly for Ghost and Link buttons, these buttons can be seen in filters\nwhere the size constraint is tightest.\n\n```jsx live\nconst App = () => (\n  <Button size=\"2xs\" variant=\"ghost\">\n   <Icons.Edit />\n   Edit Filters\n </Button>\n)\n```\n\n### Color palette\n\n#### Primary\n\nThis is the default `colorPalette` for the primary button. This styling should be used\nmost commonly for all actions.\n\n```jsx live\nconst App = () => (\n  <Button size=\"md\" variant=\"solid\">\n    <Icons.SentimentSatisfied />\n      Button\n    <Icons.SentimentSatisfied />\n  </Button>\n)\n```\n\n#### Critical\n\nUse this button when the user is approaching a permanent destructive action.\n\n```jsx live\nconst App = () => (\n  <Button colorPalette=\"critical\" size=\"md\" variant=\"solid\">\n    <Icons.SentimentSatisfied />\n      Button\n    <Icons.SentimentSatisfied />\n  </Button>\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": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Primary actions",
+          "href": "#primary-actions",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Secondary actions",
+          "href": "#secondary-actions",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tertiary actions",
+          "href": "#tertiary-actions",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icons in buttons",
+          "href": "#icons-in-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icons before or after in buttons",
+          "href": "#icons-before-or-after-in-buttons",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Primary",
+          "href": "#primary",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical",
+          "href": "#critical",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            6,
+            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\nThe Button component uses `onPress\\*` props to handle all user\ninteractions—mouse clicks, touch taps, and keyboard presses—consistently. These\nprops (`onPress`, `onPressStart`, `onPressEnd`, etc.) ensure a smooth and\naccessible experience regardless of the user's input method or device.\n\n```jsx live\nconst App = () => (\n  <Button size=\"md\" variant=\"solid\" onPress={() => alert(\"clicked!\")}>\n    Click me... with your keyboard\n  </Button>\n)\n```\n\n### Accessibility standards\n\n- **Color contrast for text:** The contrast ratio between the button text and\n  the button background should be at least 4.5:1 for normal text and 3:1 for\n  large text.\n- **Color contrast for button:** The contrast ratio between the button's\n  background color and the surrounding page background should be at least 3:1.\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 the\n  button's meaning is clear to everyone, including people with color blindness.\n- **Focus indicator:** Provide a clear visual indicator when the button receives\n  keyboard focus. This helps users understand which element is currently active.\n  The focus indicator must not be hidden by other content on the page and must\n  meet certain visibility requirements to be easily seen.\n- **Keyboard accessibility:** Buttons must be operable using a keyboard. Users\n  should be able to navigate to the button using the Tab key and activate it\n  using the Enter or Space key.\n- **Target size:** Ensure that the button is large enough to be easily\n  clickable, especially on touchscreens. WCAG recommends a minimum target size\n  of 24x24 CSS pixels.\n- **Dragging movements:** If a button's function relies on dragging, an\n  alternative method should be provided that doesn't require dragging.\n- **Clear labels:** The button's text label should clearly describe its\n  function.\n- **Consistent design:** Use buttons consistently throughout your website. This\n  helps users learn the meaning of each button and makes it easier for them to\n  navigate your site.\n- **Findable help:** If users might need help understanding how to use a button\n  or what it does, provide clear and easily findable help resources.\n- **Assistive technology compatibility:** Ensure that buttons are compatible\n  with assistive technologies like screen readers. This often involves using\n  proper HTML markup and ARIA attributes to provide semantic information about\n  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 { Button, type ButtonProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe Button component wraps React Aria's `useButton` hook to provide accessible, interactive elements.\n\n```jsx live-dev\nconst App = () => (\n  <Button onPress={() => alert('Button pressed')}>\n    Action\n  </Button>\n)\n```\n\n## Usage examples\n\n### Size options\n\nButton supports three size variants to match different interface densities. The `md` size is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Button size=\"2xs\">2XS Button</Button>\n    <Button size=\"xs\">XS Button</Button>\n    <Button size=\"sm\">SM Button</Button>\n    <Button size=\"md\">MD Button (Default)</Button>\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between five visual variants to match your design context. The `subtle` variant is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Button variant=\"solid\">Solid</Button>\n    <Button variant=\"subtle\">Subtle (Default)</Button>\n    <Button variant=\"outline\">Outline</Button>\n    <Button variant=\"ghost\">Ghost</Button>\n    <Button variant=\"link\">Link</Button>\n  </Stack>\n)\n```\n\n### Color palette options\n\nThe Button component supports all semantic color palettes to convey meaning and hierarchy. The `primary` color palette is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"primary\">Primary (Default)</Button>\n      <Button colorPalette=\"neutral\">Neutral</Button>\n      <Button colorPalette=\"info\">Info</Button>\n    </Stack>\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"positive\">Positive</Button>\n      <Button colorPalette=\"warning\">Warning</Button>\n      <Button colorPalette=\"critical\">Critical</Button>\n    </Stack>\n  </Stack>\n)\n```\n\nYou can also override the color palette using Chakra UI style props for one-off customizations:\n\n```jsx live-dev\nconst App = () => (\n  <Button backgroundColor=\"purple.9\" color=\"purple.contrast\" _hover={{ backgroundColor: \"purple.10\" }}>\n    Custom Purple Button\n  </Button>\n)\n```\n\n### With icons\n\nButtons automatically handle spacing between icons and text. You can place icons before or after the text.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button>\n      <Icons.Add />\n      Add Item\n    </Button>\n    <Button variant=\"outline\">\n      Next\n      <Icons.ArrowForward />\n    </Button>\n  </Stack>\n)\n```\n\n### As link\n\nUse the `as` prop to render the button as an anchor tag while maintaining button styling. This is useful for navigation links that need to look like actions.\n\n```jsx live-dev\nconst App = () => (\n  <Button as=\"a\" href=\"#\" variant=\"link\">\n    Go to Home\n  </Button>\n)\n```\n\n### Disabled state\n\nUse the `isDisabled` prop to prevent interaction. This visualizes the button as disabled and removes it from the tab order.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button isDisabled variant=\"solid\">Disabled Solid</Button>\n    <Button isDisabled variant=\"outline\">Disabled Outline</Button>\n  </Stack>\n)\n```\n\n### Event handling\n\nUse `onPress` instead of `onClick` for consistent behavior across mouse, touch, and keyboard interactions.\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Button onPress={() => setCount(c => c + 1)}>\n        Increment\n      </Button>\n      <Text>Count: {count}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Button component handles most accessibility requirements internally via React Aria.\n\n- **Labeling**: Ensure the button has a visible label (children) or an `aria-label` if it contains only an icon.\n- **Role**: Renders as `button` by default, or `link` (a tag) when using `as=\"a\"`.\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 = \"submit-order-button\";\n\nexport const Example = () => (\n  <Button id={PERSISTENT_ID}>Submit</Button>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab`: Focuses the button.\n- `Enter` or `Space`: Activates the button (triggers `onPress`).\n\n## API reference\n\n<PropsTable id=\"Button\" />\n\n## Common patterns\n\n### Loading state\n\nWhile the Button component doesn't have a built-in `isLoading` prop yet, you can implement a loading state by disabling the button and showing a spinner.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handleClick = () => {\n    setIsLoading(true);\n    // Simulate async action\n    setTimeout(() => setIsLoading(false), 2000);\n  };\n\n  return (\n    <Button \n      isDisabled={isLoading} \n      onPress={handleClick}\n    >\n      {isLoading ? 'Loading...' : 'Save Changes'}\n    </Button>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Button 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 Button renders with expected content and 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 { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Basic rendering\", () => {\n  it(\"renders with correct text\", () => {\n    render(\n      <NimbusProvider>\n        <Button>Click me</Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /click me/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with custom data attributes\", () => {\n    render(\n      <NimbusProvider>\n        <Button data-testid=\"my-button\">Action</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"my-button\")).toBeInTheDocument();\n  });\n\n  it(\"renders as an anchor element when using the as prop\", () => {\n    render(\n      <NimbusProvider>\n        <Button as=\"a\" href=\"/home\" data-testid=\"link-button\">\n          Go Home\n        </Button>\n      </NimbusProvider>\n    );\n\n    const element = screen.getByTestId(\"link-button\");\n    expect(element.tagName).toBe(\"A\");\n    expect(element).toHaveAttribute(\"href\", \"/home\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the Button\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 { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Interactions\", () => {\n  it(\"calls onPress when clicked\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Action</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/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        <Button isDisabled onPress={handlePress}>\n          Action\n        </Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/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 Button\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 { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Keyboard navigation\", () => {\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button>Focus me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /focus me/i });\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        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/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        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/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 Button\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 { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - States\", () => {\n  it(\"applies disabled state on native button\", () => {\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Disabled</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /disabled/i });\n    expect(button).toBeDisabled();\n  });\n\n  it(\"is not focusable when disabled\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Cannot focus</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /cannot focus/i });\n    await user.tab();\n\n    expect(button).not.toHaveFocus();\n  });\n});\n```\n\n### Visual Variant Tests\n\nTest rendering with 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 { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Visual variants\", () => {\n  it(\"renders with different size variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Button size=\"sm\">Small</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button size=\"md\">Medium</Button>\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        <Button variant=\"solid\">Solid</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button variant=\"outline\">Outline</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with color palettes\", () => {\n    render(\n      <NimbusProvider>\n        <Button colorPalette=\"primary\" variant=\"solid\">\n          Primary\n        </Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /primary/i })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-buttons-button--docs)\n- [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html)\n\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 palette options",
+          "href": "#color-palette-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icons",
+          "href": "#with-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "As link",
+          "href": "#as-link",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Event handling",
+          "href": "#event-handling",
+          "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": "Loading state",
+          "href": "#loading-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "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": "# Button Guidelines\n\nButtons are essential interactive elements that empower users to trigger actions\nand navigate within your product. They serve as clear calls to action, guiding\nusers through key flows and enabling them to interact with content in meaningful\nways. These guidelines ensure consistent styling and behavior for all buttons,\ncontributing to a cohesive and predictable user experience.\n\n## Writing guidelines\n\n- A good button label tells you exactly what will happen when you click it,\n  making the whole experience more intuitive and enjoyable.\n- Use concise and clear action based language for all buttons.\n- Use sentence case, capitalize the first word and use lowercase for the rest.\n- Be aware that with localization/translation character count will add on\n  average 20% more length.\n\n## Preferred words\n\n| **Text**                                | **Description**                                                                                                                                                                                                                                                                                                        |\n| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Save**                                | Carries out pending changes, commits to saving the information.                                                                                                                                                                                                                                                        |\n| **Back**                                | This term typically implies a return to a previous state or location in a non-linear or less structured flow. It's often used for:<ul style={{listStyle: \"disc\", marginLeft: \"20px\"}}><li>Navigating browser history</li><li>Exiting a screen or section</li></ul>                                                     |\n| **Previous**                            | This term is more common in linear, sequential flows, such as: <ul style={{listStyle: \"disc\", marginLeft: \"20px\"}}><li>Stepping through a list of items</li><li>Moving between pages in a paginated view</li><li>Progressing through a multi-step process</li></ul> <br />Pair \"Previous\" with \"Next\" button language. |\n| **Add new (noun)**                      | Establishes a new object from scratch. Always followed by an object. For example \"add product\" \"add category\".<br/><br/>Can also be used in areas that establishes a new relationship. Example \"add products to a category\".<br/><br/>Do not use \"add new\" as it does not give full context.                           |\n| **Revert changes**                      | \"Revert\" stops an action without saving pending changes. When paired with a form it should return the information to the previously saved state. Never make Revert changes red, it is not a destructive action.                                                                                                        |\n| **Cancel**                              | \"Cancel\" stops an action without saving pending changes. Never make Cancel red, it is not a destructive action. Cancel should be outline, ghost or link button.                                                                                                                                                        |\n| **Delete or Delete (X nouns)**          | Deletes a data so a user can no longer retrieve it. This is different from Remove.                                                                                                                                                                                                                                     |\n| **Remove**                              | Removes a relationship, but does not permanently delete data.                                                                                                                                                                                                                                                          |\n| **Expand/Collapse Show more/Show less** | Expands or collapses further details and information. No capitalization is needed for these placements.                                                                                                                                                                                                                |\n\n## Avoid these words\n\n| **Text**                      | **Use this instead**                                                             |\n| ----------------------------- | -------------------------------------------------------------------------------- |\n| **New**                       | Be more specific about what the user is creating.                                |\n| **Continue**                  | Use \"Next\" instead of \"Continue\" instead to maintain consistency.                |\n| **Create new (noun)**         | Use \"Add (noun)\" instead of \"create\" in button language to maintain consistency. |\n| **OK, Sure, Fine, Yes, No**   | Use words that explain the action.                                               |\n| **Wow! Yes? DELETE NOW! No?** | Avoid full capitalization and punctuation.                                       |\n\n## Usage\n\n**A primary filled button** highlights the most important action a user can\ntake. For example, it might be used to save changes, submit a form, or emphasize\na key action like adding a discount.\n\n**Secondary and tertiary** (primary color palette with outline and linked styling) buttons\nare used when there's already a primary action on the page. They're for less\nprominent actions, like canceling changes, supporting the primary action, going\nback in a process, or expanding/collapsing information.\n\n**Buttons with 'critical' color palette** are reserved for destructive actions, such as\ndeleting something or removing a connection.\n\n> [!TIP]\\\n> When to use\n\n- **Trigger an action:** Anything that happens (save, delete, submit, download,\n  etc.).\n- **Control a process:** Start, stop, pause, resume, undo, redo.\n- **Confirm a choice:** \"Yes,\" \"Save changes,\" Confirm.\n- **Open something:** Modal, popover, dialog.\n- **Select an option:** Especially complex or visual choices.\n  <br />\n\n> [!CAUTION]\\\n> When not to use\n\n- **Navigation:** Use links, not buttons, for page/section navigation.\n- **Too many:** Avoid button overload; group actions or use menus.\n- **Simple actions:** Icons suffice for basic actions (e.g., close, play/pause).\n- **Non-interactive:** Don't make non-clickable elements look like buttons.\n- **Accessibility:** Misusing buttons confuses assistive tech.\n- **Visual clutter:** Too many button styles dilute meaning.\n- **Progressive disclosure:** Reveal options gradually for complex tasks.\n- **Data display:** Use labels, not buttons, for showing info.\n- **Simpler controls:** Use checkboxes, radios, toggles when appropriate.\n- **Too much text:** Truncate text if translation is too long, but look for\n  better solutions or different wording.\n\n## Icons in buttons\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<br />\n\n> [!TIP]\\\n> **Do**\n>\n> - Use the correct and consistently patterned icon for the action that a user\n>   will be selecting.\n> - Ok ways to break this rule are with drop downs and right pointing arrows.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.Undo />\n      Revert\n    </Button>\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.FileUpload />\n      Upload\n   </Button>\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.Add />\n      Add product\n   </Button>\n    <Button size=\"md\" variant=\"outline\">\n      <Icons.ArrowBack />\n      Previous\n   </Button>\n    <Button size=\"md\" variant=\"solid\">\n      Next\n      <Icons.ArrowForward />\n   </Button>\n </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Icons should represent the action the user will be taking.\n> - Don't use two icons to represent an action. One icon will do.\n> - Left icons are the default unless there is directional reason.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"solid\">\n      <Icons.Upload />\n       Delete\n      <Icons.Upload />\n    </Button>\n    <Button colorPalette=\"critical\" size=\"md\" variant=\"solid\">\n      <Icons.Clear />\n        Add discount\n      <Icons.Clear />\n    </Button>\n    <Button size=\"md\" variant=\"solid\">\n      Revert\n      <Icons.Undo />\n    </Button>\n </Stack>\n)\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - Use right icons to build a drop down component with the Popover component.\n> - Icons are on the left unless there is a directional reason to use a right\n>   icon placement.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Stack>\n      <Button size=\"md\" variant=\"outline\">\n        Save changes\n        <Icons.KeyboardArrowDown />\n      </Button>\n     <Card.Root elevation=\"elevated\" cardPadding=\"md\">\n        <Card.Content>\n        <div style={{fontSize: \"16px\", fontWeight: \"400\"}}>\n        <p>Save</p>\n        <p>Save and publish</p>\n        <p>Save and open next</p>\n        </div>\n        </Card.Content>\n      </Card.Root>\n    </Stack>\n    <Stack>\n      <Button size=\"md\" variant=\"solid\">\n        <Icons.FileUpload />\n        Export categories\n        <Icons.KeyboardArrowDown />\n      </Button>\n      <Card.Root elevation=\"elevated\" cardPadding=\"md\">\n        <Card.Content>\n        <div style={{fontSize: \"16px\", fontWeight: \"400\"}}>\n        <p>Export as csv</p>\n        <p>Download to drive</p>\n        </div>\n        </Card.Content>\n      </Card.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Dropdown icons should always be on the right side.\n> - Don't place action describing icons on the right if a drop down is wanted.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\">\n    <Stack>\n      {['2xs','xs','md'].map((size) => (\n        <Stack key={size} direction=\"horizontal\">\n          <Button size={size} colorPalette=\"positive\" variant=\"solid\" startIcon={<Icons.Check />}>\n            <Icons.Check />\n            Yes\n          </Button>\n          <Button size={size} colorPalette=\"critical\" variant=\"solid\" startIcon={<Icons.X />}>\n            <Icons.Close />\n            No\n          </Button>\n          <Button size={size} colorPalette=\"neutral\" variant=\"ghost\" endIcon={<Box animation=\"spin\" asChild><Icons.Loader/></Box>}>\n             Maybe\n             <Icons.HelpOutline />\n          </Button>\n        </Stack>\n      ))}\n    </Stack>\n    <Stack>\n      <Button size=\"md\" variant=\"solid\">\n        <Icons.KeyboardArrowDown />\n        Export categories\n        <Icons.FileUpload />\n      </Button>\n      <Card.Root elevation=\"elevated\" cardPadding=\"md\">\n        <Card.Content>\n        <div style={{fontSize: \"16px\", fontWeight: \"400\"}}>\n        <p>Export as csv</p>\n        <p>Download to drive</p>\n        </div>\n        </Card.Content>\n      </Card.Root>\n    </Stack>\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> - This is the correct hierarchy of button groupings. From right to left,\n>   Primary, Outlined, and Link button.\n\n```jsx live\n  const App = () => (\n  <Stack direction=\"horizontal\">\n    <Button as=\"a\" size=\"md\" variant=\"link\">\n      Cancel and close\n    </Button>\n    <Button size=\"md\" variant=\"outline\">\n      <Icons.Undo />\n      Revert\n    </Button>\n    <Button size=\"md\" variant=\"solid\">\n      Save changes\n    </Button>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid stacking actions.\n> - Don't use two buttons with the primary color palette in the same area.\n\n```jsx live\n  const App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" colorPalette=\"primary\" variant=\"solid\">\n      Save changes\n    </Button>\n    <Button size=\"md\" colorPalette=\"primary\" variant=\"solid\">\n      <Icons.Undo />\n      Revert\n    </Button>\n    <Button size=\"md\" colorPalette=\"primary\" variant=\"ghost\">\n      Cancel and close\n    </Button>\n  </Stack>\n)\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - Place the filled primary button to the right. This should represent the\n>   action most likely taken by a user.\n> - Outlined secondary button to the left of the primary action.\n> - Icon is on the left of the button.\n\n```jsx live\n  const App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"outline\">\n      <Icons.Undo />\n      Revert\n    </Button>\n    <Button size=\"md\" variant=\"solid\">\n      Save\n    </Button>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not place the filled primary button to the left of another option.\n> - Do not have two primary filled buttons near each other.\n> - Do not include punctuation in buttons.\n\n```jsx live\n  const App = () => (\n  <Stack direction=\"horizontal\">\n    <Button size=\"md\" variant=\"solid\">\n      Cancel!\n    </Button>\n    <Button size=\"md\" variant=\"solid\">\n      Save.\n    </Button>\n    <Button as=\"a\" size=\"sm\" variant=\"link\">\n      External link\n      <Icons.Launch />\n    </Button>\n  </Stack>\n)\n```\n\n## Button links\n\nThese actions are likely seen when an action is optional to have more or less\ninformation shown.\n\n> [!TIP]\\\n> **Do**\n>\n> - Expand actions should be placed at the lower center or left hand side of the\n>   element that will expand/collapse.\n> - Link button is using the correct size, 2x-small.\n\n```jsx live\n const App = () => (\n  <>\n   <div style={{\n     width: \"300px\",\n     height: \"40px\",\n     backgroundColor: \"#f0f8ff\",\n     border: \"1px dashed #60a5fa\",\n     borderRadius: \"12px\",\n     display: \"flex\",\n     justifyContent: \"center\",\n     alignItems: \"center\",\n     position: \"relative\",\n   }}>\n     <span style={{\n       fontSize: \"10px\",\n       color: \"#3b82f6\",\n       letterSpacing: \"1px\",\n     }}>Trigger</span>\n  </div>\n    <Button as=\"a\" size=\"2xs\" variant=\"link\" marginLeft=\"220px\">\n      <Icons.KeyboardArrowDown />\n      expand\n    </Button>\n</>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - The button is too large for this placement\n> - Expansion icons should be placed to the left side of the label to allow for\n>   easier scanning by a user.\n\n```jsx live\n  const App = () => (\n  <>\n   <div style={{\n     width: \"300px\",\n     height: \"40px\",\n     backgroundColor: \"#f0f8ff\",\n     border: \"1px dashed #60a5fa\",\n     borderRadius: \"12px\",\n     display: \"flex\",\n     justifyContent: \"center\",\n     alignItems: \"center\",\n     position: \"relative\",\n   }}>\n     <span style={{\n       fontSize: \"10px\",\n       color: \"#3b82f6\",\n       letterSpacing: \"1px\",\n     }}>Trigger</span>\n  </div>\n    <Button as=\"a\" size=\"md\" variant=\"link\" marginLeft=\"200px\">\n      expand\n      <Icons.KeyboardArrowDown />\n    </Button>\n</>\n)\n```\n",
+      "toc": [
+        {
+          "value": "Writing guidelines",
+          "href": "#writing-guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Preferred words",
+          "href": "#preferred-words",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Avoid these words",
+          "href": "#avoid-these-words",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icons in buttons",
+          "href": "#icons-in-buttons",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Button groupings",
+          "href": "#button-groupings",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Button links",
+          "href": "#button-links",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}