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

package/components/progress-bar.json

@@ -9,6 +9,19 @@
     "category": "status",
     "documentationUrl": "https://spectrum.adobe.com/page/progress-bar/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "ProgressBar",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "ProgressBar",
+      "importPath": "@adobe/spectrum-wc/components/progress-bar",
+      "notes": "Spectrum 2 web component custom element: swc-progress-bar."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,55 +29,102 @@
     },
     {
       "type": "guideline",
-      "content": "Minimum and maximum width.\n\nThe minimum width of a progress bar is 48 px and the maximum width of a progress bar is 768 px, for both desktop and mobile platform scale. Smaller progress bars should only be used in places where it's not necessary to have a label."
+      "content": "A progress bar can be either determinate or indeterminate. By default, progress bars are determinate. Use a determinate progress bar when progress can be calculated against a specific goal (e.g., downloading a file of a known size). Use an indeterminate progress bar when progress is happening but the time or effort to completion can’t be determined (e.g., attempting to reconnect to a server)."
+    },
+    {
+      "type": "guideline",
+      "content": "Progress bars come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
+    },
+    {
+      "type": "guideline",
+      "content": "Progress bars can have a value label that gives detailed information about the progress (e.g. \"60%\" or \"2 of 8\"). This value label works alongside the label and should not be displayed if the label itself is not displayed. It should also not be displayed if the progress is indeterminate. Similar to the label, the value label is always placed above the track."
+    },
+    {
+      "type": "guideline",
+      "content": "The value represents progress within the bar’s range, from minimum to maximum. These defaults are 0 and 100 but can be customized. Min and max values don’t apply to indeterminate progress bars."
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates."
+      "content": "The label of the progress bar can be hidden if the context for the progress bar is sufficient without the title — for example, when the progress bar is shown inside a table row and the item is labeled in another column."
     },
     {
       "type": "guideline",
-      "content": "Progress bar or progress circle?\n\nBoth progress bars and circles can show either determinate or indeterminate progress. The available space should help determine whether a progress bar or circle is best. Progress bars are preferred in vertically narrow areas such as tables or cards. Use a progress circle for full-page loading or very small areas. Use a progress bar in a loader dialog."
+      "content": "Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited."
     },
     {
       "type": "guideline",
-      "content": "Labels.\n\nUse the built-in style to show a label associated with the operation. This style always includes a left-aligned label and a right-aligned percentage value above the track. The label should be in sentence case. Add an ellipsis (\"...\") at the end to indicate that the action is in progress — for example, \"Loading data...\" or \"Updating settings..."
+      "content": "Progress bars should have a label that gives context about the operation being performed. Use an ellipsis at the end of the label text to communicate that the process is in progress. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These progress bars should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the progress bar is mirrored for both determinate and indeterminate options. The label is right-aligned, the value is left-aligned, and the fill progresses from right to left. Keep in mind that the placement of the percent sign differs depending on the locale."
+      "content": "When a progress bar needs to be placed on top of a colored background, use the over background variant. This progress bar uses a static white color regardless of the color theme. Make sure the background offers enough contrast for the progress bar to be legible."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
+      "content": "Use the over background variant when a progress bar needs to be placed on top of a colored background or visual."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
+      "content": "Over background progress bars are available in static black or white, meaning they don’t change with the theme of the page. Use static black on light color or image backgrounds, and white on dark color or image backgrounds."
     },
     {
       "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 buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, 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, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.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.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various 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."
+      "content": "The minimum width of a progress bar is 48 px and the maximum width of a progress bar is 768 px, for both desktop and mobile platform scale. Smaller progress bars should only be used in places where it’s not necessary to have a label."
+    },
+    {
+      "type": "guideline",
+      "content": "When the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates."
+    },
+    {
+      "type": "guideline",
+      "content": "Both progress bars and circles can show either determinate or indeterminate progress. The available space should help determine whether a progress bar or circle is best. Progress bars are preferred in vertically narrow areas such as tables or cards. Use a progress circle for full-page loading or very small areas. Use a progress bar in a loader dialog."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the built-in style to show a label associated with the operation. This style always includes a left-aligned label and a right-aligned percentage value above the track. The label should be in sentence case. Add an ellipsis (\"...\") at the end to indicate that the action is in progress — for example, \"Loading data...\" or \"Updating settings..."
     }
   ],
   "options": {
     "variant": {
       "type": "string",
       "default": "default",
-      "values": [{ "value": "default" }, { "value": "over background" }]
+      "values": [
+        {
+          "value": "default"
+        },
+        {
+          "value": "over background"
+        }
+      ]
     },
     "staticColor": {
       "type": "string",
       "description": "Static color can only be white, otherwise it is default.",
-      "values": [{ "value": "white" }]
+      "values": [
+        {
+          "value": "white"
+        }
+      ]
+    },
+    "label": {
+      "type": "string"
     },
-    "label": { "type": "string" },
     "labelPosition": {
       "type": "string",
       "default": "top",
-      "values": [{ "value": "top" }, { "value": "side" }]
+      "values": [
+        {
+          "value": "top"
+        },
+        {
+          "value": "side"
+        }
+      ]
+    },
+    "hideLabel": {
+      "type": "boolean",
+      "default": false
     },
-    "hideLabel": { "type": "boolean", "default": false },
     "value": {
       "type": "number",
       "description": "Not applicable when indeterminate."
@@ -79,27 +139,52 @@
       "default": 1,
       "description": "Not applicable when indeterminate."
     },
-    "valueLabel": { "type": "string" },
-    "width": { "type": "number" },
+    "valueLabel": {
+      "type": "string"
+    },
+    "width": {
+      "type": "number"
+    },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        { "value": "s" },
-        { "value": "m" },
-        { "value": "l" },
-        { "value": "xl" }
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
       ]
     },
-    "isIndeterminate": { "type": "boolean", "default": false }
+    "isIndeterminate": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "progressbar",
     "focusable": false,
     "wcag": [
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" },
-      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      },
+      {
+        "criterion": "4.1.3",
+        "level": "AA",
+        "title": "Status Messages"
+      }
     ]
   }
 }

package/components/progress-circle.json

@@ -9,6 +9,19 @@
     "category": "status",
     "documentationUrl": "https://spectrum.adobe.com/page/progress-circle/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "ProgressCircle",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "ProgressCircle",
+      "importPath": "@adobe/spectrum-wc/components/progress-circle",
+      "notes": "Spectrum 2 web component custom element: swc-progress-circle."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,34 +29,41 @@
     },
     {
       "type": "guideline",
-      "content": "Use progress circles for loading views.\n\nMedium and large progress circles are optimized for large areas with no space constraints. Use them for loading content into views (e.g., web pages, panels, etc.)"
+      "content": "Progress circles can be determinate or indeterminate. Use determinate when progress can be measured against a goal, such as downloading a file. Use indeterminate when the duration or effort is unknown, like reconnecting to a server."
     },
     {
       "type": "guideline",
-      "content": "Use small progress circle when space is limited.\n\nSmall progress circles are well suited when space is limited both vertically and horizontally, such as in buttons, menu items, and input fields."
+      "content": "Progress circles come in 3 sizes: small, medium (default), or large. These are available to fit various contexts. For example, the small progress circle can be used in place of an icon or in tight spaces, while the large one can be used for full-page loading."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the fill of both the determinate and indeterminate progress circle continues to spin clockwise."
+      "content": "The value represents progress within the circle’s range, from minimum to maximum. These defaults are 0 and 100 but can be customized. Min and max values don’t apply to indeterminate progress circles."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
+      "content": "When a progress circle needs to be placed on top of a colored background, use the over background variant. This progress circle uses a static white color regardless of the color theme. Make sure the background offers enough contrast for the progress circle to be legible."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
+      "content": "Medium and large progress circles are optimized for large areas with no space constraints. Use them for loading content into views (e.g., web pages, panels, etc.)"
     },
     {
       "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 buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, 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, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.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.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various 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."
+      "content": "Small progress circles are well suited when space is limited both vertically and horizontally, such as in buttons, menu items, and input fields."
     }
   ],
   "options": {
     "variant": {
       "type": "string",
       "default": "default",
-      "values": [{ "value": "default" }, { "value": "over background" }]
+      "values": [
+        {
+          "value": "default"
+        },
+        {
+          "value": "over background"
+        }
+      ]
     },
     "value": {
       "type": "number",
@@ -62,17 +82,40 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        }
+      ]
     },
-    "isIndeterminate": { "type": "boolean", "default": false }
+    "isIndeterminate": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "progressbar",
     "focusable": false,
     "wcag": [
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" },
-      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      },
+      {
+        "criterion": "4.1.3",
+        "level": "AA",
+        "title": "Status Messages"
+      }
     ]
   }
 }

package/components/radio-button.json

@@ -16,39 +16,80 @@
     },
     {
       "type": "guideline",
-      "content": "Keyboard focus.\n\nA radio button can be navigated using a keyboard. The keyboard focus state takes the radio button's visual hover state and adds a blue ring to the radio button in focus."
+      "content": "Radio buttons present a list of options where only one can be selected at a time. They are styled consistently with other components that support binary selection. Use when all options should be visible and only one can apply."
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the button text is too long for the horizontal space available, it wraps to form another line."
+      "content": "Radio button should always have a label for accessibility and clear comprehension. When the label is not defined, a radio button becomes standalone. Standalone radio buttons should only be used when their connection to other components is clear and they give sufficient context — for example, in application panels."
     },
     {
       "type": "guideline",
-      "content": "Radio button, checkbox or switch?\n\nRadio buttons are best when only one option can be selected at a time from a set (for example choosing one preference or mode). Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list)."
+      "content": "By default, radio buttons are not emphasized. This version is optimal for when the radio button is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content."
     },
     {
       "type": "guideline",
-      "content": "When to use an emphasized radio button?\n\nEmphasized radio buttons are optimal for forms, settings, and other scenarios where the radio buttons need to be noticed. Default radio buttons are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
+      "content": "The emphasized version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a radio button needs to be noticed."
     },
     {
       "type": "guideline",
-      "content": "No partial state.\n\nRadio buttons can only be on or off. Indeterminate radio buttons don't exist in accessibility APIs, so it's not possible to make an indeterminate radio button accessible. If you need to show a partial state, use a checkbox instead of a radio button. When a parent radio button represents a group of radio buttons, it should be turned off unless all of the radio buttons are on (turning the parent radio button on turns all of the radio buttons on)."
+      "content": "Radio button can either be selected or not selected. They cannot be in an indeterminate state (unlike checkboxes)."
+    },
+    {
+      "type": "guideline",
+      "content": "Radio buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
+    },
+    {
+      "type": "guideline",
+      "content": "A radio button can be navigated using a keyboard. The keyboard focus state takes the radio button’s visual hover state and adds a blue ring to the radio button in focus."
+    },
+    {
+      "type": "guideline",
+      "content": "When the button text is too long for the horizontal space available, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "Radio buttons are best when only one option can be selected at a time from a set (for example choosing one preference or mode). Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list)."
+    },
+    {
+      "type": "guideline",
+      "content": "Emphasized radio buttons are optimal for forms, settings, and other scenarios where the radio buttons need to be noticed. Default radio buttons are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
+    },
+    {
+      "type": "guideline",
+      "content": "Radio buttons can only be on or off. Indeterminate radio buttons don’t exist in accessibility APIs, so it’s not possible to make an indeterminate radio button accessible. If you need to show a partial state, use a checkbox instead of a radio button. When a parent radio button represents a group of radio buttons, it should be turned off unless all of the radio buttons are on (turning the parent radio button on turns all of the radio buttons on)."
     }
   ],
   "options": {
-    "isSelected": { "type": "boolean", "default": false },
-    "isEmphasized": { "type": "boolean", "default": false },
+    "isSelected": {
+      "type": "boolean",
+      "default": false
+    },
+    "isEmphasized": {
+      "type": "boolean",
+      "default": false
+    },
     "label": {
       "type": "string",
       "description": "The text displayed next to a radio button."
     }
   },
   "states": [
-    { "name": "hover", "trigger": "interaction" },
-    { "name": "down", "trigger": "interaction" },
-    { "name": "keyboard-focus", "trigger": "interaction" }
+    {
+      "name": "hover",
+      "trigger": "interaction"
+    },
+    {
+      "name": "down",
+      "trigger": "interaction"
+    },
+    {
+      "name": "keyboard-focus",
+      "trigger": "interaction"
+    }
   ],
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "tokenBindings": [
     {
       "token": "neutral-content-color-selected-default",
@@ -69,9 +110,21 @@
     "focusable": true,
     "keyboardIntents": ["activate"],
     "wcag": [
-      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
-      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "1.3.1",
+        "level": "A",
+        "title": "Info and Relationships"
+      },
+      {
+        "criterion": "2.1.1",
+        "level": "A",
+        "title": "Keyboard"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }