{
  "title": "Tooltip",
  "path": "/components/tooltip",
  "url": "https://design.werklist.com/components/tooltip",
  "text": "https://design.werklist.com/agent/components/tooltip",
  "summary": "A tooltip names an icon button or shows its shortcut when the pointer rests on it or the keyboard reaches it.",
  "version": "2.1.2",
  "kind": "component",
  "name": "Tooltip",
  "purpose": "One line of text next to a control, shown on pointer rest or keyboard focus, that names it, shows its shortcut, shows a truncated value in full or says why it is unavailable.",
  "use": [
    "An icon button without a visible label",
    "A control with a keyboard shortcut",
    "A truncated value, to show it in full",
    "An unavailable control, to say what would make it available"
  ],
  "avoid": [
    "Anything people need to finish a task",
    "Links, buttons or formatted text: use a popover",
    "System feedback: use a toast or an inline message",
    "Touch screens: tooltips do not show there",
    "Repeating a visible label",
    "Tips that open by themselves to teach a feature"
  ],
  "anatomy": [
    {
      "part": "Layer",
      "measure": "above the page",
      "token": "--layer-popover"
    },
    {
      "part": "Text",
      "measure": "12 px on an 18 px line, weight 400",
      "token": "--text"
    },
    {
      "part": "Padding",
      "measure": "4 px above and below, 8 px at the sides",
      "token": "--space-1, --space-2"
    },
    {
      "part": "Height",
      "measure": "26 px, 30 px with a keycap"
    },
    {
      "part": "Radius",
      "measure": "8 px",
      "token": "--radius-lg"
    },
    {
      "part": "Surface",
      "measure": "translucent glass under a 36 px blur, with an inset top highlight, a 1 px inset rim and a soft shadow. Solid where the blur cannot render or transparency is reduced"
    },
    {
      "part": "Gap and window margin",
      "measure": "8 px and at least 8 px",
      "token": "--space-2"
    },
    {
      "part": "Maximum width",
      "measure": "the window width less 16 px"
    },
    {
      "part": "Keycap",
      "measure": "11 px on a 16 px line, weight 500, tabular, at least 26 px wide, 22 px high, radius 6 px, a 1 px inset edge in the border ink",
      "token": "--surface-control, --border, --text-label, --radius-md"
    }
  ],
  "states": [
    {
      "name": "Showing on pointer rest",
      "change": "After 500 ms, fades in over 150 ms with 4 px of travel away from the control",
      "tokens": [
        "--duration-fast",
        "--ease-soft"
      ]
    },
    {
      "name": "Showing on keyboard focus",
      "change": "At once, same fade",
      "tokens": [
        "--duration-fast"
      ]
    },
    {
      "name": "Moving between triggers",
      "change": "The next shows at once while one is showing"
    },
    {
      "name": "Hiding",
      "change": "When the pointer leaves both the control and the tooltip, when focus leaves, on Escape, on a press. Fades over 150 ms",
      "tokens": [
        "--duration-fast",
        "--ease-standard"
      ]
    },
    {
      "name": "Reduced motion",
      "change": "The fade stays, the travel goes",
      "tokens": [
        "--duration-fast"
      ]
    },
    {
      "name": "Touch screen",
      "change": "Does not show"
    }
  ],
  "keys": [
    {
      "key": "Tab onto the control",
      "action": "Shows the tooltip at once"
    },
    {
      "key": "Escape",
      "action": "Hides the tooltip. Focus stays on the control"
    }
  ],
  "accessibility": [
    "role tooltip with an id. The control references it with aria-describedby when the tooltip adds to the name",
    "When the tooltip repeats an icon button's aria-label, the tooltip is aria-hidden true",
    "aria-keyshortcuts on the control for its shortcut",
    "Unavailable controls that explain themselves use aria-disabled true, not disabled, so they receive hover and focus",
    "The native title attribute is removed from any control with a tooltip",
    "People can move the pointer onto the tooltip. It stays while hovered or focused and does not time out",
    "Escape hides the tooltip before it closes anything behind it"
  ],
  "content": [
    "A verb phrase or a noun phrase in sentence case, with no full stop",
    "Not the visible label again",
    "For an unavailable control, the condition: Select a candidate first",
    "At most 60 characters"
  ],
  "tokens": [
    "--layer-popover",
    "--radius-lg",
    "--radius-md",
    "--space-1",
    "--space-2",
    "--text",
    "--text-label",
    "--surface-control",
    "--border",
    "--duration-fast",
    "--ease-soft",
    "--ease-standard"
  ]
}