Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update tooltip docs to add note about disabled #2084

Merged
merged 3 commits into from
Jun 20, 2023
Merged

Update tooltip docs to add note about disabled #2084

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dfd538d
Tooltip docs
khiga8 Jun 20, 2023
154b2a3
Update tooltip.rb
khiga8 Jun 20, 2023
13b4e6b
Update app/components/primer/alpha/tooltip.rb
khiga8 Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions app/components/primer/alpha/tooltip.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,20 @@ module Alpha
# When using a tooltip, follow the provided guidelines to avoid accessibility issues:
# - 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.
# - `Tooltip` should be rendered through the API of <%= link_to_component(Primer::ButtonComponent)%>, <%= link_to_component(Primer::Beta::Link)%>, or <%= link_to_component(Primer::IconButton)%>. Avoid using `Tooltip` a standalone component unless absolutely necessary (and **only** on interactive elements).
# @accessibility
# - Tooltip text must be brief and concise whether it is a label or a description.
# - Tooltip can only hold string content.
# - **Never set tooltips on static, non-interactive elements** like `span` or `div`. Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only users
# and screen reader users. Use of tooltip through <%= link_to_component(Primer::ButtonComponent) %>, <%= link_to_component(Primer::Beta::Link) %>, or <%= link_to_component(Primer::IconButton) %> will guarantee this.
# - If you must use `Tooltip` as a standalone component, place it adjacent after the trigger element in the DOM. This allows screen reader users to navigate to and copy the tooltip
# - Tooltip text must be brief and concise even when used to display a description.
# - Tooltips can only hold string content.
# - Tooltips are not allowed on `disabled` elements because such elements are not keyboard-accessible. If you must set a tooltip on a disabled element, use `aria-disabled="true"` instead and programmatically disable the element.
# - **Never set tooltips on static, non-interactive elements** like `span` or `div`. Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only
# and screen reader users. Use of tooltips through <%= link_to_component(Primer::Beta::Button) %>, <%= link_to_component(Primer::Beta::Link) %>, or <%= link_to_component(Primer::Beta::IconButton) %> will guarantee this.
# - If you must use `Tooltip` as a standalone component, place it immediately after the trigger element in the DOM. This allows screen reader users to navigate to the tooltip and copy its contents if desired.
# content.
# ### Which type should I set?
# Semantically, a tooltip will either act an accessible name or an accessible description for the element that it is associated with resulting in either a
# `aria-labelledby` or an `aria-describedby` association. The `type` drastically changes semantics and screen reader behavior so follow these guidelines carefully:
# - When there is already a visible label text on the trigger element, the tooltip is likely intended be supplementary, so set `type: :description`.
# The majority of tooltips will fall under this category.
# - When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set `type: :label`.
# `label` type is usually only appropriate for an icon-only control.
#
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that the "Accessibility" section and the "Which type do I set" information is not being rendered on the doc page for tooltip. I'm assuming this is due to the ongoing docs migration work, and we're only allowing top-level text to show up.

I think this information is very important to surface so I opted to remove the headings to ensure it shows up in the doc.

Copy link
Contributor

@camertron camertron Jun 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm that's interesting. I'll look into it. Ideally all markdown under the @accessibility tag should make it to the new docsite.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Happy to add back the headings later!

# Semantically, a tooltip will either act an accessible name or an accessible description for the element that it is associated with resulting in either a
# `aria-labelledby` or an `aria-describedby` association. The `type` drastically changes semantics and screen reader behavior so follow these guidelines carefully:
# - When there is already a visible label text on the trigger element, the tooltip is likely intended be supplementary, so set `type: :description`.
# The majority of tooltips will fall under this category.
# - When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set `type: :label`.
# `label` type is usually only appropriate for an icon-only control.
class Tooltip < Primer::Component
DIRECTION_DEFAULT = :s
DIRECTION_OPTIONS = [DIRECTION_DEFAULT, :n, :e, :w, :ne, :nw, :se, :sw].freeze
Expand Down