Tooltip: anchoredPosition + IconButton

docs/content/IconButton.mdx

@@ -35,6 +35,16 @@ A separate component called `IconButton` is used if the action shows only an ico
 </>
 ```
 
+### Customize description / tooltip text
+
+To add description for the button, wrap `IconButton` in a `Tooltip`. Make sure you pass `aria-label` to the button as well.
+
+```jsx live
+<Tooltip text="You have no unread notifications">
+  <IconButton icon={BellIcon} aria-label="Notifications" />
+</Tooltip>
+```
+
 ## API reference
 
 Native `<button>` HTML attributes are forwarded to the underlying React `button` component and are not listed below.

docs/content/Tooltip.mdx

@@ -0,0 +1,192 @@
+---
+componentId: tooltip
+title: Tooltip
+status: Alpha
+source: https://github.com/primer/react/tree/main/src/Tooltip
+storybook: '/react/storybook?path=/story/composite-components-tooltip'
+description: The Tooltip component adds a tooltip to add context to elements on the page.
+---
+
+Tooltip only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. [Consider these alternatives](https://primer.style/design/accessibility/tooltip-alternatives).
+
+import {Tooltip, IconButton, Button} from '@primer/react'
+import {BellIcon, MentionIcon} from '@primer/octicons-react'
+import InlineCode from '@primer/gatsby-theme-doctocat/src/components/inline-code'
+
+<Box
+  sx={{
+    display: 'flex',
+    justifyContent: 'center',
+    border: '1px solid',
+    borderColor: 'border.default',
+    borderRadius: 2,
+    padding: 6,
+    paddingTop: 8,
+    marginBottom: 3
+  }}
+>
+  <Tooltip text="You have no unread notifications" sx={{visibility: 'visible', opacity: 1}}>
+    <IconButton icon={BellIcon} aria-label="Notifications" />
+  </Tooltip>
+</Box>
+
+When using a tooltip, follow the provided guidelines to avoid accessibility issues.
+
+- Tooltip text should be brief and to the point.
+- Tooltips should contain only **non-essential text**. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information.
+
+## Examples
+
+### As a description for icon-only button
+
+If the tooltip content provides supplementary description, wrap the target in a `Tooltip`. The trigger element should also have a concise accessible label via `aria-label`.
+
+```jsx live
+<Tooltip text="Directly mention a team or user">
+  <IconButton aria-label="Mentions" icon={MentionIcon} variant="invisible" />
+</Tooltip>
+```
+
+### As a description for a button with visible label
+
+```jsx live
+<Tooltip text="This will immediately impact all organization members">
+  <Button variant="primary">Save</Button>
+</Tooltip>
+```
+
+### With direction
+
+Set direction of tooltip with `direction`. The tooltip is responsive and will automatically adjust direction to avoid cutting off.
+
+```jsx live
+<Box
+  sx={{
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 8,
+    marginY: 4,
+    '[data-component=tooltip]': {visibility: 'visible', opacity: 1}
+  }}
+>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="nw" text="Tooltip text">
+      <Button>North West</Button>
+    </Tooltip>
+    <Tooltip direction="n" text="Tooltip text">
+      <Button>North</Button>
+    </Tooltip>
+    <Tooltip direction="ne" text="Tooltip text">
+      <Button>North East</Button>
+    </Tooltip>
+  </Box>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="e" text="Tooltip text">
+      <Button>East</Button>
+    </Tooltip>
+    <Tooltip direction="w" text="Tooltip text">
+      <Button>West</Button>
+    </Tooltip>
+  </Box>
+  <Box sx={{display: 'flex', justifyContent: 'space-between', gap: 1}}>
+    <Tooltip direction="sw" text="Tooltip text">
+      <Button>South West</Button>
+    </Tooltip>
+    <Tooltip direction="s" text="Tooltip text">
+      <Button>South</Button>
+    </Tooltip>
+    <Tooltip direction="se" text="Tooltip text">
+      <Button>South East</Button>
+    </Tooltip>
+  </Box>
+</Box>
+```
+
+## Props
+
+<PropsTable>
+  <PropsTableRow name="children" required type="React.ReactNode" description="Tooltip target, single element" />
+
+  <PropsTableRow
+    name="text"
+    type="string"
+    description="The text content of the tooltip. This should be brief and no longer than a sentence"
+  />
+  <PropsTableRow
+    deprecated
+    name="aria-label"
+    type="string"
+    description={
+      <>
+        Use <InlineCode>text</InlineCode> instead
+      </>
+    }
+  />
+  <PropsTableRow
+    name="type"
+    type="description | label"
+    defaultValue="description"
+    description={
+      <>
+        Use <InlineCode>aria-describedby</InlineCode> or <InlineCode>aria-labelledby</InlineCode>
+      </>
+    }
+  />
+  <PropsTableRow
+    name="direction"
+    type="nw | n | ne | e | se | s | sw | w"
+    defaultValue="n"
+    description="Sets where the tooltip renders in relation to the target"
+  />
+  <PropsTableRow name="align" deprecated type="left | right" description="Use direction instead. Alignment relative to target" />
+  <PropsTableRow
+    name="noDelay"
+    type="boolean"
+    defaultValue="false"
+    description={
+      <>
+        When set to <InlineCode>true</InlineCode>, tooltip appears without any delay
+      </>
+    }
+  />
+  <PropsTableRow
+    name="wrap"
+    type="boolean"
+    deprecated
+    description={
+      <>
+        Use to allow text within tooltip to wrap. Deprecated: always set to <InlineCode>true</InlineCode> now.
+      </>
+    }
+  />
+  <PropsTableSxRow />
+</PropsTable>
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    hasStorybookStories: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: true,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: true
+  }}
+/>
+
+## Further reading
+
+- [Tooltip alternatives](https://primer.style/design/accessibility/tooltip-alternatives)
+
+## Related components
+
+- [IconButton](/IconButton)