Documentation for Stable release

docs/stories/00-getting started/Troubleshooting.mdx

@@ -0,0 +1,71 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Troubleshooting" />
+
+# Troubleshooting
+
+## Layout shift when opening Modals or Dialogs (due to radix-ui -> react-remove-scroll)
+
+If you notice a layout shift when opening Modals or Dialogs, this is caused by the `react-remove-scroll` library used by
+`@radix-ui/react-dialog` to prevent background scrolling when a dialog is open.
+
+To fix this, you can add the following CSS to your global styles:
+
+```css
+html,
+body {
+  width: calc(100% - var(--removed-body-scroll-bar-size), 0px);
+}
+```
+
+You will also need to set a background color on the `body` to avoid a white flash when opening a Modal or Dialog:
+
+```css
+body {
+  background: [your-background-color];
+}
+```
+
+## Focus outline is visible when using mouse
+
+By default, browsers show focus outlines when elements are focused, regardless of the input method (keyboard or mouse).
+This can lead to a less-than-ideal user interface when using a mouse.
+
+To improve the user experience, you can use [`what-input`](https://github.com/ten1seven/what-input) library to
+conditionally apply focus styles based on the input method.
+
+Install and import `what-input` in your project.
+
+Then, add the following CSS to your global styles:
+
+```css
+[data-whatintent='mouse'] *:focus {
+  outline: none;
+}
+```
+
+This will hide focus outlines when using a mouse, while still allowing keyboard users to see focus indicators for
+accessibility.
+
+## Popovers not appearing above other elements
+
+If you notice that Popovers are not appearing above other elements, you may need to adjust the default radix-ui popper
+z-index by adding the following CSS to your global styles:
+
+```css
+[data-radix-popper-content-wrapper] {
+  z-index: 300 !important;
+}
+```
+
+## Disabled links are still clickable
+
+If you have a link that is disabled but still clickable, you can add the following CSS to your global styles to prevent
+pointer events on disabled links:
+
+```css
+a[aria-disabled='true'] {
+  pointer-events: none;
+  cursor: default;
+}
+```

docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

@@ -196,10 +196,28 @@ If you don't do this, the props for `MyBox` are all inferred as `Record<string,
 
 Some specific props have been removed from components:
 
-- `error` prop from `Accordion` component
-- `noBorder` prop from `IconButton`
-- `active` prop from `PageLink`
-- `showBullet` from `Status`
+#### `Accordion` component
+
+- `error` prop is no longer supported
+
+#### `IconButton` component
+
+- `noBorder` prop is no longer supported
+- To achieve the same effect, use styled-components:
+
+```tsx
+const IconButtonWithoutBorder = styled(IconButton)`
+  border: 0;
+`;
+```
+
+#### `PageLink` component
+
+- `active` prop has been removed
+
+#### `Status` component
+
+- `showBullet` prop has been removed
 
 ### Removed CMS specific components
 

docs/stories/02-primitives/Combobox.mdx

@@ -74,30 +74,26 @@ The `Combobox` primitive is composed of the following components:
 and is combined in the following way:
 
 ```tsx
-() => {
-  return (
-    <Combobox.Root>
-      <Combobox.Trigger>
-        <Combobox.TextInput placeholder="Pick me" />
-        <Combobox.Icon />
-      </Combobox.Trigger>
-      <Combobox.Portal>
-        <Combobox.Content>
-          <Combobox.Viewport>
-            <Combobox.Item value="1">
-              <Combobox.ItemText>Option 1</Combobox.ItemText>
-              <Combobox.ItemIndicator>
-                <Check />
-              </Combobox.ItemIndicator>
-            </Combobox.Item>
-            <Combobox.NoValueFound>No value found</Combobox.NoValueFound>
-            <Combobox.CreateItem>Create a new value</Combobox.CreateItem>
-          </Combobox.Viewport>
-        </Combobox.Content>
-      </Combobox.Portal>
-    </Combobox.Root>
-  );
-};
+<Combobox.Root>
+  <Combobox.Trigger>
+    <Combobox.TextInput placeholder="Pick me" />
+    <Combobox.Icon />
+  </Combobox.Trigger>
+  <Combobox.Portal>
+    <Combobox.Content>
+      <Combobox.Viewport>
+        <Combobox.Item value="1">
+          <Combobox.ItemText>Option 1</Combobox.ItemText>
+          <Combobox.ItemIndicator>
+            <Check />
+          </Combobox.ItemIndicator>
+        </Combobox.Item>
+        <Combobox.NoValueFound>No value found</Combobox.NoValueFound>
+        <Combobox.CreateItem>Create a new value</Combobox.CreateItem>
+      </Combobox.Viewport>
+    </Combobox.Content>
+  </Combobox.Portal>
+</Combobox.Root>
 ```
 
 ## API Reference
@@ -106,30 +102,22 @@ and is combined in the following way:
 
 <ArgTypes of={Combobox.Root} />
 
-### Trigger
-
-### TextInput
-
-### Icon
-
 ### Portal
 
 <ArgTypes of={Combobox.Portal} />
 
 ### Content
 
-### Viewport
+<ArgTypes of={Combobox.Content} />
 
 ### Item
 
-### ItemText
-
-### ItemIndicator
-
-### NoValueFound
+<ArgTypes of={Combobox.Item} />
 
 ### CreateItem
 
+<ArgTypes of={Combobox.CreateItem} />
+
 ## Accessibility
 
 Adheres to the [Combobox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)