docs(tooltip): updated tooltip docs based on feedback in #972 (#1021)

* docs(tooltip): tooltip docs cleanup

* docs(tooltip): removed unsued images

* docs(tooltip): added feedback to each docs page and usage to code page

* docs(tooltip): edited alt text and removed a11y tab for now

* docs(tooltip): fixed spacing issue

* docs(tooltip): fixed a br that was an hr

* docs(tooltip): added changeset

* docs(tooltip): added sample component

* refactor(tooltip): private css prop name

* feat(tooltip): add conventional css props

* docs(tooltip): css props

* chore: tweak stylelint config

* style: lint css files

* docs(tooltip):Updated .changeset/nasty-flies-flash.md

Co-authored-by: Benny Powers <bennypowers@users.noreply.github.com>

* docs(tooltip): updated tooltip docs and added accessibility page

* docs(tooltip): added kbd markup to accessibility page's keyboard table

* docs(tooltip): fixed linting issue

* docs(tooltip): fixed issue on code page

* docs(tooltip): fixed headings and dark image styles based on PR feedback

* docs(tooltip): fixed column widths on tables

* docs(tooltip): updated spacer to new shortcode

---------

Co-authored-by: Benny Powers <web@bennypowers.com>
Co-authored-by: Benny Powers <bennypowers@users.noreply.github.com>

.changeset/rh-tooltip-deprecate-bem-props.md

@@ -1,5 +1,5 @@
 ---
-"@rhds/elements": minor
+"@patternfly/elements": minor
 ---
 `<rh-tooltip>`: add new CSS custom properties:
     - `--rh-tooltip-arrow-size`

elements/rh-tooltip/docs/00-overview.md

@@ -45,7 +45,7 @@
 ## When to use 
 - When users need help making a decision
 - When you need to provide more information for icons or icon buttons without labels
-- When you need to define new or unfamiliar UI elements - that are not described directly in the user interface
+- When you need to define new or unfamiliar UI elements that are not described directly in the user interface
 
-{% repoStatus %}
+{% repoStatus type="Element" %}
 

elements/rh-tooltip/docs/10-style.md

@@ -2,66 +2,55 @@
 A tooltip is a container with text that includes an arrow and sometimes a drop shadow. It can be anchored to various elements like buttons, icons, etc.
 ### Anatomy 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Anatomy of a tooltip with annotations; number 1 is pointing to the container, number 2 is pointing to the text, number 3 is pointing to the arrow, and number 4 is pointing to the trigger",
           src="../tooltip-anatomy.png" %}
 
 1) Container
 2) Text
 3) Arrow
 4) Trigger
+{.example-notes}
+
 ## Theme 
 A tooltip is available in both light and dark themes. The dark theme tooltip container does not include a drop shadow.
 ### Light theme 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Light theme tooltip which is black",
           src="../tooltip-theme-light.png" %}
 
-
 ### Dark theme 
-{% example palette="dark",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
+{% example palette="darkest",
           alt="Dark theme tooltip which is white",
           src="../tooltip-theme-dark.png" %}
 
-
 ## Configuration 
 All badges have the same height and border radius.
 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="How a tooltip is constructed showing alignment, border radius, and arrow details",
           src="../tooltip-configuration.png" %}
 
-
 ## Space 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Tooltip spacing both within the element and in between the element and trigger",
           src="../tooltip-space.png" %}
 
-<br>
-
-| Spacer | Current value |
-| ------ | ------------- |
-| ![8px spacer]({{ '../tooltip-8px-spacer.png' | url }}) | 8px 0.5rem |
-| ![16px spacer]({{ '../tooltip-16px-spacer.png' | url }}) | 16px 1.0rem |
+{% spacerTokensTable 
+  headline="",
+  caption='',
+  headingLevel="4",
+  tokens="--rh-space-md, --rh-space-lg" %}
+{% endspacerTokensTable %}
 
 ## Animation 
-A tooltip has a <code>300ms</code> entry delay on hover by default, but this can be customized. For example, if you would like it to appear immediately, set the delay to <code>0ms</code>.
+A tooltip has a `300ms` entry delay on hover by default, but this can be customized. For example, if you would like it to appear immediately, set the delay to `0ms`.
 ## Interaction states 
 A tooltip appears near an icon or element on hover, focus, or when tapped. A tooltip contains only text and is not interactive.
 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Tooltip trigger interaction states",
           src="../tooltip-interaction-states.png" %}
 
-{% include 'feedback.html' %}
+[6px]: {{ '../tooltip-6px-spacer.png' | url }}
+[8px]: {{ '../tooltip-8px-spacer.png' | url }}
+[16px]: {{ '../tooltip-16px-spacer.png' | url }}

elements/rh-tooltip/docs/20-guidelines.md

@@ -1,6 +1,6 @@
 ## Usage 
 Use a tooltip as a way for users to see more information before they select an element, go to a new page, or trigger an action on the page.
-## Tooltip vs. popover 
+### Tooltip vs. popover 
 A tooltip and [Popover](/elements/popover) provide more information in context for users. However, they are different in the following ways.
 
 - A tooltip is used for simple communication purposes while a popover is more descriptive
@@ -10,8 +10,6 @@ A tooltip and [Popover](/elements/popover) provide more information in context f
 Content in a tooltip is limited to text only. Consider the following when writing tooltip content.
 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Various text examples; from left to right, the text length starts very short, but gets longer and longer",
           src="../tooltip-content.png" %}
 
@@ -20,8 +18,6 @@ Content in a tooltip is limited to text only. Consider the following when writin
 The correct orientation of a tooltip depends on the amount of content and browser window. If a tooltip covers up important information or gets cut off, choose a different orientation.
 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Various orientation examples; from left to right and top to bottom, top, right, bottom, and left",
           src="../tooltip-orientation.png" %}
 
@@ -30,24 +26,22 @@ The correct orientation of a tooltip depends on the amount of content and browse
 When a cursor or focus is moved, the tooltip disappears. On mobile devices, users must tap to trigger a tooltip and then tap again to make it disappear.
 
 {% example palette="light",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Various behavior examples; from top to bottom, how a tooltip behaves when the trigger is hovered, focused, and tapped",
           src="../tooltip-behavior.png" %}
 
 
 ## Responsive design 
 A tooltip can generally be used on both large and small breakpoints if the content is not too long.
 
-![Examples of a tooltip used on large and small breakpoints]({{ '../tooltip-responsive-design.png' | url }})
+{% example palette="none",
+          alt="Examples of a tooltip used on large and small breakpoints",
+          src="../tooltip-responsive-design.png" %}
 
 ## Best practices 
 ### White on white 
 Do not use a dark theme tooltip in light theme environments.
 
 {% example palette="wrong",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="A dark theme or white tooltip used on a white background is incorrect usage",
           src="../tooltip-best-practice-1.png" %}
 
@@ -56,8 +50,6 @@ Do not use a dark theme tooltip in light theme environments.
 A tooltip should not be cut off by the browser window. Change the orientation if it does.
 
 {% example palette="wrong",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="If using the top orientation will cause the tooltip to get cut off, that is incorrect usage",
           src="../tooltip-best-practice-2.png" %}
 
@@ -66,9 +58,5 @@ A tooltip should not be cut off by the browser window. Change the orientation if
 Do not add a tooltip to interface elements or actions that do not require further explanation.
 
 {% example palette="wrong",
-          class="inline-flex centered",
-          style="margin-block:var(--rh-space-2xl);",
           alt="Pairing a tooltip with an element that already has adequate descriptive text is incorrect usage",
           src="../tooltip-best-practice-3.png" %}
-
-{% include 'feedback.html' %}

elements/rh-tooltip/docs/30-code.md

@@ -1,18 +1,11 @@
 {% renderInstallation %}{% endrenderInstallation %}
 
-{% band header="Usage" %}
-```html
-<rh-tooltip>
-    <div>
-        This is An Element 
-    </div>
-    <div slot="content">
-
-        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Mi eget mauris pharetra et ultrices.
-    </div>
-</rh-tooltip>
-```
-{% endband %}
+{% section headline="Usage" %}
+  {% playground tagName=button %}{% endplayground %}
+  {% cta href="./demo/", target="_blank" %}
+View the demo in a new tab
+  {% endcta %}
+{% endsection %}
 
 {% renderSlots %}{% endrenderSlots %}
 

elements/rh-tooltip/docs/40-accessibility.md

@@ -0,0 +1,27 @@
+## Keyboard interactions
+A tooltip will appear when the trigger receives focus and disappear when moving focus away from the trigger.
+
+{% example palette="light",
+          alt="Tooltip keyboard interactions; pressing tab to focus the trigger will show the tooltip, but pressing tab again will hide the tooltip",
+          src="../tooltip-keyboard-interactions.png" %}
+
+
+| Key {style="width: 50%" } | Result                                                       |
+| ------------------------- | ------------------------------------------------------------ |
+| <kbd>Tab</kbd>            | Moves focus to the trigger, tooltip appear                   |
+| <kbd>Tab</kbd>            | Moves focus away from the trigger, tooltip disappears        |
+| <kbd>Esc</kbd>            | Removes a tooltip without moving focus away from the trigger |
+
+## Additional guidelines
+ - Do not use a tooltip on static elements
+ - A tooltip should persist while hovering over the trigger and tooltip
+ - A tooltip should persist as long as the trigger has focus
+ - Users navigating via screen reader must have tooltip text announced to them when it is triggered
+ - If a tooltip is added to a disabled trigger, that trigger must be able to receive focus
+
+{% include 'accessibility/ariaguide.md' %}
+{% include 'accessibility/wcag.md' %}
+{% include 'accessibility/2.1.1-A.md' %}
+{% include 'accessibility/2.1.3-AAA.md' %}
+{% include 'accessibility/2.4.3-A.md' %}
+{% include 'accessibility/2.5.5-AAA.md' %}

elements/rh-tooltip/rh-tooltip.ts

@@ -12,8 +12,9 @@ import { BaseTooltip } from '@patternfly/elements/pf-tooltip/BaseTooltip.js';
 import styles from './rh-tooltip.css';
 
 /**
- * Tooltip
- * @summary A tooltip is a floating text area that provides helpful or contextual information on hover, focus, or tap.
+ * A tooltip is a floating text area that provides helpful or contextual information on hover, focus, or tap.
+ * @summary Reveals a small area of information on hover
+ *
  * @slot - Place element content here
  *
  * @cssprop --rh-box-shadow-sm