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

package/components/badge.json

@@ -9,6 +9,19 @@
     "category": "status",
     "documentationUrl": "https://spectrum.adobe.com/page/badge/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Badge",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "Badge",
+      "importPath": "@adobe/spectrum-wc/components/badge",
+      "notes": "Spectrum 2 web component custom element: swc-badge."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,46 +29,59 @@
     },
     {
       "type": "guideline",
-      "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)."
+      "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."
+    },
+    {
+      "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."
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen a badge's label is too long for the available horizontal space, it wraps to form another line."
+      "content": "A Badge’s style determines its visual emphasis. Badges come in three different styles: bold, subtle, and outline."
     },
     {
-      "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": "When badges have a semantic meaning, they use semantic colors. Use these variants for the following statuses:"
     },
     {
       "type": "guideline",
-      "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."
+      "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": "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": "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."
     },
     {
-      "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": "Badges should always have a label for accessibility and clear comprehension. When the label is not defined, a badge becomes icon-only."
     },
     {
       "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": "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": "guideline",
-      "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."
+      "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": "Cursor guidelines.\n\nCursor Usage Default (Arrow)Use the default cursor for non-interactive components like the badge."
+      "content": "Blue badges are easily confused with Spectrum's blue accent buttons. Only use blue badges when absolutely necessary."
     },
     {
       "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 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."
+      "content": "The 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 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": "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": "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."
     }
   ],
   "options": {
@@ -69,65 +95,146 @@
     "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
+  }
 }

package/components/breadcrumbs.json

@@ -9,6 +9,13 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/breadcrumbs/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Breadcrumbs",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,44 +23,71 @@
     },
     {
       "type": "guideline",
-      "content": "Overflow.\n\nBreadcrumbs truncate when there is not enough room to display all levels of the breadcrumb list, or as a way of managing relevance of the visible breadcrumb items in a deeply nested hierarchy. The truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display. The truncation menu displays all options within a breadcrumb. Items are listed with the hierarchy ordered from top (root) to bottom and include the currently selected item."
+      "content": "When set to true, the breadcrumb item is displayed as an icon only."
+    },
+    {
+      "type": "guideline",
+      "content": "Separators visually divide breadcrumb items and convey hierarchy."
+    },
+    {
+      "type": "guideline",
+      "content": "Breadcrumbs can include multiple items, but too many levels can overwhelm users. Limit the hierarchy to four items (including the root, if shown) to provide clear context while keeping truncated options accessible."
+    },
+    {
+      "type": "guideline",
+      "content": "Breadcrumbs come in two sizes: medium, and large. The medium size is the default and most frequently used option."
+    },
+    {
+      "type": "guideline",
+      "content": "The multiline variation places emphasis on the selected breadcrumb item as a page title, helping a user to more clearly identify their current location."
+    },
+    {
+      "type": "guideline",
+      "content": "Breadcrumbs truncate when there is not enough room to display all levels of the breadcrumb list, or as a way of managing relevance of the visible breadcrumb items in a deeply nested hierarchy. The truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display."
+    },
+    {
+      "type": "guideline",
+      "content": "The truncation menu displays all options within a breadcrumb. Items are listed with the hierarchy ordered from top (root) to bottom and include the currently selected item."
+    },
+    {
+      "type": "guideline",
+      "content": "Breadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location."
     },
     {
       "type": "guideline",
-      "content": "Use breadcrumbs to show hierarchy.\n\nBreadcrumbs need a consistent hierarchical structure because they create a path for discovery and context for a user’s current location."
+      "content": "Breadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters."
     },
     {
       "type": "guideline",
-      "content": "Use breadcrumbs for hierarchical navigation.\n\nBreadcrumbs should be a form of navigating a linear hierarchy. They should not be used for any other interactions, such as displaying filters."
+      "content": "The truncation menu should display all available options within the hierarchy where a user is located — not as indented. Doing this provides context for the directionality of how the menu is being displayed. Adding indentation to the menu items does not add value to understanding the hierarchy, and it can actually decrease the readability of the menu options."
     },
     {
-      "type": "do-dont",
-      "content": "Don't indent menu items",
-      "dont": "The truncation menu should display all available options within the hierarchy where a user is located — not as indented. Doing this provides context for the directionality of how the menu is being displayed. Adding indentation to the menu items does not add value to understanding the hierarchy, and it can actually decrease the readability of the menu options."
+      "type": "guideline",
+      "content": "When list items are truncated into a menu but the label text is still too large for the horizontal space, truncate the text with an ellipsis. By default, truncation should occur at the end of the title. If your users need to see the end of truncated titles, truncating the middle of the title is acceptable."
     },
     {
       "type": "guideline",
-      "content": "Don’t wrap breadcrumb list items.\n\nWhen list items are truncated into a menu but the label text is still too large for the horizontal space, truncate the text with an ellipsis. By default, truncation should occur at the end of the title. If your users need to see the end of truncated titles, truncating the middle of the title is acceptable."
+      "content": "When the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile."
     },
     {
       "type": "guideline",
-      "content": "Tooltips.\n\nWhen the breadcrumb title is truncated, a tooltip should display the full title when the user hovers, keyboard focuses, or single-taps on mobile."
+      "content": "Prioritize using the truncation menu when breadcrumb labels are long. Never truncate more than one breadcrumb label. If the current location has a long label, all items can be truncated into the menu."
     },
     {
       "type": "guideline",
-      "content": "Truncation and overflow.\n\nPrioritize using the truncation menu when breadcrumb labels are long. Never truncate more than one breadcrumb label. If the current location has a long label, all items can be truncated into the menu. Truncation should be avoided by way of the breadcrumbs overflow behavior, although in some cases the final breadcrumb title may truncate with an ellipsis."
+      "content": "Truncation should be avoided by way of the breadcrumbs overflow behavior, although in some cases the final breadcrumb title may truncate with an ellipsis."
     },
     {
       "type": "guideline",
-      "content": "Don’t show too many breadcrumbs at once.\n\nBe mindful of your user’s cognitive load and truncate breadcrumbs appropriately. Displaying too many levels can be overwhelming. By displaying only 4 items in the hierarchy (including the root item, if you are displaying it), users will quickly understand context while still having easy access to any truncated options. Truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display."
+      "content": "Be mindful of your user’s cognitive load and truncate breadcrumbs appropriately. Displaying too many levels can be overwhelming. By displaying only 4 items in the hierarchy (including the root item, if you are displaying it), users will quickly understand context while still having easy access to any truncated options. Truncation of breadcrumb items begins when either there is not enough room to display all items, or if there are 5 or more breadcrumbs to display."
     },
     {
       "type": "guideline",
-      "content": "Icons in breadcrumbs.\n\nDon't use icons within the labels for breadcrumbs. Since breadcrumb labels are horizontally distributed, icons disrupt the rhythm and readability of the list."
+      "content": "Don't use icons within the labels for breadcrumbs. Since breadcrumb labels are horizontally distributed, icons disrupt the rhythm and readability of the list."
     },
     {
       "type": "guideline",
-      "content": "Don’t modify breadcrumbs for lateral navigation.\n\nBreadcrumbs are a way for traveling up a hierarchical navigation and should not be mixed with controls intended for lateral or non-hierarchical navigation."
+      "content": "Breadcrumbs are a way for traveling up a hierarchical navigation and should not be mixed with controls intended for lateral or non-hierarchical navigation."
     }
   ],
   "options": {
@@ -66,7 +100,14 @@
       "type": "string",
       "default": "m",
       "description": "Controls the overall size of the breadcrumb component.",
-      "values": [{ "value": "m" }, { "value": "l" }]
+      "values": [
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        }
+      ]
     },
     "items": {
       "type": "array",
@@ -87,7 +128,10 @@
             "description": "Indicates if the breadcrumb item represents the current page.",
             "default": false
           },
-          "isDisabled": { "type": "boolean", "default": false }
+          "isDisabled": {
+            "type": "boolean",
+            "default": false
+          }
         },
         "required": ["label"]
       }
@@ -96,7 +140,14 @@
       "type": "string",
       "default": "chevron",
       "description": "The separator icon used between breadcrumb items.",
-      "values": [{ "value": "chevron" }, { "value": "none" }]
+      "values": [
+        {
+          "value": "chevron"
+        },
+        {
+          "value": "none"
+        }
+      ]
     },
     "isTruncated": {
       "type": "boolean",
@@ -107,10 +158,18 @@
       "type": "string",
       "description": "Overrides the size of the breadcrumb items when isMultiline is true.",
       "values": [
-        { "value": "s" },
-        { "value": "m" },
-        { "value": "l" },
-        { "value": "xl" }
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
       ]
     }
   },
@@ -121,19 +180,41 @@
     }
   ],
   "states": [
-    { "name": "hover", "trigger": "interaction" },
-    { "name": "down", "trigger": "interaction" },
-    { "name": "keyboard-focus", "trigger": "interaction" },
-    { "name": "drag-and-drop", "trigger": "prop" }
+    {
+      "name": "hover",
+      "trigger": "interaction"
+    },
+    {
+      "name": "down",
+      "trigger": "interaction"
+    },
+    {
+      "name": "keyboard-focus",
+      "trigger": "interaction"
+    },
+    {
+      "name": "drag-and-drop",
+      "trigger": "prop"
+    }
   ],
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "accessibility": {
     "intents": ["navigate"],
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate"],
     "wcag": [
-      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "2.1.1",
+        "level": "A",
+        "title": "Keyboard"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }