Short form items - a few words, no more than X number of characters (TBD), tooltip text should never be longer than one line. If the text is too long, consider revising the text, or using something else (e.g. popover)
Do not put links or other special HTML in tooltips.
Tooltips activate on mouse hover, and on mobile devices, they trigger on touch and stay persistent.
Don't attach tooltips to text-only links. (so we should change our example on the styleguide.) Text links should explain what they're linking to. If you needed a tooltip to explain the link, you should just change the text of the link.
Tooltips should be attached to icon-based links and buttons to explain what the icon means. (Note: tooltips do not take the place of accessibility-oriented labels, so remember to add those anyway) (TBD: tooltips will not be visible on touch devices because clicking the link/button will trigger an action, not just the tooltip.)
For question-mark-in-circle help for labels, headings, etc, use popovers instead of tooltips.
Popovers
For longer form explanatory content, may contain its own links.
Use this for question-mark-in-circle help icons.
Do not put any critical-path user actions in popovers.
Placement: Always use "auto" as the first value so that Bootstrap can dynamically reorient the tooltip in case it doesn't fit.
Prefer "top" or "bottom" placement because "left" or "right" placements can cause tooltips/popovers to extend out of their columns.
Example: placement="auto top"
Always test your tooltips to make sure they don't obscure important actions when triggered accidentally, and adjust placement rules if necessary.
Specific Uses
If a form is missing information (invalid inputs) and someone clicks on a submit button (which may be disabled) a popover may display above the button to remind the user that they are missing form inputs.
Popover is used for the API key swap interaction (this may also contain a button for further API key interaction)
When a bit of text is copied via a button interaction, a tooltip can appear to let the user know it has been successfully copied to the clipboard.
Action items
[ ] Definitely update the styleguide to reflect these rules as examples
[ ] Add question-mark-in-circle popover from Mobility Explorer to styleguide (for use with admin dashboards)
[ ] Convert the "Copied!" tooltip on user dashboard to this tooltip
related to #496.
cc @souperneon