@adobe/spectrum-design-data 3.2.3 → 3.3.0-beta.1

package/components/steplist.json

@@ -51,14 +51,7 @@
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     },
     "items": {
       "type": "array",
@@ -100,28 +93,16 @@
       "name": "track-size",
       "description": "The connecting track between steps."
     },
-    {
-      "name": "track"
-    }
+    { "name": "track" }
   ],
-  "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" }
     ]
   }
 }

package/components/swatch-group.json

@@ -16,23 +16,23 @@
     },
     {
       "type": "guideline",
-      "content": "Swatch groups organize related swatches into a single container. They’re used to display collections of colors, gradients, textures, or materials for comparison or selection."
+      "content": "Border only for low-contrast swatches.\n\nIt's important for users to compare colors when they're displayed in a swatch group. Because of this, swatches within a swatch group with low contrast (below 3:1 contrast with the background) have a less prominent border compared to the swatch component when used by itself. This reduces the likelihood of the UI interfering with color perception and comparisons."
     },
     {
       "type": "guideline",
-      "content": "Swatch groups come in 3 densities: regular (default), compact, and spacious. Compact and spacious densities retain the same swatch size as regular density but have less or more padding between each swatch, respectively."
+      "content": "Corner rounding in swatch groups.\n\nA corner rounding of none should be used in a swatch group in order to help minimize the Hermann grid illusion that happens at the intersections of the white space within the group. The only exception is when a swatch group only takes up a single row. In that case, use any of the rounding options: none, partial rounding, or full rounding."
     },
     {
       "type": "guideline",
-      "content": "By default, selection is not enabled in a swatch group. Selection can be enabled for a swatch group to allow for toggling. This is often used inside of swatch panels."
+      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto the swatch or swatch group.Arrow keysMoves focus through the swatches in the group."
     },
     {
       "type": "guideline",
-      "content": "When selection is enabled, a swatch group can allow for either single or multiple selection of swatches. This is often used inside of swatch panels to allow for bulk operations, such as deleting multiple swatches at once."
+      "content": "Cursor guidelines.\n\nCursor Description PointerUse the pointer cursor for all interactive elements in every state."
     },
     {
       "type": "guideline",
-      "content": "It’s important for users to compare colors when they’re displayed in a swatch group. Because of this, swatches within a swatch group with low contrast (below 3:1 contrast with the background) have a less prominent border compared to the swatch component when used by itself. This reduces the likelihood of the UI interfering with color perception and comparisons."
+      "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 must provide a text alternative that communicates the control’s purpose. All controls, especially icon‑only controls, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAASwatch groups should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized, so the grouping relationship between swatches and the selected state are programmatically conveyed.Use of color 1.4.1 AThis criterion requires that color not be the only method of communicating information. In swatches, the color itself is the content being presented, not a cue that conveys additional meaning. 2. Operable RequirementCriterionLevel 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": {
@@ -40,51 +40,27 @@
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "xs"
-        },
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
+        { "value": "xs" },
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" }
       ]
     },
     "density": {
       "type": "string",
       "default": "regular",
       "values": [
-        {
-          "value": "compact"
-        },
-        {
-          "value": "regular"
-        },
-        {
-          "value": "spacious"
-        }
+        { "value": "compact" },
+        { "value": "regular" },
+        { "value": "spacious" }
       ]
     },
-    "enableSelection": {
-      "type": "boolean",
-      "default": false
-    },
+    "enableSelection": { "type": "boolean", "default": false },
     "selectionMode": {
       "type": "string",
       "description": "Only applicable if selection is enabled.",
       "default": "single",
-      "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "multiple"
-        }
-      ]
+      "values": [{ "value": "single" }, { "value": "multiple" }]
     },
     "allowsEmptySelection": {
       "type": "boolean",
@@ -96,31 +72,19 @@
       "default": "none",
       "description": "Determines the corner radius of each swatch in the group. Partial refers to corner-radius-75.",
       "values": [
-        {
-          "value": "none"
-        },
-        {
-          "value": "full"
-        },
-        {
-          "value": "partial"
-        }
+        { "value": "none" },
+        { "value": "full" },
+        { "value": "partial" }
       ]
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "group",
     "intents": ["choose"],
     "focusable": false,
     "wcag": [
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }

package/components/swatch.json

@@ -16,31 +16,27 @@
     },
     {
       "type": "guideline",
-      "content": "The preview shows the sample of the fill that the swatch represents. This property can be a color, gradient, texture, or material. The exact format this property takes will depend on implementation. Some examples of the format include color values, image, canvas, and gradient."
+      "content": "Keyboard focus.\n\nA swatch can be navigated using a keyboard. The keyboard focus state adds a blue ring to the swatch in focus."
     },
     {
       "type": "guideline",
-      "content": "Swatches come in four different sizes: extra-small, small, medium, and 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."
+      "content": "Mixed value.\n\nWhen a swatch represents multiple values that are not identical, the preview shows a gray fill and a dash UI icon."
     },
     {
       "type": "guideline",
-      "content": "By default, swatches have partial rounding. There are 3 options for a swatch’s rounding: none, partial rounding, and full rounding."
+      "content": "Hide unavailable swatches when possible.\n\nEven though swatches can have a disabled state, hiding unavailable swatches reduces visual clutter and eases cognitive load. Only show disabled swatches if hiding them would cause confusion to your users."
     },
     {
       "type": "guideline",
-      "content": "A swatch can have a selected state to allow for selection. This is often used in a swatch group."
+      "content": "Keyboard interactions.\n\nKeyInteractionTabMoves focus onto or off of the swatch group. Focus moves to the first swatch in the group.Space or EnterTriggers an action or selects the swatch when selection is enabled. The focus remains on the swatch, unless the swatch opens or closes the current container. In this case, the focus moves to the target or back to the caller."
     },
     {
       "type": "guideline",
-      "content": "A swatch in a disabled state shows that the swatch exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that a swatch may become available later. Disabled swatches should be used with caution."
+      "content": "Cursor guidelines.\n\nCursor Description PointerUse the pointer cursor for all interactive elements in every state."
     },
     {
       "type": "guideline",
-      "content": "A swatch can be navigated using a keyboard. The keyboard focus state adds a blue ring to the swatch in focus."
-    },
-    {
-      "type": "guideline",
-      "content": "Even though swatches can have a disabled state, hiding unavailable swatches reduces visual clutter and eases cognitive load. Only show disabled swatches if hiding them would cause confusion to your users."
+      "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 must provide a text alternative that communicates the control’s purpose. All controls, especially icon‑only controls, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAASwatch groups should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized, so the grouping relationship between swatches and the selected state are programmatically conveyed.Use of color 1.4.1 AThis criterion requires that color not be the only method of communicating information. In swatches, the color itself is the content being presented, not a cue that conveys additional meaning. 2. Operable RequirementCriterionLevel 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": {
@@ -52,102 +48,51 @@
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "xs"
-        },
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
+        { "value": "xs" },
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" }
       ]
     },
     "shape": {
       "type": "string",
       "default": "square",
-      "values": [
-        {
-          "value": "square"
-        },
-        {
-          "value": "rectangle"
-        }
-      ]
+      "values": [{ "value": "square" }, { "value": "rectangle" }]
     },
     "cornerRounding": {
       "type": "string",
       "default": "none",
       "description": "Determines the corner radius of the swatch. Partial refers to corner-radius-75.",
       "values": [
-        {
-          "value": "none"
-        },
-        {
-          "value": "partial"
-        },
-        {
-          "value": "full"
-        }
+        { "value": "none" },
+        { "value": "partial" },
+        { "value": "full" }
       ]
     },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
+    "isSelected": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
   },
   "anatomy": [
     {
       "name": "slash",
       "description": "Diagonal slash indicating an empty or \"none\" swatch."
     },
-    {
-      "name": "icon"
-    }
+    { "name": "icon" }
   ],
   "states": [
-    {
-      "name": "hover",
-      "trigger": "interaction"
-    },
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    },
-    {
-      "name": "disabled",
-      "trigger": "prop"
-    }
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" },
+    { "name": "disabled", "trigger": "prop" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "intents": ["choose"],
     "focusable": true,
     "keyboardIntents": ["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" }
     ]
   }
 }

package/components/switch.json

@@ -16,141 +16,100 @@
     },
     {
       "type": "guideline",
-      "content": "Switches toggle an individual option on or off. They're typically used to activate or deactivate a specific setting."
+      "content": "Keyboard focus.\n\nA switch can be navigated using a keyboard. The keyboard focus state takes the switch's visual hover state and adds a blue ring to the switch in focus."
     },
     {
       "type": "guideline",
-      "content": "Switch should always have a label for accessibility and clear comprehension. When the label is not defined, a switch becomes standalone. Standalone switches should only be used when their connection to other components is clear and they give sufficient context — for example, in application panels."
+      "content": "Text overflow.\n\nWhen the label is too long for the horizontal space available, it wraps to form another line."
     },
     {
       "type": "guideline",
-      "content": "Switches can either be selected or not selected. They cannot be in an indeterminate state (unlike checkboxes). When a switch represents multiple values that are not identical, the switch should appear as not selected."
+      "content": "When to use an emphasized switch?\n\nEmphasized switches are optimal for forms, settings, and other scenarios where the switches need to be noticed. Not emphasized switches are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
     },
     {
       "type": "guideline",
-      "content": "Switch 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."
+      "content": "When to use a standalone switch?\n\nStandalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options."
     },
     {
       "type": "guideline",
-      "content": "By default, switches are not emphasized (gray). This version is optimal for when the switch 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."
+      "content": "Switch, checkbox or radio button?\n\nSwitches 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). Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode)."
     },
     {
       "type": "guideline",
-      "content": "The emphasized (blue) version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a switch needs to be noticed."
+      "content": "Representing mixed values.\n\nWhen a switch represents multiple values that are not identical, the switch should appear as not selected. Any subsequent click or tap should select the switch, and update all values to be selected. Another click or tap after that should deselect the switch, and update all values to be not selected."
     },
     {
       "type": "guideline",
-      "content": "A switch in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later."
+      "content": "No partial state.\n\nSwitches can only be on or off. Indeterminate switches don't exist in accessibility APIs, so it's not possible to make an indeterminate switch accessible. If you need to show a partial state, use a checkbox instead of a switch. When a parent switch represents a group of switches, it should be turned off unless all of the switches are on (turning the parent switch on turns all of the switches on)."
     },
     {
       "type": "guideline",
-      "content": "Switches have a read-only option for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed."
+      "content": "Consider if the label should use a verb or a noun.\n\nA switch shows a state of persistence for something — a noun or a proper noun — as either being \"on\" or \"off.\" A verb isn't usually needed to communicate the thing being turned on or off, but there can be instances where phrasing the label as a verb can aid in clarity. Just try to keep switches consistently using either verbs or nouns if you have more than one of them in a single view."
     },
     {
       "type": "guideline",
-      "content": "A switch can be navigated using a keyboard. The keyboard focus state takes the switch’s visual hover state and adds a blue ring to the switch in focus."
+      "content": "Avoid using verb phrases related to a state of activity.\n\nAvoid using verb phrases related to activity states in a switch label, such as \"turn on\" or \"turn off.\" A switch is naturally either in a state of being on or off — active or inactive — so repeating in the label that something is \"on\" or \"off\" is redundant and clutters an interface."
     },
     {
       "type": "guideline",
-      "content": "When the label is too long for the horizontal space available, it wraps to form another line."
+      "content": "Use a neutral tone.\n\nBecause switches are used for controls and utility, their labels are written in a neutral, utilitarian way. There's no need for overly celebratory language."
     },
     {
       "type": "guideline",
-      "content": "Emphasized switches are optimal for forms, settings, and other scenarios where the switches need to be noticed. Not emphasized switches are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
+      "content": "Use \"you\" or \"your\" if needed to refer to the user directly.\n\nDescribe switches objectively by using only the names of features or settings, or what those features and settings will do. In the case where it's necessary to refer to a user directly, do so sparingly and use the second person \"you/your.\" We aim to be conversational and talk to the user — not as them."
     },
     {
       "type": "guideline",
-      "content": "Standalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options."
+      "content": "Use sentence case.\n\nFollowing Adobe's UX writing style, labels for switches are written in sentence case unless they contain words that are branded terms."
     },
     {
       "type": "guideline",
-      "content": "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). Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode)."
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the switch is mirrored. The track is placed on the right side of the text and the handle is positioned to the left when the switch is turned on."
     },
     {
       "type": "guideline",
-      "content": "When a switch represents multiple values that are not identical, the switch should appear as not selected. Any subsequent click or tap should select the switch, and update all values to be selected. Another click or tap after that should deselect the switch, and update all values to be not selected."
+      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus to the next item or group of items.Shift + TabMoves focus to the previous item or group of items.Space or EnterToggles the switch between on and off."
     },
     {
       "type": "guideline",
-      "content": "Switches can only be on or off. Indeterminate switches don’t exist in accessibility APIs, so it’s not possible to make an indeterminate switch accessible. If you need to show a partial state, use a checkbox instead of a switch."
+      "content": "Cursor guidelines.\n\nCursor Description PointerUse the pointer cursor for interactive elements in all states."
     },
     {
       "type": "guideline",
-      "content": "When a parent switch represents a group of switches, it should be turned off unless all of the switches are on (turning the parent switch on turns all of the switches on)."
+      "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 Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAASwitches should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized.Use of color 1.4.1 ASwitches never rely on color alone to convey meaning. The active state uses blue to reinforce “on,” and the handle shifts position to clearly show whether the switch is on or off.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 AASwitches should be built in such a way that they can be resized without assistive technology up to 200%.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 when the label is wrapped. 2. Operable RequirementCriterionLevel 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": {
-    "label": {
-      "type": "string"
-    },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
-    },
+    "label": { "type": "string" },
+    "isSelected": { "type": "boolean", "default": false },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "isReadOnly": {
-      "type": "boolean",
-      "default": false
-    }
+    "isEmphasized": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isReadOnly": { "type": "boolean", "default": false }
   },
   "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" },
   "accessibility": {
     "role": "switch",
     "intents": ["choose"],
     "focusable": true,
     "keyboardIntents": ["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" }
     ]
   }
 }