@adobe/spectrum-design-data 3.3.0 → 3.4.0

package/components/alert-banner.json

@@ -96,35 +96,22 @@
     }
   ],
   "options": {
-    "text": {
-      "type": "string"
-    },
+    "text": { "type": "string" },
     "variant": {
       "type": "string",
       "default": "neutral",
       "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "informative"
-        },
-        {
-          "value": "negative"
-        },
-        {
-          "value": "accent"
-        }
+        { "value": "neutral" },
+        { "value": "informative" },
+        { "value": "negative" },
+        { "value": "accent" }
       ]
     },
     "actionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
     },
-    "isDismissible": {
-      "type": "boolean",
-      "default": false
-    }
+    "isDismissible": { "type": "boolean", "default": false }
   },
   "anatomy": [
     {
@@ -132,17 +119,11 @@
       "description": "Icon indicating the alert's severity."
     }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "focusable": false,
     "wcag": [
-      {
-        "criterion": "4.1.3",
-        "level": "AA",
-        "title": "Status Messages"
-      }
+      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
     ]
   }
 }

package/components/alert-dialog.json

@@ -9,13 +9,6 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/alert-dialog/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "AlertDialog",
-      "package": "@react-spectrum/s2"
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -23,80 +16,87 @@
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs present critical information that must be acknowledged. They appear over the interface and block further interaction until an action is selected."
+      "content": "Text overflow.\n\nWhen the title and description text are too long for the available horizontal space, they wrap to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "Button group overflow.\n\nAlert dialogs can include up to three buttons. When horizontal space is limited, the buttons stack vertically. Buttons should be ordered by ascending importance, with the most critical action placed at the end or bottom of the stack."
+    },
+    {
+      "type": "guideline",
+      "content": "Use alert dialogs sparingly.\n\nAlert dialogs are interruptive, so they should be reserved for important information that users must acknowledge before continuing a task or workflow. Use them only when absolutely necessary—not for low-priority notifications or excessive confirmations."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t nest alert dialogs.\n\nAlert dialogs are designed to pause the experience until a decision is made, so only one should appear at a time. Avoid opening an alert dialog from within another. If a situation seems to require a sequence of decisions, consider using a different design pattern."
+    },
+    {
+      "type": "guideline",
+      "content": "Writing for alert dialogs starts by determining the nature of the message. Each Spectrum alert dialog variant has its own communication goal and tone that work in partnership with its visual design. Alert dialog variant Goal Tone Confirmation Asking a user to confirm an action they want to take. Instructive Information Sharing important information that a user needs to acknowledge. Helpful Warning Sharing time-sensitive information that a user needs to consider, but won’t block them from proceeding. Instructive to helpful Destructive Telling a user that if they are to proceed with an action they want to take, it may impact their data in a negative way. Instructive Error Communicating critical information about an issue that a user needs to resolve before they can move forward with a task. Supportive"
     },
     {
       "type": "guideline",
-      "content": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
+      "content": "Writing the title.\n\nAll alert dialogs must have a title. The title communicates the upshot of the message, such as the eventual outcome or conclusion of an action. It should be as close as possible to a complete sentence (subject + verb). Don’t use punctuation at the end of the title. Most alert dialog titles communicate the main effect of whatever a person is about to do. Titles ideally use the same or similar phrasing as the call-to-action that had led someone to the alert dialog in the first place. The title of an error alert dialog communicates the result of the error. Don’t just state that an error has occurred."
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs can include up to three buttons if a secondary outline button label is defined. If no label is defined, the button won’t appear. The secondary outline button should use a short, actionable phrase that clearly communicates the result of selecting the action—typically describing the previous step or an alternative choice."
+      "content": "Writing the description.\n\nAlert dialog descriptions share any additional information or context that a person needs to know in order to make one of the decisions offered by the actions. Descriptions are written in complete sentences, and any error code is included in parentheses at the end of the last sentence."
     },
     {
       "type": "guideline",
-      "content": "An alert dialog must include at least one button. The primary action label refers to the rightmost button in the dialog footer for languages that read left to right. It should use a short, actionable phrase that clearly communicates the result of selecting the action—whether that means moving forward or dismissing the dialog."
+      "content": "Writing the actions.\n\nUse a short phrase to succinctly describe the options for next steps. If possible, have the button label use the same language as the action mentioned in the alert dialog title (e.g., if a dialog's title is “Delete conversation,” its primary action button label would be “Delete”)."
     },
     {
       "type": "guideline",
-      "content": "Use the appropriate variant based on the context of the message:"
+      "content": "Make button labels specific and actionable.\n\nFor alert dialog buttons, make the labels as specific and actionable as possible. Even if someone were to only read the word or phrase on the button, they should be able to get a summary of the alert dialog’s entire message."
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs should include a description when available. The description briefly communicates any additional information or context a user needs to make a decision based on the options presented."
+      "content": "Avoid asking questions.\n\nQuestions in alert dialog titles — such as “Are you sure you want to quit?” or “Do you want to cancel?” — are redundant and undermine a user's agency in the decision they've already made by taking a previous action to get to the alert dialog. This phrasing also sets up for a yes/no set of actions, which can become confusing. Instead, reframe the message to focus on the outcome or effect."
     },
     {
       "type": "guideline",
-      "content": "All alert dialogs must have a title. The title appears at the top of the dialog and uses a few words to convey the outcome of what will happen if a user continues with the primary action."
+      "content": "Pair confirmation with distinct actions.\n\nIt’s OK to ask a question in an alert dialog's description to confirm if someone wants to go ahead with a choice that the system is making on their behalf. However, this should still be paired with distinct actions that show that a person has control over what happens next."
     },
     {
       "type": "guideline",
-      "content": "When the title and description text are too long for the available horizontal space, they wrap to form another line."
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the alert dialog is mirrored. Texts are right-aligned and buttons are left-aligned."
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs can include up to three buttons. When horizontal space is limited, the buttons stack vertically. Buttons should be ordered by ascending importance, with the most critical action placed at the end or bottom of the stack."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Moves focus to the next button inside the alert dialog (last becomes first). If none of the buttons are selected, the focus is set on the first button. Shift + Tab Moves focus to the previous button inside the alert dialog (first becomes last). If none of the buttons are selected, the focus is set on the last button. Esc Dismisses the alert dialog. This is equivalent to choosing “Cancel” or an “OK” confirmation. Esc Dismisses the alert banner if possible. This is equivalent to selecting the close button."
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs are interruptive, so they should be reserved for important information that users must acknowledge before continuing a task or workflow. Use them only when absolutely necessary—not for low-priority notifications or excessive confirmations."
+      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow) Use the default cursor for non-interactive elements and text within the alert dialog. Pointer Use the pointer cursor for any interactive elements, such as buttons, inside the alert dialog."
     },
     {
       "type": "guideline",
-      "content": "Alert dialogs are designed to pause the experience until a decision is made, so only one should appear at a time. Avoid opening an alert dialog from within another. If a situation seems to require a sequence of decisions, consider using a different design pattern."
+      "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 alert dialogs, must provide a text alternative that communicates the dialog's purpose. All alert dialogs 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 Alert dialogs should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of alertdialog should be utilized. Use of color 1.4.1 A Color is not used as a means to convey information or distinguish elements. Contrast 1.4.3 AA The visual presentation of text has a contrast ratio of at least 4.5:1. 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 illustrations and component 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. 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": [
+    {
+      "platform": "web",
+      "componentName": "AlertDialog",
+      "package": "@react-spectrum/s2"
     }
   ],
   "options": {
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
-    },
+    "title": { "type": "string" },
+    "description": { "type": "string" },
     "variant": {
       "type": "string",
       "default": "confirmation",
       "values": [
-        {
-          "value": "confirmation"
-        },
-        {
-          "value": "information"
-        },
-        {
-          "value": "warning"
-        },
-        {
-          "value": "destructive"
-        },
-        {
-          "value": "error"
-        }
+        { "value": "confirmation" },
+        { "value": "information" },
+        { "value": "warning" },
+        { "value": "destructive" },
+        { "value": "error" }
       ]
     },
-    "primaryActionLabel": {
-      "type": "string"
-    },
+    "primaryActionLabel": { "type": "string" },
     "secondaryActionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
@@ -107,25 +107,15 @@
       "description": "If undefined, this button does not appear."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "dialog",
     "intents": ["dismiss"],
     "focusable": false,
     "keyboardIntents": ["dismiss"],
     "wcag": [
-      {
-        "criterion": "2.4.3",
-        "level": "A",
-        "title": "Focus Order"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "2.4.3", "level": "A", "title": "Focus Order" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }

package/components/avatar-group.json

@@ -9,13 +9,6 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/avatar-group/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "AvatarGroup",
-      "package": "@react-spectrum/s2"
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -23,27 +16,23 @@
     },
     {
       "type": "guideline",
-      "content": "An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities."
-    },
-    {
-      "type": "guideline",
-      "content": "Avatar sizes scale exponentially, based on the Spectrum type scale. Avatar has preset sizes to flex across all surfaces and can also be customized to fit appropriately for your context."
+      "content": "Keyboard focus.\n\nIndividual avatars inside Avatar group can be navigated using a keyboard. The keyboard focus state adds a focus ring around the avatar."
     },
     {
       "type": "guideline",
-      "content": "An Avatar group can have an optional text label that clearly describes the group or number of users that it represents."
+      "content": "Adjusting stroke color to match neutral backgrounds.\n\nEach individual avatar has a stroke applied to better show distinction between individual users in the group. By default, the outline color is a neutral gray, but the stroke color should be adjusted manually to match the background where the avatar group is placed."
     },
     {
-      "type": "guideline",
-      "content": "Individual avatars inside Avatar group can be navigated using a keyboard. The keyboard focus state adds a focus ring around the avatar."
-    },
-    {
-      "type": "guideline",
-      "content": "Each individual avatar has a stroke applied to better show distinction between individual users in the group. By default, the outline color is a neutral gray, but the stroke color should be adjusted manually to match the background where the avatar group is placed."
-    },
+      "type": "do-dont",
+      "content": "Do not adjust stroke color on a colored background",
+      "dont": "When using a colored background the avatar stroke color should remain set as default for both light and dark themes."
+    }
+  ],
+  "implementations": [
     {
-      "type": "guideline",
-      "content": "When using a colored background the avatar stroke color should remain set as default for both light and dark themes."
+      "platform": "web",
+      "componentName": "AvatarGroup",
+      "package": "@react-spectrum/s2"
     }
   ],
   "options": {
@@ -55,35 +44,16 @@
       "type": "number",
       "default": 100,
       "values": [
-        {
-          "value": 50
-        },
-        {
-          "value": 75
-        },
-        {
-          "value": 100
-        },
-        {
-          "value": 200
-        },
-        {
-          "value": 300
-        },
-        {
-          "value": 400
-        },
-        {
-          "value": 500
-        }
+        { "value": 50 },
+        { "value": 75 },
+        { "value": 100 },
+        { "value": 200 },
+        { "value": 300 },
+        { "value": 400 },
+        { "value": 500 }
       ]
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "role": "group",
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "role": "group", "focusable": false }
 }

package/components/avatar.json

@@ -9,19 +9,6 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/avatar/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "Avatar",
-      "package": "@react-spectrum/s2"
-    },
-    {
-      "platform": "web",
-      "componentName": "Avatar",
-      "importPath": "@adobe/spectrum-wc/components/avatar",
-      "notes": "Spectrum 2 web component custom element: swc-avatar."
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -29,39 +16,36 @@
     },
     {
       "type": "guideline",
-      "content": "An avatar in a disabled state shows that an avatar exists, but is not available or a user is not active in that circumstance. This can be used to maintain layout continuity and communicate that an avatar may become available or active later."
-    },
-    {
-      "type": "guideline",
-      "content": "When used as an individual Avatar, showStroke is false by default. When used in Avatar group, showStroke is true by default to create separation between the stacked group of Avatar components."
+      "content": "Keyboard focus.\n\nAn avatar can be navigated using a keyboard. The keyboard focus state adds a blue ring to the avatar in focus."
     },
     {
       "type": "guideline",
-      "content": "Avatar sizes scale exponentially, based on the Spectrum type scale. Avatar has preset sizes to flex across all surfaces and can also be customized to fit appropriately for your context."
+      "content": "Multiple avatars in a group.\n\nAn avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities."
     },
     {
       "type": "guideline",
-      "content": "An avatar has multiple visual styles, depending on the user preference. These show up as branded gradient images, initials of the user’s name, as well as any image that a user uploads. For users who do not have Adobe accounts, they will default to the guest avatar."
+      "content": "Use gradient image avatars when a user image is undefined.\n\nUse branded generic avatars when a user has not set their avatar image. These images are designed to be abstracted from all genders, locales, and cultures."
     },
     {
       "type": "guideline",
-      "content": "An avatar can be navigated using a keyboard. The keyboard focus state adds a blue ring to the avatar in focus."
+      "content": "Use the initials avatar style for users with latin characters only.\n\nThe initials avatar is designed to work with latin characters only and supports 1 or 2 characters that are programmatically identified by the first name and last name in a user's account settings. For users with non-latin characters, their default avatar should be the gradient image style."
     },
     {
       "type": "guideline",
-      "content": "An avatar group displays a set of related avatars together. It’s typically used to represent a collection of people or entities."
-    },
-    {
-      "type": "guideline",
-      "content": "Use branded generic avatars when a user has not set their avatar image. These images are designed to be abstracted from all genders, locales, and cultures."
-    },
+      "content": "Use the guest avatar style for users without an Adobe account.\n\nThe guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account."
+    }
+  ],
+  "implementations": [
     {
-      "type": "guideline",
-      "content": "The initials avatar is designed to work with latin characters only and supports 1 or 2 characters that are programmatically identified by the first name and last name in a user’s account settings. For users with non-latin characters, their default avatar should be the gradient image style."
+      "platform": "web",
+      "componentName": "Avatar",
+      "package": "@react-spectrum/s2"
     },
     {
-      "type": "guideline",
-      "content": "The guest avatar style is designed for users who may be interacting with Adobe products, but are not logged in or do not have an Adobe account."
+      "platform": "web",
+      "componentName": "Avatar",
+      "importPath": "@adobe/spectrum-wc/components/avatar",
+      "notes": "Spectrum 2 web component custom element: swc-avatar."
     }
   ],
   "options": {
@@ -69,107 +53,44 @@
       "type": "number",
       "default": 500,
       "values": [
-        {
-          "value": 50
-        },
-        {
-          "value": 75
-        },
-        {
-          "value": 100
-        },
-        {
-          "value": 200
-        },
-        {
-          "value": 300
-        },
-        {
-          "value": 400
-        },
-        {
-          "value": 500
-        },
-        {
-          "value": 600
-        },
-        {
-          "value": 700
-        },
-        {
-          "value": 800
-        },
-        {
-          "value": 900
-        },
-        {
-          "value": 1000
-        },
-        {
-          "value": 1100
-        },
-        {
-          "value": 1200
-        },
-        {
-          "value": 1300
-        },
-        {
-          "value": 1400
-        },
-        {
-          "value": 1500
-        }
+        { "value": 50 },
+        { "value": 75 },
+        { "value": 100 },
+        { "value": 200 },
+        { "value": 300 },
+        { "value": 400 },
+        { "value": 500 },
+        { "value": 600 },
+        { "value": 700 },
+        { "value": 800 },
+        { "value": 900 },
+        { "value": 1000 },
+        { "value": 1100 },
+        { "value": 1200 },
+        { "value": 1300 },
+        { "value": 1400 },
+        { "value": 1500 }
       ]
     },
     "image": {
       "type": "string",
       "default": "user image",
       "values": [
-        {
-          "value": "user image"
-        },
-        {
-          "value": "gradient image"
-        },
-        {
-          "value": "gradient"
-        },
-        {
-          "value": "guest image"
-        },
-        {
-          "value": "initials"
-        }
+        { "value": "user image" },
+        { "value": "gradient image" },
+        { "value": "gradient" },
+        { "value": "guest image" },
+        { "value": "initials" }
       ]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "showStroke": {
-      "type": "boolean",
-      "default": false
-    }
+    "isDisabled": { "type": "boolean", "default": false },
+    "showStroke": { "type": "boolean", "default": false }
   },
   "states": [
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    },
-    {
-      "name": "disabled",
-      "trigger": "prop"
-    }
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" },
+    { "name": "disabled", "trigger": "prop" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }