Tooltips / Popovers: Document usage / purpose on Mapzen sites

[louh]

related to #496.

cc @souperneon

[louh]

Tooltips

• 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.
• Prefer dismissible popovers - which requires some specific syntax.

Both

• 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