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

package/components/tag-field.json

@@ -67,35 +67,81 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        }
+      ]
     },
     "style": {
       "type": "string",
       "default": "keyword",
       "values": [
-        { "value": "keyword" },
-        { "value": "icon" },
-        { "value": "thumbnail" },
-        { "value": "avatar" }
+        {
+          "value": "keyword"
+        },
+        {
+          "value": "icon"
+        },
+        {
+          "value": "thumbnail"
+        },
+        {
+          "value": "avatar"
+        }
       ]
     },
-    "isDisabled": { "type": "boolean", "default": false },
-    "hideLabel": { "type": "boolean", "default": false }
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "hideLabel": {
+      "type": "boolean",
+      "default": false
+    }
   },
   "states": [
-    { "name": "hover", "trigger": "interaction" },
-    { "name": "focus-+-hover", "trigger": "prop" },
-    { "name": "focus-+-not-hover", "trigger": "prop" },
-    { "name": "keyboard-focus", "trigger": "interaction" }
+    {
+      "name": "hover",
+      "trigger": "interaction"
+    },
+    {
+      "name": "focus-+-hover",
+      "trigger": "prop"
+    },
+    {
+      "name": "focus-+-not-hover",
+      "trigger": "prop"
+    },
+    {
+      "name": "keyboard-focus",
+      "trigger": "interaction"
+    }
   ],
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "accessibility": {
     "intents": ["input", "select"],
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate"],
     "wcag": [
-      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "1.3.1",
+        "level": "A",
+        "title": "Info and Relationships"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }

package/components/tag-group.json

@@ -9,6 +9,13 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/tag-group/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "TagGroup",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,63 +23,96 @@
     },
     {
       "type": "guideline",
-      "content": "Tag group overflow.\n\nWhen horizontal space is limited in a tag group, the individual tags wrap to form another line."
+      "content": "Tag groups organize multiple tags into a single visual group. They’re used to categorize content like keywords or names that describe an item or search query. Tags within the group can be added, removed, or styled to reflect different types of content."
     },
     {
       "type": "guideline",
-      "content": "Focus between tags.\n\nIf the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more."
+      "content": "Tag groups come in three different sizes: 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."
     },
     {
       "type": "guideline",
-      "content": "Allow bulk actions.\n\nIn some instances, it's possible to add an action next to a group of tags to provide a way to easily act on the entire group at once. Reveal the action only when more than one tag is displayed."
+      "content": "Labels can be placed either on top or on the side of a group of tags. 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": "do-dont",
-      "content": "Avoid disabling a large group of tags",
-      "dont": "In cases where users cannot interact with a large group of tags, consider hiding the group and its broader construct rather than disabling all the individual tags."
+      "type": "guideline",
+      "content": "The label of the tag group can be hidden if the context for the tags is sufficient without the title — for example, when the page title or section title applies to the group of tags."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the group of tags is mirrored. The first tag will appear on the left instead of the right and flow from there."
+      "content": "Define an action label to include a link-style button to perform an action on the entire group of tags. This button always appears at the end of the tag group."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabTabbing into a group of tags places the focus on the first tag (only one tag receives the keyboard focus at a time).Arrow keysMoves focus through the group of tags.Page Up or Page DownMoves focus to the previous or next tag in the group (last becomes first, and first becomes last).Home or EndMoves focus to the first or last tag in the group.Backspace or DeleteRemoves the tag in focus from the group.SpaceIf the tag is selectable, the space bar will toggle selection.Ctrl / Cmd + ASelects all tags."
+      "content": "When horizontal space is limited in a tag group, the individual tags wrap to form another line."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Description Default (Arrow)Use the default cursor for non-interactive tags.PointerUse the pointer cursor for interactive tags, such as tags that are removable or can be used to filter content.Grab handUse the grab hand cursor when the order of tags can be rearranged.Grab fistUse the grab fist cursor when holding a tag."
+      "content": "If the order of tags within the group matters, the user must be able to click or use keyboard focus between tags to add more."
     },
     {
       "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 tags—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, AAATags should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized.Text contrast 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 AATag groups 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 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."
+      "content": "In some instances, it's possible to add an action next to a group of tags to provide a way to easily act on the entire group at once. Reveal the action only when more than one tag is displayed."
+    },
+    {
+      "type": "guideline",
+      "content": "In cases where users cannot interact with a large group of tags, consider hiding the group and its broader construct rather than disabling all the individual tags."
     }
   ],
   "options": {
     "size": {
       "type": "string",
       "default": "m",
-      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        }
+      ]
     },
     "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 },
     "actionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
     }
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "accessibility": {
     "intents": ["select"],
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate"],
     "wcag": [
-      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "1.3.1",
+        "level": "A",
+        "title": "Info and Relationships"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }

package/components/tag.json

@@ -9,6 +9,13 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/tag/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Tag",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,58 +23,108 @@
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the tag text is too long for the available horizontal space or when a tag reaches its maximum width, it truncates. Hovering over the tag shows a tooltip with the full text."
+      "content": "Tags categorize content such as keywords or names. They’re often grouped to represent a search query or describe an item."
+    },
+    {
+      "type": "guideline",
+      "content": "Tags should always include a label. These can represent search terms, filters, or keywords."
+    },
+    {
+      "type": "guideline",
+      "content": "Tags have the option to include an avatar in addition to the label. These should be used to represent entities."
     },
     {
-      "type": "do-dont",
-      "content": "Avoid conflicting tag actions",
-      "dont": "A tag can either trigger navigation or filtering, or act as a dismissible chip. Combining both interactions disrupts focus order and accessibility states. Choose one behavior — navigation or dismissal — and apply it consistently."
+      "type": "guideline",
+      "content": "Tags have the option to be removable or not. Removable tags have a small close (“x”) button."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the tag is mirrored. The avatar is right-aligned and the close button is left-aligned."
+      "content": "A tag can be marked as having an error to show that it has become invalid."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabTabbing into a group of tags places the focus on the first tag (only one tag receives the keyboard focus at a time).Arrow keysMoves focus through the group of tags.Page Up or Page DownMoves focus to the previous or next tag in the group (last becomes first, and first becomes last).Home or EndMoves focus to the first or last tag in the group.Backspace or DeleteRemoves the tag in focus from the group.SpaceIf the tag is selectable, the space bar will toggle selection."
+      "content": "A tag in a disabled state shows that a tag exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a tag may become available later."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Description Default (Arrow)Use the default cursor for non-interactive tags.PointerUse the pointer cursor for interactive tags, such as tags that are removable or can be used to filter content.Grab handUse the grab hand cursor when the order of tags can be rearranged.Grab fistUse the grab fist cursor when holding a tag."
+      "content": "Tags have a read-only option for when content in the disabled state still needs to be shown. This allows for content to be copied, but not interacted with or changed."
     },
     {
       "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 tags—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 AATags should be understandable by assistive technologies like screen readers. This means the proper semantic HTML or ARIA role should be utilized.Text contrast 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 AATags 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. 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."
+      "content": "When the tag text is too long for the available horizontal space or when a tag reaches its maximum width, it truncates. Hovering over the tag shows a tooltip with the full text."
+    },
+    {
+      "type": "guideline",
+      "content": "A tag can either trigger navigation or filtering, or act as a dismissible chip. Combining both interactions disrupts focus order and accessibility states. Choose one behavior — navigation or dismissal — and apply it consistently."
     }
   ],
   "options": {
-    "label": { "type": "string" },
-    "hasAvatar": { "type": "boolean", "default": false },
-    "isRemovable": { "type": "boolean", "default": false },
-    "isError": { "type": "boolean", "default": false },
-    "isDisabled": { "type": "boolean", "default": false },
-    "isReadOnly": { "type": "boolean", "default": false }
+    "label": {
+      "type": "string"
+    },
+    "hasAvatar": {
+      "type": "boolean",
+      "default": false
+    },
+    "isRemovable": {
+      "type": "boolean",
+      "default": false
+    },
+    "isError": {
+      "type": "boolean",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "isReadOnly": {
+      "type": "boolean",
+      "default": false
+    }
   },
   "anatomy": [
     {
       "name": "clear-icon",
       "description": "Icon affordance that removes the tag."
     },
-    { "name": "cross-icon", "description": "Cross/X icon shown on the tag." }
+    {
+      "name": "cross-icon",
+      "description": "Cross/X icon shown on the tag."
+    }
   ],
   "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": {
     "intents": ["dismiss"],
     "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/takeover-dialog.json

@@ -16,26 +16,67 @@
     },
     {
       "type": "guideline",
-      "content": "Title text overflow.\n\nWhen the title is too long for the available horizontal space, it wraps to form another line."
+      "content": "Takeover dialogs are full-screen modals used for complex or immersive workflows. They block access to the rest of the interface and are typically used when multiple steps or tools need focused attention. Use when the task requires the entire screen and shouldn’t be interrupted."
     },
     {
       "type": "guideline",
-      "content": "Header content overflow.\n\nTakeover dialogs can optionally include additional elements in the header custom content area. When horizontal space is limited, the header custom content will be displayed underneath the title."
+      "content": "The takeover dialog supports two slots—one in the header and one in the body—where other components can be inserted."
     },
     {
       "type": "guideline",
-      "content": "Use similar language for dialog titles and actions.\n\nMost dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is \"Delete conversation,\" the primary action button label should be \"Delete."
+      "content": "Takeover dialogs support two layout variants: dialog and full-screen."
+    },
+    {
+      "type": "guideline",
+      "content": "All takeover dialogs must include a title. The title appears at the top of the dialog and should briefly describe the expected outcome if the user proceeds with the primary action."
+    },
+    {
+      "type": "guideline",
+      "content": "A takeover 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 taking action, progressing through a workflow, or dismissing the dialog."
+    },
+    {
+      "type": "guideline",
+      "content": "Takeover 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."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, a takeover dialog that includes a button to cancel or go back will be labeled “Cancel.”"
+    },
+    {
+      "type": "guideline",
+      "content": "When the title is too long for the available horizontal space, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "Takeover dialogs can optionally include additional elements in the header custom content area. When horizontal space is limited, the header custom content will be displayed underneath the title."
+    },
+    {
+      "type": "guideline",
+      "content": "Most dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is “Delete conversation,” the primary action button label should be “Delete.”"
     }
   ],
   "options": {
-    "title": { "type": "string" },
-    "description": { "type": "string" },
+    "title": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
     "variant": {
       "type": "string",
       "default": "dialog",
-      "values": [{ "value": "dialog" }, { "value": "full screen" }]
+      "values": [
+        {
+          "value": "dialog"
+        },
+        {
+          "value": "full screen"
+        }
+      ]
+    },
+    "primaryActionLabel": {
+      "type": "string"
     },
-    "primaryActionLabel": { "type": "string" },
     "secondaryActionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
@@ -64,15 +105,25 @@
       }
     }
   },
-  "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"
+      }
     ]
   }
 }