@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/tabs.json

@@ -9,18 +9,61 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/tabs/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Tabs organize content into multiple sections and allow users to navigate between them. The content under the set of tabs should be related and form a coherent unit."
+    },
+    {
+      "type": "guideline",
+      "content": "Tabs organize related content into multiple sections. They allow navigation between views while keeping the content grouped under a single context. Use when content can be divided logically into categories within the same view."
+    },
+    {
+      "type": "guideline",
+      "content": "Tabs can be horizontal or vertical. By default, tabs are horizontal and should be used when horizontal space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "Use vertical tabs when horizontal space is more generous or when the list of sections is too long for a horizontal layout. Vertical tabs can also serve as anchor links, providing shortcuts to sections on a single page. In this case, tab items link to on-page anchors rather than opening a new tab view."
+    },
+    {
+      "type": "guideline",
+      "content": "When a user selects a tab item, the selection indicator slides along the base to the newly selected tab. The text and icon colors of both tabs fade during the transition. The tab view changes immediately upon selection."
+    },
+    {
+      "type": "guideline",
+      "content": "When there are too many tabs to fit horizontally across the viewport, display the tabs component as a quiet picker. When appropriate, you can also use alternative overflow methods such as horizontal scrolling."
+    },
+    {
+      "type": "guideline",
+      "content": "When there are too many tabs to fit horizontally across the viewport, you can either allow horizontal scrolling or place all tab items in a quiet picker. Do not truncate multiple tab items just to make them fit horizontally."
+    },
+    {
+      "type": "guideline",
+      "content": "Use tabs to organize sections of equal importance. Groups of content under each tab item should not be of different natures. Don't use tabs to replace a flow; use pagination components instead."
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid using multiple levels of tabs. Instead, consider other organizational patterns such as side navigation, accordions or collapsible panels. Nesting tabs is acceptable only when there is a clear separation between the two tab experiences or when different orientations are used."
+    },
+    {
+      "type": "guideline",
+      "content": "Do not compromise hierarchy by using the same tab variations or orientations."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t mix the use of icons in tabs. Navigation controls require a clear spacial relationship to one another, and mixing the use of icons can dramatically impact the visual balance and presence for each tab item. Keep in mind that if one tab item has an icon, then they all should have an icon."
+    },
+    {
+      "type": "guideline",
+      "content": "It can often be hard to identify the meaning of icon-only tabs. An icon-only tab should always show a tooltip displaying the label on hover."
+    }
+  ],
   "options": {
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     },
     "items": {
       "type": "array",
@@ -59,18 +102,13 @@
             "default": false,
             "description": "This overrides density and is only applicable to horizontal tabs."
           },
-          "isEmphasized": {
-            "type": "boolean",
-            "default": false
-          },
+          "isEmphasized": { "type": "boolean", "default": false },
           "alignment": {
             "type": "string",
             "enum": ["start", "center"],
             "default": "start"
           },
-          "selectedItem": {
-            "description": "(list of available items)"
-          },
+          "selectedItem": { "description": "(list of available items)" },
           "keyboardActivation": {
             "type": "string",
             "enum": ["manual", "automatic"],
@@ -80,30 +118,13 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "tab-item-compact-height-medium",
-      "context": "Height "
-    },
-    {
-      "token": "tab-item-height-medium",
-      "context": "Regular density "
-    },
-    {
-      "token": "corner-radius-0",
-      "context": "Corner radius"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon "
-    },
-    {
-      "token": "text-to-visual-100",
-      "context": "Spacing (icon to label)"
-    },
+    { "token": "tab-item-compact-height-medium", "context": "Height " },
+    { "token": "tab-item-height-medium", "context": "Regular density " },
+    { "token": "corner-radius-0", "context": "Corner radius" },
+    { "token": "workflow-icon-size-100", "context": "Icon " },
+    { "token": "text-to-visual-100", "context": "Spacing (icon to label)" },
     {
       "token": "tab-item-top-to-workflow-icon-compact-medium",
       "context": "Spacing (top/bottom to edge, workflow icon only)"
@@ -120,10 +141,7 @@
       "token": "tab-item-side-to-workflow-icon-medium",
       "context": "Spacing (side to edge, workflow icon only)"
     },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (edge to edge)"
-    },
+    { "token": "spacing-100", "context": "Spacing (edge to edge)" },
     {
       "token": "tab-item-top-to-text-compact-medium",
       "context": "Spacing (top edge to label)"
@@ -148,26 +166,14 @@
       "token": "tab-item-to-tab-item-horizontal-medium",
       "context": "Spacing (between tab items, horizontal)"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus ring"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus ring"
-    },
+    { "token": "focus-indicator-thickness", "context": "Focus ring" },
+    { "token": "focus-indicator-gap", "context": "Focus ring" },
     {
       "token": "tab-selection-indicator-thickness",
       "context": "Selection indicator (underline)"
     },
-    {
-      "token": "spacing-75",
-      "context": "Spacing (selected) "
-    },
-    {
-      "token": "spacing-200",
-      "context": "Spacing (selected) "
-    },
+    { "token": "spacing-75", "context": "Spacing (selected) " },
+    { "token": "spacing-200", "context": "Spacing (selected) " },
     {
       "token": "spacing-50",
       "context": "Spacing (selected with keyboard focus) "
@@ -196,58 +202,25 @@
       "token": "neutral-subdued-content-color-key-focus",
       "context": "Tab items and selection indicator"
     },
-    {
-      "token": "disabled-border-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "default-font-family"
-    },
-    {
-      "token": "default-font-style"
-    },
-    {
-      "token": "regular-font-weight"
-    },
-    {
-      "token": "font-size-75"
-    },
-    {
-      "token": "font-size-100"
-    },
-    {
-      "token": "font-size-200"
-    },
-    {
-      "token": "font-size-300"
-    },
-    {
-      "token": "line-height-100"
-    }
+    { "token": "disabled-border-color", "context": "Disabled" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "default-font-family" },
+    { "token": "default-font-style" },
+    { "token": "regular-font-weight" },
+    { "token": "font-size-75" },
+    { "token": "font-size-100" },
+    { "token": "font-size-200" },
+    { "token": "font-size-300" },
+    { "token": "line-height-100" }
   ],
   "accessibility": {
     "intents": ["navigate"],
     "focusable": true,
     "keyboardIntents": ["navigate-items"],
     "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/tag-field.json

@@ -9,131 +9,111 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/tag-field/"
   },
-  "options": {
-    "size": {
-      "type": "string",
-      "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
-    },
-    "style": {
-      "type": "string",
-      "default": "keyword",
-      "values": [
-        {
-          "value": "keyword"
-        },
-        {
-          "value": "icon"
-        },
-        {
-          "value": "thumbnail"
-        },
-        {
-          "value": "avatar"
-        }
-      ]
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "hideLabel": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "states": [
+  "documentBlocks": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "purpose",
+      "content": "A tag field is an input field that allows users to enter and manage tags."
     },
     {
-      "name": "focus-+-hover",
-      "trigger": "prop"
+      "type": "guideline",
+      "content": "Tag field is an input component for adding and editing multiple tags. It includes standard field label and error options, and is used to capture grouped keywords or descriptors. Tags can be added directly in the field and displayed inline for editing or removal."
     },
     {
-      "name": "focus-+-not-hover",
-      "trigger": "prop"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
-    {
-      "token": "tag-field-default-width-small",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "The label of the tag field 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."
     },
     {
-      "token": "tag-field-default-width-medium",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "A tag field in a disabled state indicates that it exists but is not available in that context. This state helps maintain layout continuity and signals that tagging may become available later."
     },
     {
-      "token": "tag-field-default-width-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "Tag groups within a tag field can include a keyword, icon, thumbnail or avatar. Icons, thumbnails and avatars should also include a keyword."
     },
     {
-      "token": "tag-field-minimum-width",
-      "context": "Width (minimum)"
+      "type": "guideline",
+      "content": "Tag fields 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."
     },
     {
-      "token": "tag-field-minimum-height-small",
-      "context": "Height (minimum)"
+      "type": "guideline",
+      "content": "A flyout/menu appears when the user starts typing to suggest tags that are supported or have already been entered previously."
     },
     {
-      "token": "tag-field-minimum-height-medium",
-      "context": "Height (minimum)"
+      "type": "guideline",
+      "content": "Sometimes tag field can be additive, meaning new tags may be added from this particular tag field. They can also be restricted to only allowing tags that already exist in the system"
     },
     {
-      "token": "tag-field-minimum-height-large",
-      "context": "Height (minimum)"
+      "type": "guideline",
+      "content": "When there are more tags than fit in the horizontal space, tags wrap to another line."
     },
     {
-      "token": "corner-radius-medium-size-small",
-      "context": "Rounding"
+      "type": "guideline",
+      "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."
     },
     {
-      "token": "corner-radius-medium-size-medium",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "If there is space in an experience for the field to grow with the tags, such as at the bottom of a page or dialog, you can use the multi-line option."
     },
     {
-      "token": "corner-radius-medium-size-large",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "If the tag field is located at the top of a header or otherwise constrained space, it is better to use a non-multi-line tag field."
     },
     {
-      "token": "border-width-200",
-      "context": "Border"
+      "type": "guideline",
+      "content": "The default option should be a standard text field with tags displayed below it. You may use a tag field if space is limited, especially when using a single-line tag field. This allows all fields to stay contained within a defined area."
+    }
+  ],
+  "options": {
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus indicator"
+    "style": {
+      "type": "string",
+      "default": "keyword",
+      "values": [
+        { "value": "keyword" },
+        { "value": "icon" },
+        { "value": "thumbnail" },
+        { "value": "avatar" }
+      ]
     },
+    "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" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "tag-field-default-width-small", "context": "Width (default)" },
+    { "token": "tag-field-default-width-medium", "context": "Width (default)" },
+    { "token": "tag-field-default-width-large", "context": "Width (default)" },
+    { "token": "tag-field-minimum-width", "context": "Width (minimum)" },
     {
-      "token": "workflow-icon-size-75",
-      "context": "Alert icon"
+      "token": "tag-field-minimum-height-small",
+      "context": "Height (minimum)"
     },
     {
-      "token": "workflow-icon-size-100",
-      "context": "Alert icon"
+      "token": "tag-field-minimum-height-medium",
+      "context": "Height (minimum)"
     },
     {
-      "token": "workflow-icon-size-200",
-      "context": "Alert icon"
+      "token": "tag-field-minimum-height-large",
+      "context": "Height (minimum)"
     },
+    { "token": "corner-radius-medium-size-small", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-medium", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-large", "context": "Rounding" },
+    { "token": "border-width-200", "context": "Border" },
+    { "token": "focus-indicator-thickness", "context": "Focus indicator" },
+    { "token": "workflow-icon-size-75", "context": "Alert icon" },
+    { "token": "workflow-icon-size-100", "context": "Alert icon" },
+    { "token": "workflow-icon-size-200", "context": "Alert icon" },
     {
       "token": "field-edge-to-alert-icon-small",
       "context": "Spacing (top/bottom edge to alert icon)"
@@ -170,74 +150,30 @@
       "token": "spacing-200",
       "context": "Spacing (minimum, field label to field)"
     },
-    {
-      "token": "gray-25",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-300",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-400",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-900",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-800",
-      "context": "Background and border"
-    },
-    {
-      "token": "negative-border-color-default",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-border-color-hover",
-      "context": "Border (error)"
-    },
+    { "token": "gray-25", "context": "Background and border" },
+    { "token": "gray-300", "context": "Background and border" },
+    { "token": "gray-400", "context": "Background and border" },
+    { "token": "gray-900", "context": "Background and border" },
+    { "token": "gray-800", "context": "Background and border" },
+    { "token": "negative-border-color-default", "context": "Border (error)" },
+    { "token": "negative-border-color-hover", "context": "Border (error)" },
     {
       "token": "negative-border-color-focus-hover",
       "context": "Border (error)"
     },
-    {
-      "token": "negative-border-color-focus",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-border-color-key-focus",
-      "context": "Border (error)"
-    },
-    {
-      "token": "negative-visual-color",
-      "context": "Alert icon"
-    },
-    {
-      "token": "disabled-border-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    }
+    { "token": "negative-border-color-focus", "context": "Border (error)" },
+    { "token": "negative-border-color-key-focus", "context": "Border (error)" },
+    { "token": "negative-visual-color", "context": "Alert icon" },
+    { "token": "disabled-border-color", "context": "Disabled" },
+    { "token": "focus-indicator-color", "context": "Focus ring" }
   ],
   "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,55 +9,69 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/tag-group/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "A tag group is a collection of tags that represent a set of related items."
+    },
+    {
+      "type": "guideline",
+      "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": "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": "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": "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": "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": "When horizontal space is limited in a tag group, the individual tags wrap to form another line."
+    },
+    {
+      "type": "guideline",
+      "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": "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"
-        }
-      ]
-    },
-    "hideLabel": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "top" }, { "value": "side" }]
     },
+    "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" },
   "tokenBindings": [
-    {
-      "token": "spacing-100",
-      "context": "Spacing (vertical)"
-    },
-    {
-      "token": "spacing-200",
-      "context": "Spacing (vertical)"
-    },
+    { "token": "spacing-100", "context": "Spacing (vertical)" },
+    { "token": "spacing-200", "context": "Spacing (vertical)" },
     {
       "token": "field-label-to-component",
       "context": "Spacing (Field label to Tags)"
@@ -72,16 +86,8 @@
     "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" }
     ]
   }
 }