@adobe/spectrum-design-data 3.3.0-beta.1 → 3.3.0

package/components/toast.json

@@ -16,100 +16,121 @@
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the text is too long for the available horizontal space, it wraps to form another line. In actionable toasts, the button moves below the text prior to text wrapping."
+      "content": "Toasts display brief, temporary notifications. They appear briefly without blocking interaction and typically do not require user action."
     },
     {
       "type": "guideline",
-      "content": "Multiple toasts.\n\nThe default state can display up to three toasts at a time. To view additional toasts beyond this limit, users can click the \"Show all\" action button. Alternatively, they can reveal remaining toasts by interacting with a button or dismissing the component. Additionally, hovering over the upper part of the toasts triggers a subtle animation, signaling to the user that the group can be fully expanded. The expanded state displays a minimum of two toasts with a visible scroll indicator, while the maximum number adapts based on screen size. Users can either dismiss the toasts or collapse them back to the previous state. To enhance contrast, an overlay is applied beneath the group, similar to components like takeover dialogs. In the React Spectrum implementation, the action button group has a fixed light theme, as switching modes significantly reduces contrast. Please refer to more multiple toasts usage guideline below."
+      "content": "Toasts must include text to communicate a message. Write the text as concisely as possible while still being clear about what has happened or is happening."
     },
     {
       "type": "guideline",
-      "content": "Toast or dialog?\n\nToasts should only be used for confirmations, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience. Dialogs are ideal for when a situation requires a user's attention, either for displaying important information or prompting for a response."
+      "content": "The neutral toast is the default variant. It is gray and does not have an icon. This is used when the message is neutral in tone or when its semantics do not fit in any of the other variants."
     },
     {
       "type": "guideline",
-      "content": "Placement.\n\nBy default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience. For desktop applications, a toast should be placed 16 px away from the bottom of the viewport. If a toast isn't noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center."
+      "content": "The informative toast uses the informative semantic color (blue) and has an info icon to help those with color vision deficiency discern the message tone. This should be used when the message should call extra attention compared to the neutral variant."
     },
     {
-      "type": "do-dont",
-      "content": "Don't display more than one action",
-      "dont": "Actionable toasts should only have one button."
+      "type": "guideline",
+      "content": "The positive toast uses the positive semantic color (green) and has a checkmark icon to help those with color vision deficiency discern the message tone. This is used to inform about a successful action or completion of a task."
+    },
+    {
+      "type": "guideline",
+      "content": "The negative toast uses the negative semantic color (red) and has an alert icon to help those with color vision deficiency to discern the message tone. This is used to show an error or failure."
     },
     {
-      "type": "do-dont",
-      "content": "Don't include a redundant action",
-      "dont": "Actionable toasts should not have a button with a redundant action. For example, including a \"Dismiss\" button would be redundant because all toasts already have a close button."
+      "type": "guideline",
+      "content": "By default, a toast will dismiss when the user clicks the close button. A toast also has the option to auto-dismiss. Be sure to set a minimum of 5 seconds so that users can have time to read the toast message. If an actionable toast is set to auto-dismiss, make sure that the action is still available elsewhere in the app."
     },
     {
       "type": "guideline",
-      "content": "Multiple toasts.\n\nToasts are designed for brief, non-intrusive, and temporary notifications. While displaying multiple toasts is available via the React Spectrum implementation, we still discourage triggering multiple toasts simultaneously when possible, as this can be very distracting to the user. Frequent interruptions interfere with usability, especially for people with visual and cognitive disabilities (see WCAG Success Criterion 2.2.4 Interruptions ). Products should allow for users to be able turn off all types of alerts. Doing this helps people who want to focus and minimize information that they may find non-essential."
+      "content": "When the text is too long for the available horizontal space, it wraps to form another line. In actionable toasts, the button moves below the text prior to text wrapping."
     },
     {
       "type": "guideline",
-      "content": "Confirmation.\n\nFor a confirmation message ( neutral and positive variants), use a short past participle verb phrase: (optional) noun + verb ending in -ed + (optional) prepositional phrase with more information. If you refer to an interface element directly, put its name in bold text."
+      "content": "The default state can display up to three toasts at a time. To view additional toasts beyond this limit, users can click the “Show all” action button. Alternatively, they can reveal remaining toasts by interacting with a button or dismissing the component. Additionally, hovering over the upper part of the toasts triggers a subtle animation, signaling to the user that the group can be fully expanded."
     },
     {
       "type": "guideline",
-      "content": "Informational.\n\nFor an informational message ( informative variant ), write in a complete sentence following the formula of subject + verb phrase + optional additional information."
+      "content": "Please refer to more multiple toasts usage guideline below."
     },
     {
       "type": "guideline",
-      "content": "Error.\n\nFor an error message ( negative variant), use a short phrase — it can be a complete sentence or not — to describe what's happening as succinctly as possible. Whenever possible, include an in-line action for a user to take so that they can readily address the issue explained in the message."
+      "content": "Toasts should only be used for confirmations, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience."
     },
     {
       "type": "guideline",
-      "content": "Write in sentence case with no period.\n\nLike all in-product content at Adobe, toasts and their actions are written in sentence case. If the toast's message is a single sentence, do not add a period to the end; this helps keep the text quicker to read and easier to parse. Toasts should ideally only be a single sentence, but if you need to use two or more sentences to most accurately communicate the information, add a period to the end of each sentence."
+      "content": "Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response."
     },
     {
       "type": "guideline",
-      "content": "Use an instructive tone.\n\nToasts offer quick reference or context, so a user should be able to quickly read a message that's brief and optimized for delivery. Use an instructive tone that presents the message in a concise and neutral way. Because users are likely to see several toasts in quick succession, it's not appropriate to use overly playful, encouraging, or celebratory language. Just convey the message, then get out of the way so that they can get back to the task at hand. Toasts are not appropriate for promotional messaging or upsells that show the benefit of doing or trying something."
+      "content": "By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience."
     },
     {
       "type": "guideline",
-      "content": "Use generic language.\n\nWhenever possible, use generic language in confirmation and error messages. This approach allows for better localization and it also reduces the need to write many different versions of toasts for similar use cases. It's usually unnecessary to include specific filenames, usernames, or folders because a user can get that context from elsewhere in the UI."
+      "content": "For desktop applications, a toast should be placed 16 px away from the bottom of the viewport."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the toast is mirrored. The icon is right-aligned and the close button is left-aligned. If the toast is actionable, the button placement is also inverted and appears on the left side."
+      "content": "If a toast isn’t noticeable or disrupts the user experience, its placement can be changed to bottom end, top end, or top center."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabPlaces the focus on the next interactive element, which is either a button or a close button.Shift + TabPlaces the focus on the previous interactive element, which is either a button or a close button.Space or EnterIf focus is on the close button, dismisses the toast. If focus is on the button, executes the button action.EscDismisses the toast. This is equivalent to selecting the close button."
+      "content": "Actionable toasts should only have one button."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow)Use the default cursor for non-interactive areas on the toast.PointerUse the pointer cursor for interactive areas on the toast such as the close button."
+      "content": "Actionable toasts should not have a button with a redundant action. For example, including a “Dismiss” button would be redundant because all toasts already have a close button."
     },
     {
       "type": "guideline",
-      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in toasts—must provide a text alternative that communicates the control’s purpose. All controls, especially icon‑only controls, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAToasts should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in toasts. Toasts use color to reinforce their meaning, but every toast also includes a clear text description that communicates purpose.Text contrast minimums 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size.Text spacing1.4.12AALine height of text is at least 1.5x the font size in wrapped tooltips. 2. Operable RequirementCriterionLevel Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Timing adjustable 2.2.1 AToasts should not auto-dismiss. If they do, users need a way to extend, pause, or dismiss time-limited content. Hovering, clicking, or keyboard focusing on the toast should keep it from disappearing.Seizures and physical feactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
+      "content": "Products should allow for users to be able turn off all types of alerts. Doing this helps people who want to focus and minimize information that they may find non-essential."
     }
   ],
   "options": {
-    "text": { "type": "string" },
+    "text": {
+      "type": "string"
+    },
     "variant": {
       "type": "string",
       "default": "neutral",
       "values": [
-        { "value": "neutral" },
-        { "value": "informative" },
-        { "value": "positive" },
-        { "value": "negative" }
+        {
+          "value": "neutral"
+        },
+        {
+          "value": "informative"
+        },
+        {
+          "value": "positive"
+        },
+        {
+          "value": "negative"
+        }
       ]
     },
     "actionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
     },
-    "isAutoDismissible": { "type": "boolean", "default": false }
+    "isAutoDismissible": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "intents": ["dismiss"],
     "focusable": true,
     "keyboardIntents": ["dismiss"],
     "wcag": [
-      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
+      {
+        "criterion": "4.1.3",
+        "level": "AA",
+        "title": "Status Messages"
+      }
     ]
   }
 }

package/components/tooltip.json

@@ -9,6 +9,19 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/tooltip/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Tooltip",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "Tooltip",
+      "importPath": "@adobe/spectrum-wc/components/tooltip",
+      "notes": "Spectrum 2 web component custom element: swc-tooltip."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,64 +29,94 @@
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the label is too long for the available horizontal space, it wraps to form another line."
+      "content": "Tooltips display contextual information related to a specific component. They appear on hover or focus to clarify purpose or behavior."
+    },
+    {
+      "type": "guideline",
+      "content": "All tooltips have a label. The label communicates the contextual help or information about specific components when a user hovers over or focuses on them."
     },
     {
       "type": "guideline",
-      "content": "Animation.\n\nA tooltip fades in and out when showing and hiding, and slides a short distance from the source to indicate its origin. The direction of the slide (left, right, top, bottom) depends on the placement of the tooltip. The animation attributes (duration, easing, offset) are the same whether it's showing or hiding."
+      "content": "By default, tooltips are the neutral variant. These are the most common variant because most tooltips are used to only disclose additional information, without conveying a semantic meaning. The neutral variant never includes an icon."
     },
     {
       "type": "guideline",
-      "content": "Immediate or delayed appearance.\n\nTooltips attached to help icons appear immediately. For conventional UI elements where a tooltip appearing immediately would be intrusive, delay appearance with a warmup period."
+      "content": "Tooltips also come in semantic variants: informative (blue), and negative (red). An icon is required for these variants to ensure information isn’t conveyed by color alone."
     },
     {
       "type": "guideline",
-      "content": "Warmup and cooldown.\n\nThe warmup period is a global timer that requires the cursor to remain on a UI element for the allotted time before a tooltip appears. Once this period is complete, a tooltip appears instantly on any hovered-upon UI element until the cursor is in an area that does not trigger a tooltip for the duration of the cooldown period."
+      "content": "2 of the 3 tooltip variants (informative and negative) can include an icon to supplement the messaging. These icons are predefined and can not be customized. Unless it's being used to provide context about the exact same icon, a semantic tooltip should always show an icon. Doing this is essential for helping users with color vision deficiency to discern the message tone."
     },
     {
       "type": "guideline",
-      "content": "Use tooltips to describe icons.\n\nIcons 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."
+      "content": "A tooltip is positioned in relation to its target."
     },
     {
-      "type": "do-dont",
-      "content": "Don't use tooltips to communicate crucial information",
-      "dont": "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."
+      "type": "guideline",
+      "content": "This option determines whether or not a tooltip should be able to switch sides when constrained by space. A tooltip placed at the top would flip to be placed at the bottom (and vice versa), and a tooltip placed at the left would flip to be placed at the right (and vice versa)."
+    },
+    {
+      "type": "guideline",
+      "content": "The offset is the distance between the end of the tip and the target."
     },
     {
       "type": "guideline",
-      "content": "Be concise.\n\nTooltips should be as concise and clear as possible. Keep the text to 1 or 2 short sentences. If the information you need to communicate is longer than that, look into using a different design. If a tooltip is written in a full sentence (or is 2 or more sentences), include a period at the end. If it's a short phrase or is only the name of a tool, action, or icon, don't add a period to the end."
+      "content": "To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it’s possible to define a container and a container padding value to respect."
     },
     {
-      "type": "do-dont",
-      "content": "Don't place actions inside a tooltip",
-      "dont": "Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links."
+      "type": "guideline",
+      "content": "When the label is too long for the available horizontal space, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "A tooltip fades in and out when showing and hiding, and slides a short distance from the source to indicate its origin. The direction of the slide (left, right, top, bottom) depends on the placement of the tooltip. The animation attributes (duration, easing, offset) are the same whether it’s showing or hiding."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the tooltip is mirrored. The icon is placed on the right side of the text."
+      "content": "Tooltips attached to help icons appear immediately. For conventional UI elements where a tooltip appearing immediately would be intrusive, delay appearance with a warmup period."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabTabbing into an item that has a tooltip associated with it (e.g., an icon) shows the tooltip.EscHides the tooltip."
+      "content": "The warmup period is a global timer that requires the cursor to remain on a UI element for the allotted time before a tooltip appears. Once this period is complete, a tooltip appears instantly on any hovered-upon UI element until the cursor is in an area that does not trigger a tooltip for the duration of the cooldown period."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerIf the trigger is a button or link, or a focus-only element (like an info icon that shows a tooltip on hover), use the pointer cursor.Default (Arrow)If the trigger is an icon that is not clickable, use the default cursor.PointerIf the tooltip has a link, use the pointer cursor when interacting with the link."
+      "content": "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."
     },
     {
       "type": "guideline",
-      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content1.1.1ANon‑text elements—such as icons used in tooltips and icons that trigger tooltips—must provide a text alternative that communicates the control’s purpose. All controls, especially icon‑only controls, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose1.3.1, 1.3.6A, AAATooltips should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role should be utilized.Use of color1.4.1AColor is never used as the sole way to convey meaning in tooltips. Tooltips use color to reinforce their meaning, but every tooltip also includes a clear text label that communicates purpose.Text contrast minimums1.4.3AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Resize text1.4.4AATooltips should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation1.4.8AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast1.4.11AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing1.4.12AALine height of text is at least 1.5x the font size in wrapped tooltips. 2. Operable RequirementCriterionLevel Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
+      "content": "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips should be as concise and clear as possible. Keep the text to 1 or 2 short sentences. If the information you need to communicate is longer than that, look into using a different design."
+    },
+    {
+      "type": "guideline",
+      "content": "If a tooltip is written in a full sentence (or is 2 or more sentences), include a period at the end. If it's a short phrase or is only the name of a tool, action, or icon, don't add a period to the end."
+    },
+    {
+      "type": "guideline",
+      "content": "Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links."
     }
   ],
   "options": {
-    "label": { "type": "string" },
+    "label": {
+      "type": "string"
+    },
     "variant": {
       "type": "string",
       "default": "neutral",
       "values": [
-        { "value": "neutral" },
-        { "value": "informative" },
-        { "value": "negative" }
+        {
+          "value": "neutral"
+        },
+        {
+          "value": "informative"
+        },
+        {
+          "value": "negative"
+        }
       ]
     },
     "hasIcon": {
@@ -90,13 +133,24 @@
       "type": "string",
       "default": "top",
       "values": [
-        { "value": "top" },
-        { "value": "bottom" },
-        { "value": "left" },
-        { "value": "right" }
+        {
+          "value": "top"
+        },
+        {
+          "value": "bottom"
+        },
+        {
+          "value": "left"
+        },
+        {
+          "value": "right"
+        }
       ]
     },
-    "shouldFlip": { "type": "boolean", "default": false },
+    "shouldFlip": {
+      "type": "boolean",
+      "default": false
+    },
     "offset": {
       "type": "number",
       "default": 4,
@@ -108,7 +162,9 @@
       "description": "units: pixels"
     }
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "accessibility": {
     "role": "tooltip",
     "focusable": false,
@@ -118,7 +174,11 @@
         "level": "AA",
         "title": "Content on Hover or Focus"
       },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }