import { Canvas, Meta, Controls } from '@storybook/blocks'
import { ResourceLinks, Installation, DosAndDonts, DoOrDont } from '~storybook/components'
import * as TooltipStories from './Tooltip.docs.stories'
import AnatomyPng from './assets/tooltip_anatomy.png'
import PlacementPng from './assets/tooltip_placement.png'
import DesignSpecPng from './assets/tooltip_spec.png'
import WhenToUsePng from './assets/tooltip_variant.png'

<Meta title="Components/Tooltip/Usage Guidelines" />

# Tooltip

Updated June 25, 2024

<ResourceLinks
  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Tooltip"
  figma="https://www.figma.com/file/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-UI-Kit%3A-Heart?type=design&node-id=1929%3A32006&mode=design&t=LwTCBZ5E1uRvOA1l-1"
  designGuidelines="/?path=/docs/overlays-tooltip-next-usage-guidelines--docs"
  ariaComponentPage="https://react-spectrum.adobe.com/react-aria/Tooltip.html"
  apiSpecification="/?path=/docs/overlays-tooltip-next-api-specifications--docs"
/>

<Installation
  installCommand="pnpm add @kaizen/components"
  importStatement='import { Tooltip, TooltipTrigger } from "@kaizen/components/next"'
/>

## Overview

Tooltips are brief floating labels used to add additional contextual information when users hover, click or focus on an interactive element. These should offer concise explanations, elaborating on the element they are associated with.

<Canvas
  of={TooltipStories.Playground}
  source={{
    code: `
<TooltipTrigger>
  <Button>Button</Button>
  <Tooltip>Tooltip content</Tooltip>
</TooltipTrigger>
  `,
  }}
/>
<Controls of={TooltipStories.Playground} include={['placement', 'isOpen']} />

### Anatomy

- The anatomy of a tooltip is made up of a container, description and arrow.
  - **They do not include a title or heading**. If you need to include a title, use a Popover
- A tooltip is connected to a trigger element, such as a button or icon, that shows the tooltip when the interactive trigger element is hovered or focused. (More details below.)

<img
  src={AnatomyPng}
  alt="Indicates the anatomy of the Tooltip component, the Container, Label, Arrow and Trigger"
  className="mt-24"
/>

### When to use

- Tooltips are used to provide additional information when space is tight.
- Tooltips must be concise with one or more lines of text.
- Tooltips must be accessible via hover and focus only.
- Trigger tooltips from Interactive elements (Buttons, Links, Icon buttons) or Non-interactive elements (Icons, Abbreviations Truncated text)—be mindful of keyboard accessibility
- **Never include any kind of error messages** in a tooltip

<img src={WhenToUsePng} className="mt-32" alt="Illustration of when to use the Tooltip component" />

### Specs

<img src={DesignSpecPng} alt="" />

#### Do use tooltips to describe icons

Icons are not always easy to identify on their own. When you use components that don&apos;t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons.

<DosAndDonts>
  <DoOrDont story={TooltipStories.Primary} />
</DosAndDonts>

#### Don&apos;t use tooltips to communicate crucial information

Tooltips should never stop a user (or be a gate) from completing a task or performing an action. They disappear so they should never contain critical information that a user would absolutely need to proceed, or information without which a user may cause errors. If the information is crucial for a user to proceed, consider using a modal or inline notification instead.

<DosAndDonts>
  <DoOrDont story={TooltipStories.DoFieldTooltip} />
  <DoOrDont story={TooltipStories.DontFieldTooltip} isDont />
</DosAndDonts>

#### Do be concise

Good tooltips contain concise and helpful information, keep it short. If you need more space, consider using a Popover. Don&apos;t use it to duplicate information that already exists on the page. Instead, closely consider its placement and whether the disclosed copy will inform the action the user is about to perform.

<DosAndDonts>
  <DoOrDont story={TooltipStories.DoConcise} />
  <DoOrDont story={TooltipStories.DontConcise} isDont />
</DosAndDonts>

### Placements

<img src={PlacementPng} alt="" className="mb-24" />

- Type: Dropdown to choose from Default (dark tooltip) and Reverse (light tooltip)
- Direction: Dropdown to choose where the arrow points
- Tooltip label: Input field allows you to type in the label from the properties panel
- Use strong signifiers for trigger elements to ensure the tooltip is discoverable.
- The proximity of tooltips is always paired to the element with which they are associated.

### Trigger

- A tooltip trigger needs to be discoverable:
  - E.g. something like an icon to suggest there&apos;s a tooltip.
  - Avoid triggering tooltips from text that excludes a visual indicator (e.g. underline)
- A tooltip should be shown and accessible on hover, click or on focus events.

<DosAndDonts>
  <DoOrDont story={TooltipStories.TriggerDo} />
  <DoOrDont story={TooltipStories.TriggerDont} isDont />
</DosAndDonts>

- Only trigger tooltips from interactive elements, such as: - Buttons - Links - Icon buttons

<DosAndDonts>
  <DoOrDont story={TooltipStories.Primary} />
  <DoOrDont story={TooltipStories.TriggerLinkDescription} />
</DosAndDonts>

- Non-interactive elements (be mindful of keyboard accessibility): - Icons - Abbreviations (e.g.
  dashed underlined text for HRIS that shows a tooltip that says Human Resource Information System)
- Truncated text - For interactive elements that trigger tooltips, only have optional information
  in the tooltip because it could be missed when the user clicks