@adobe/spectrum-design-data 3.3.0 → 3.5.0

package/components/toast.json

@@ -16,121 +16,104 @@
     },
     {
       "type": "guideline",
-      "content": "Toasts display brief, temporary notifications. They appear briefly without blocking interaction and typically do not require user action."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
-      "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": "do-dont",
+      "content": "Don't display more than one action",
+      "dont": "Actionable toasts should only have one button."
     },
     {
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "Writing for toasts depends on the nature of the message, whether it's communicating confirmation, information, or an error. For all kinds of toasts, keep the text to fewer than 2 lines in English, since it will become longer when localized."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "Please refer to more multiple toasts usage guideline below."
+      "content": "Informational.\n\nFor an informational message (informative variant), write in a complete sentence following the formula of subject + verb phrase + optional additional information."
     },
     {
       "type": "guideline",
-      "content": "Toasts should only be used for confirmations, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "Dialogs are ideal for when a situation requires a user’s attention, either for displaying important information or prompting for a response."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "By default, a toast is placed at the bottom center for both desktop and mobile platform scales to avoid disrupting the user experience."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "For desktop applications, a toast should be placed 16 px away from the bottom of the viewport."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "Actionable toasts should only have one button."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Places the focus on the next interactive element, which is either a button or a close button. Shift + Tab Places the focus on the previous interactive element, which is either a button or a close button. Space or Enter If focus is on the close button, dismisses the toast. If focus is on the button, executes the button action. Esc Dismisses the toast. This is equivalent to selecting the close button."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow) Use the default cursor for non-interactive areas on the toast. Pointer Use the pointer cursor for interactive areas on the toast such as the close button."
     },
     {
       "type": "guideline",
-      "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."
+      "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 A Non‑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, AAA Toasts 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 A Color 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 AA Large 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 AAA The 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 AA The visual presentation of icons have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line height of text is at least 1.5x the font size. Text spacing 1.4.12 AA Line height of text is at least 1.5x the font size in wrapped tooltips. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus can be moved away from the component using only a keyboard. Timing adjustable 2.2.1 A Toasts 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
     }
   ],
   "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
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "isAutoDismissible": { "type": "boolean", "default": false }
   },
+  "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,19 +9,6 @@
     "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",
@@ -29,94 +16,77 @@
     },
     {
       "type": "guideline",
-      "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": "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": "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": "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."
+      "content": "Text overflow.\n\nWhen the label is too long for the available horizontal space, it wraps to form another line."
     },
     {
       "type": "guideline",
-      "content": "A tooltip is positioned in relation to its target."
+      "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."
     },
     {
       "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)."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "The offset is the distance between the end of the tip and the target."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
-      "type": "guideline",
-      "content": "When the label is too long for the available horizontal space, it wraps to form another line."
+      "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": "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."
+      "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."
     },
     {
-      "type": "guideline",
-      "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": "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": "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Tabbing into an item that has a tooltip associated with it (e.g., an icon) shows the tooltip. Esc Hides the tooltip."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "Cursor guidelines.\n\nCursor Usage Pointer If 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. Pointer If the tooltip has a link, use the pointer cursor when interacting with the link."
     },
     {
       "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."
-    },
+      "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 A Non‑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 purpose 1.3.1, 1.3.6 A, AAA Tooltips should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role should be utilized. Use of color 1.4.1 A Color 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 minimums 1.4.3 AA Large 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 text 1.4.4 AA Tooltips should be built in such a way that they can be resized without assistive technology up to 200%. Visual presentation 1.4.8 AAA The 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 AA The visual presentation of icons and various states have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line height of text is at least 1.5x the font size in wrapped tooltips. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
+    }
+  ],
+  "implementations": [
     {
-      "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."
+      "platform": "web",
+      "componentName": "Tooltip",
+      "package": "@react-spectrum/s2"
     },
     {
-      "type": "guideline",
-      "content": "Tooltips appear only on hover or when in keyboard focus. They should not contain actions or links."
+      "platform": "web",
+      "componentName": "Tooltip",
+      "importPath": "@adobe/spectrum-wc/components/tooltip",
+      "notes": "Spectrum 2 web component custom element: swc-tooltip."
     }
   ],
   "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": {
@@ -133,24 +103,13 @@
       "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,
@@ -162,9 +121,7 @@
       "description": "units: pixels"
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "tooltip",
     "focusable": false,
@@ -174,11 +131,7 @@
         "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" }
     ]
   }
 }