docs(tooltip): updated docs for accessbility (#5497)

* docs(tooltip): updating tooltip docs

* docs(tooltip): updating tooltip docs

* docs(tooltip): updated tooltip directive docs

* docs(tooltip): renamed tooltip-directive readme

* docs(tooltip): updated based on PR feedback

* docs(tooltip): fixed typo

Author: nikkimk

packages/tooltip/README.md

@@ -1,133 +1,193 @@
-## Description
+## Overview
 
-`sp-tooltip` allow users to get contextual help or information about specific components when hovering or focusing on them.
+`<sp-tooltip>` allow users to get contextual help or information about specific components when hovering or focusing on them.
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/tooltip?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/tooltip)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/tooltip?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/tooltip)
 [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-cizgmpks)
 
-```
+```bash
 yarn add @spectrum-web-components/tooltip
 ```
 
 Import the side effectful registration of `<sp-tooltip>` via:
 
-```
+```javascript
 import '@spectrum-web-components/tooltip/sp-tooltip.js';
 ```
 
 When looking to leverage the `Tooltip` base class as a type and/or for extension purposes, do so via:
 
-```
+```javascript
 import { Tooltip } from '@spectrum-web-components/tooltip';
 ```
 
-## Example
+### Anatomy
 
-Tooltips can be top, bottom, left, or right.
-
-```html
-<sp-tooltip open placement="top">Label</sp-tooltip>
-<br />
-<br />
-<sp-tooltip open placement="bottom">Label</sp-tooltip>
-<br />
-<br />
-<sp-tooltip open placement="left">Label</sp-tooltip>
-<br />
-<br />
-<sp-tooltip open placement="right">Label</sp-tooltip>
-```
+The tooltip consists of several key parts:
 
-### Self-managed overlays
-
-By default, Tooltip provides styling without behavior.
-You must combine it with an [Overlay Trigger](https://opensource.adobe.com/spectrum-web-components/components/overlay-trigger/#%22hover%22-content-only) in order to manage its overlay behavior.
-
-You can use the tooltip as the descendant of an interactive element, such as [Action Button](https://opensource.adobe.com/spectrum-web-components/components/action-button/), by applying the `self-managed` attribute which automatically binds the Tooltip to its first interactive ancestor element's focus/hover interactions:
+- The message content in its default slot
+- An optional icon using `slot="icon"`
+- A tip element that points to the trigger
 
 ```html
-<sp-action-button>
-    Trigger
-    <sp-tooltip self-managed>Content</sp-tooltip>
-</sp-action-button>
+<sp-tooltip open>
+    <sp-icon-info slot="icon"></sp-icon-info>
+    Tooltip message
+</sp-tooltip>
 ```
 
-This is especially useful when inserting an intermediate `<overlay-trigger>` would interfere with
-parent/child relationships, such as between `<sp-action-group>` and `<sp-action-button>`.
-
-Note that an interactive element is an element that can receive focus during tab navigation, such as `sp-action-button`, `sp-action-menu`, `sp-field-label` etc.
+### Options
 
-Given that tooltip is not focusable by itself, it would not show up during tab navigation. Thus a tooltip would not be accessible if used with a non-interactive element, such as `<sp-icon-*>`.
+#### Placement
 
-The correct way to make it accessible would be to wrap it under an interactive element, such as `sp-action-button`:
+Tooltips can be positioned relative to their trigger element using the `placement` attribute:
 
 ```html
-<sp-action-button size="s">
-    <sp-icon-info slot="icon"></sp-icon-info>
-    <sp-tooltip self-managed placement="right">
-        Display something here
-    </sp-tooltip>
-</sp-action-button>
+<sp-tooltip open placement="left">Left</sp-tooltip>
+<sp-tooltip open placement="bottom">Bottom</sp-tooltip>
+<sp-tooltip open placement="right">Right</sp-tooltip>
+<sp-tooltip open placement="top">Top</sp-tooltip>
 ```
 
-## Variants
+#### Variants
+
+The tooltip supports several variants to convey different types of messages:
 
-### Informative
+<sp-tabs selected="info" auto label="Variant Options">
+<sp-tab value="info">Info</sp-tab>
+<sp-tab-panel value="info">
 
-This is the informative or info variant of Tooltip
+Use `variant="info"` for informational messages.
 
 ```html
-<sp-tooltip open placement="top" variant="info">Label</sp-tooltip>
-<sp-tooltip open placement="top" variant="info">
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
-</sp-tooltip>
 <sp-tooltip open placement="top" variant="info">
     <sp-icon-info slot="icon" size="s"></sp-icon-info>
-    Label
-</sp-tooltip>
-<sp-tooltip open placement="top" variant="info">
-    <sp-icon-info slot="icon" size="s"></sp-icon-info>
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    Embark on a side quest.
 </sp-tooltip>
 ```
 
-### Positive
+</sp-tab-panel>
+<sp-tab value="positive">Positive</sp-tab>
+<sp-tab-panel value="positive">
 
-This is the postive (a.k.a.) success variant of Tooltip
+Use `variant="positive"` for success messages.
 
 ```html
-<sp-tooltip open placement="top" variant="positive">Label</sp-tooltip>
-<sp-tooltip open placement="top" variant="positive">
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
-</sp-tooltip>
 <sp-tooltip open placement="top" variant="positive">
     <sp-icon-checkmark-circle slot="icon" size="s"></sp-icon-checkmark-circle>
-    Label
-</sp-tooltip>
-<sp-tooltip open placement="top" variant="positive">
-    <sp-icon-checkmark-circle slot="icon" size="s"></sp-icon-checkmark-circle>
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    Quest completed!
 </sp-tooltip>
 ```
 
-### Negative
+</sp-tab-panel>
+<sp-tab value="negative">Negative</sp-tab>
+<sp-tab-panel value="negative">
 
-This is the negative a.k.a. error variant of Tooltip
+Use `variant="negative"` for error messages.
 
 ```html
-<sp-tooltip open placement="top" variant="negative">Label</sp-tooltip>
-<sp-tooltip open placement="top" variant="negative">
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
-</sp-tooltip>
 <sp-tooltip open placement="top" variant="negative">
     <sp-icon-alert slot="icon" size="s"></sp-icon-alert>
-    Label
-</sp-tooltip>
-<sp-tooltip open placement="top" variant="negative">
-    <sp-icon-alert slot="icon" size="s"></sp-icon-alert>
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit
+    Quest failed!
 </sp-tooltip>
 ```
+
+</sp-tab-panel>
+</sp-tabs>
+
+### Behaviors
+
+#### Overlay
+
+By default, Tooltip provides styling without behavior.
+
+<sp-tabs selected="overlay-trigger" auto label="Overlay Behaviors">
+<sp-tab value="overlay-trigger">Overlay Trigger</sp-tab>
+<sp-tab-panel value="overlay-trigger">
+
+You must combine it with an [Overlay Trigger](https://opensource.adobe.com/spectrum-web-components/components/overlay-trigger/#%22hover%22-content-only) to manage its overlay behavior.
+
+```html
+<overlay-trigger triggered-by="hover">
+    <sp-button slot="trigger" variant="secondary">Hover me</sp-button>
+    <sp-tooltip slot="hover-content" placement="bottom">
+        Tooltip overlay triggered by hover
+    </sp-tooltip>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="self-managed">Self-managed</sp-tab>
+<sp-tab-panel value="self-managed">
+
+For simpler use cases, you can use the `self-managed` attribute which automatically binds the Tooltip to its first interactive ancestor element's focus/hover interactions:
+
+```html
+<sp-action-button>
+    Items
+    <sp-tooltip self-managed>Use items during battle.</sp-tooltip>
+</sp-action-button>
+```
+
+This is especially useful when inserting an intermediate `<overlay-trigger>` would interfere with parent/child relationships, such as between `<sp-action-group>` and `<sp-action-button>`.
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Delayed Opening
+
+A tooltip can be configured to delay its opening using the `delayed` attribute. This adds a warm-up period of 1000ms before showing the tooltip:
+
+```html
+<sp-action-button>
+    Show delayed tooltip
+    <sp-tooltip self-managed delayed>
+        This tooltip will show after a delay
+    </sp-tooltip>
+</sp-action-button>
+```
+
+### Accessibility
+
+The tooltip is automatically assigned appropriate ARIA attributes:
+
+- `role="tooltip"` is applied to the tooltip content
+- The tooltip is associated with its trigger element via `aria-describedby`
+
+When using `self-managed` tooltips:
+
+- The tooltip appears on hover or focus of the trigger element
+- The tooltip disappears when focus or hover leaves the trigger element
+- <kbd>Escape</kbd> dismisses the tooltip
+
+#### Use tooltips to describe icons
+
+Icons are not always easy to identify on their own. When you use components that don’t have labels — for example, icon-only action buttons and tabs — make sure to use tooltips to provide context for the icons.
+
+Given that tooltip is not focusable by itself, it would not show up during tab navigation. A tooltip should only be used with interactive elements that can receive focus during tab navigation, such as:
+
+- `<sp-action-button>`
+- `<sp-action-menu>`
+- `<sp-field-label>`
+
+For non-interactive elements like icons, wrap them in an interactive element:
+
+```html
+<sp-action-button size="s">
+    <sp-icon-book slot="icon"></sp-icon-book>
+    <sp-tooltip self-managed placement="right">Save progress.</sp-tooltip>
+</sp-action-button>
+```
+
+#### Use plain text in your tooltips
+
+Because a tooltip is not focusable by itself, it should not contain any interactive elements. Additionally, because a tooltip is referenced in an `aria-describedby` attribute, it should not contain any rich formatting, such as headings, lists, bold, italic, or other complex content.
+
+#### Don't use tooltips to communicate crucial information
+
+Show crucial information at all times, not just when a tooltip is displayed. A tooltip should only be used to provide supplementary context or hints to the message shown in help text.
+
+For example, in a scenario where a user is entering their password into a field, the crucial information would be to state the password requirements. Supplementary context would be a message about how to get help if they have forgotten their password.

packages/tooltip/directive.md renamed to packages/tooltip/tooltip-directive.md

@@ -1,30 +1,30 @@
-## Description
+## Overview
 
-While `<sp-tooltip>` element are general fairly innocumous amounts of DOM, it is possible that your page will quickly leverage so many Tooltips that their presence could begin to negatively effect its performane. To support consumers that leverage `lit-html`, Spectrum Web Components also vends a [directive](https://lit.dev/docs/api/directives/) to further simplify the delivery of `<sp-tooltip>` elements.
+While `<sp-tooltip>` elements are generally fairly innocuous amounts of DOM, it is possible impact performance with too many Tooltips. To support consumers that use `lit-html`, Spectrum Web Components also proives a [directive](https://lit.dev/docs/api/directives/) to improve performance when using many `<sp-tooltip>` elements.
 
-### Uusage
+### Usage
 
 ```
 yarn add @spectrum-web-components/tooltip
 ```
 
-Import the `trigger` directive as follows:
+Import the tooltip directive as follows:
 
 ```
 import { tooltip } from '@spectrum-web-components/tooltip/src/tooltip-directive.js';
 ```
 
-## Arguments
+### Anatomy
 
-The `trigger()` directive accepts two arguments:
+The tooltip directive consists of two main parts:
 
--   a required method returning the `TemplateResult` defining the content of the open overlay
+1. A method returning the `TemplateResult` defining the content of the open overlay:
 
 ```ts
 () => TemplateResult;
 ```
 
--   an optional options object which is shaped as follows:
+2. An optional options object for configuring the tooltip behavior:
 
 ```ts
 {
@@ -36,9 +36,15 @@ The `trigger()` directive accepts two arguments:
 }
 ```
 
-The `triggerInteraction` is applied as `hover` when using the `tooltip()` directive.
+### Options
 
-`OverlayOptions` are leveraged in the same way as outlined [here](https://opensource.adobe.com/spectrum-web-components/components/imperative-api/#overlayoptions) and `InsertionOptions` are leveraged to outline where in the DOM the Overlay should be inserted:
+#### Overlay Options
+
+The `overlayOptions` are leveraged in the same way as outlined [here](https://opensource.adobe.com/spectrum-web-components/components/imperative-api/#overlayoptions).
+
+#### Insertion Options
+
+The `insertionOptions` define where in the DOM the Overlay should be inserted:
 
 ```ts
 type InsertionOptions = {
@@ -47,14 +53,13 @@ type InsertionOptions = {
 };
 ```
 
-## Consumption via `lit-html`
+### Behaviors
 
-The `tooltip()` directive will automatically wrap whatever content you provide in an `<sp-tooltip>` element for you, so you will not need to supply one in this case.
+#### Consumption via `lit-html`
 
-Pass a `TemplateResult` into the `tooltip()` directive, as follows in order to have it rendered to the DOM when the associated Tooltip is about to open and the removed after the Tooltip has closed.
+The `tooltip()` directive will automatically wrap whatever content you provide in an `<sp-tooltip>` element. Pass a `TemplateResult` into the `tooltip()` directive to have it rendered to the DOM when the associated Tooltip is about to open and then removed after the Tooltip has closed.
 
 ```html-live
-
 <div id="root"></div>
 
 <script type="module">
@@ -71,7 +76,6 @@ Pass a `TemplateResult` into the `tooltip()` directive, as follows in order to h
         })}>Trigger</sp-button>
     `;
 
-
     customElements.whenDefined('code-example').then(() => {
         Promise.all([...document.querySelectorAll('code-example')].map(example => example.updateComplete)).then(() => {
             const appRoot = document.querySelector('#root');
@@ -104,3 +108,14 @@ Pass a `TemplateResult` into the `tooltip()` directive, as follows in order to h
         });
     });
 </script>
+
+### Accessibility
+
+The tooltip directive automatically manages accessibility features:
+
+- Tooltips are associated with their trigger elements via `aria-describedby`
+- Content is only rendered when needed, reducing DOM complexity
+- Hover and focus interactions are handled automatically
+- Keyboard navigation support is built-in
+
+For more information on accessibility, see the [Accessibility](https://opensource.adobe.com/spectrum-web-components/components/tooltip/#accessibility) section of the tooltip component.