@adobe/spectrum-design-data 3.3.0-beta.0 → 3.3.0-beta.2

package/components/alert-dialog.json

@@ -16,80 +16,76 @@
     },
     {
       "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": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
+      "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": "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": "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": "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": "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": "Use the appropriate variant based on the context of the message:"
+      "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 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": "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": "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": "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": "When the title and description text are too long for the available horizontal space, they wrap to form another line."
+      "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 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": "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": "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": "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": "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": "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": "Keyboard interactions.\n\nKey Interaction TabMoves 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 + TabMoves 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.EscDismisses the alert dialog. This is equivalent to choosing “Cancel” or an “OK” confirmation.EscDismisses the alert banner if possible. This is equivalent to selecting the close button."
+    },
+    {
+      "type": "guideline",
+      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow)Use the default cursor for non-interactive elements and text within the alert dialog.PointerUse the pointer cursor for any interactive elements, such as buttons, inside the alert dialog."
+    },
+    {
+      "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 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, AAAAlert 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 AColor is not used as a means to convey information or distinguish elements.Contrast 1.4.3 AAThe visual presentation of text has a contrast ratio of at least 4.5:1.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 illustrations and component states 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. 2. Operable Requirement Criterion Level 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."
     }
   ],
   "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."
@@ -100,25 +96,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

@@ -48,35 +48,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

@@ -56,107 +56,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 }
 }

package/components/badge.json

@@ -16,59 +16,46 @@
     },
     {
       "type": "guideline",
-      "content": "Badges come in four different sizes: small, medium, large, and extra-large. The small size is the default and most frequently used option. Use the other sizes sparingly to create a hierarchy of importance on a page."
+      "content": "Non‑interactive by default.\n\nBadges are display elements, not actions. They should not behave like buttons or links. If an action is required, use a more appropriate component (e.g., Button, Action button)."
     },
     {
       "type": "guideline",
-      "content": "Badges can be placed as floating in a container, or they can be fixed to any edge of a container. They lose their default corner rounding on the fixed edge."
+      "content": "Text overflow.\n\nWhen a badge's label is too long for the available horizontal space, it wraps to form another line."
     },
     {
-      "type": "guideline",
-      "content": "A Badge’s style determines its visual emphasis. Badges come in three different styles: bold, subtle, and outline."
-    },
-    {
-      "type": "guideline",
-      "content": "When badges have a semantic meaning, they use semantic colors. Use these variants for the following statuses:"
-    },
-    {
-      "type": "guideline",
-      "content": "When badges are for color-coded categories, they use non-semantic colors. Non-semantic variants are ideally used for when there are 8 categories or less."
+      "type": "do-dont",
+      "content": "Avoid using a blue badge",
+      "dont": "Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary."
     },
     {
       "type": "guideline",
-      "content": "A badge can have an optional icon. If no label is used, a badge becomes icon-only and it must include an icon. An icon-only badge is best for very small spaces, and it should always include a tooltip on hover to provide more context for the icon's meaning."
+      "content": "Only use a yellow badge for discounts.\n\nThe yellow badge is reserved to communicate \"best deal\" or \"discount\" situations only. Do not use the yellow badge for other situations."
     },
     {
-      "type": "guideline",
-      "content": "Badges should always have a label for accessibility and clear comprehension. When the label is not defined, a badge becomes icon-only."
+      "type": "do-dont",
+      "content": "Don't display multiple badges",
+      "dont": "Badges are meant to offer quick context about what category, status, or meaning an item is associated with. If your design requires multiple badges, consider using regular text metadata and reserve a single badge for only the most important status, category, or meaning instead."
     },
     {
-      "type": "guideline",
-      "content": "Badges are display elements, not actions. They should not behave like buttons or links. If an action is required, use a more appropriate component (e.g., Button, Action button)."
+      "type": "do-dont",
+      "content": "Avoid using icon-only badges",
+      "dont": "It's best to use a text label on a badge whenever possible because communicating with an icon alone may be unclear or subjective. Reserve icon-only badges for responsive cases, such as for cards in a panel that don't have space for a full badge. In related contexts, pair the icon with a label to help teach a user what the icon means. Icon-only badges should always include a tooltip on hover to show their associated label."
     },
     {
       "type": "guideline",
-      "content": "When a badge's label is too long for the available horizontal space, it wraps to form another line. If there is no room for a second line of text, the badge should truncate and include a tooltip to expose the full text upon hover."
-    },
-    {
-      "type": "guideline",
-      "content": "Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary."
-    },
-    {
-      "type": "guideline",
-      "content": "The yellow badge is reserved to communicate \"best deal\" or \"discount\" situations only. Do not use the yellow badge for other situations."
+      "content": "Badge placement varies widely depending on the use case. In cards, place the badge on the left side of the footer, if possible. If there is no footer or if that space is filled, affix the badge to the right edge of the preview. If there is no preview, affix the badge to the top right corner of the card."
     },
     {
       "type": "guideline",
-      "content": "Badges are meant to offer quick context about what category, status, or meaning an item is associated with. If your design requires multiple badges, consider using regular text metadata and reserve a single badge for only the most important status, category, or meaning instead."
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the badge is mirrored. The icon (if present) is right-aligned with text on the right."
     },
     {
       "type": "guideline",
-      "content": "It's best to use a text label on a badge whenever possible because communicating with an icon alone may be unclear or subjective. Reserve icon-only badges for responsive cases, such as for cards in a panel that don't have space for a full badge. In related contexts, pair the icon with a label to help teach a user what the icon means. Icon-only badges should always include a tooltip on hover to show their associated label."
+      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow)Use the default cursor for non-interactive components like the badge."
     },
     {
       "type": "guideline",
-      "content": "Badge placement varies widely depending on the use case. In cards, place the badge on the left side of the footer, if possible. If there is no footer or if that space is filled, affix the badge to the right edge of the preview. If there is no preview, affix the badge to the top right corner of the card."
+      "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 badges—must provide a text alternative that communicates the badge’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, AAABadges 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 AColor is never used as the sole way to convey meaning in buttons. Badges use color to reinforce their meaning, but every badge also includes a clear text label 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.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 when wrapped. 2. Operable Requirement Criterion Level Compliance 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."
     }
   ],
   "options": {
@@ -82,146 +69,65 @@
     "variant": {
       "type": "string",
       "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "info"
-        },
-        {
-          "value": "positive"
-        },
-        {
-          "value": "negative"
-        },
-        {
-          "value": "indigo"
-        },
-        {
-          "value": "yellow"
-        },
-        {
-          "value": "magenta"
-        },
-        {
-          "value": "fuchsia"
-        },
-        {
-          "value": "purple"
-        },
-        {
-          "value": "seafoam"
-        },
-        {
-          "value": "accent"
-        },
-        {
-          "value": "notice"
-        },
-        {
-          "value": "gray"
-        },
-        {
-          "value": "red"
-        },
-        {
-          "value": "orange"
-        },
-        {
-          "value": "chartreuse"
-        },
-        {
-          "value": "celery"
-        },
-        {
-          "value": "green"
-        },
-        {
-          "value": "cyan"
-        },
-        {
-          "value": "blue"
-        },
-        {
-          "value": "pink"
-        },
-        {
-          "value": "turquoise"
-        },
-        {
-          "value": "brown"
-        },
-        {
-          "value": "cinnamon"
-        },
-        {
-          "value": "silver"
-        }
+        { "value": "neutral" },
+        { "value": "info" },
+        { "value": "positive" },
+        { "value": "negative" },
+        { "value": "indigo" },
+        { "value": "yellow" },
+        { "value": "magenta" },
+        { "value": "fuchsia" },
+        { "value": "purple" },
+        { "value": "seafoam" },
+        { "value": "accent" },
+        { "value": "notice" },
+        { "value": "gray" },
+        { "value": "red" },
+        { "value": "orange" },
+        { "value": "chartreuse" },
+        { "value": "celery" },
+        { "value": "green" },
+        { "value": "cyan" },
+        { "value": "blue" },
+        { "value": "pink" },
+        { "value": "turquoise" },
+        { "value": "brown" },
+        { "value": "cinnamon" },
+        { "value": "silver" }
       ]
     },
     "style": {
       "type": "string",
       "values": [
-        {
-          "value": "bold"
-        },
-        {
-          "value": "subtle"
-        },
-        {
-          "value": "outline"
-        }
+        { "value": "bold" },
+        { "value": "subtle" },
+        { "value": "outline" }
       ]
     },
     "fixed": {
       "type": "string",
       "default": "none",
       "values": [
-        {
-          "value": "none"
-        },
-        {
-          "value": "top"
-        },
-        {
-          "value": "right"
-        },
-        {
-          "value": "bottom"
-        },
-        {
-          "value": "left"
-        }
+        { "value": "none" },
+        { "value": "top" },
+        { "value": "right" },
+        { "value": "bottom" },
+        { "value": "left" }
       ]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
+    "isDisabled": { "type": "boolean", "default": false },
     "size": {
       "type": "string",
       "pattern": "^(x?s|m|x{0,3}l)$",
       "default": "s",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }