@adobe/spectrum-design-data 0.4.0 → 0.6.0

package/components/segmented-control.json

@@ -9,18 +9,81 @@
     "category": "navigation",
     "documentationUrl": "https://spectrum.adobe.com/page/segmented-control/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Segmented controls allow users to select one option from a set of mutually exclusive options."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls display a group of buttons where only one can be selected at a time. They're ideal for toggling between layouts like a list, grid, or map. Avoid using them for navigation or triggering actions."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls should have between two and five items."
+    },
+    {
+      "type": "guideline",
+      "content": "The identifier of the currently selected item."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, segmented controls should include a track. The track style is justified within the parent container. Segmented controls without a track are left-aligned in left-to-right (LTR) languages."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls without a track are left aligned in left-to-right languages."
+    },
+    {
+      "type": "guideline",
+      "content": "If true, the control takes up the full width of its container. Only horizontal segmented controls support fluid behavior."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls can be either horizontal or vertical. By default, segmented controls are horizontal."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls have one item selected by default at all times, and are mutually exclusive. This means selecting one item automatically deselects the others."
+    },
+    {
+      "type": "guideline",
+      "content": "Clicking on a segmented control item immediately performs the view change."
+    },
+    {
+      "type": "guideline",
+      "content": "When the segmented control item text is too long for the available horizontal space, it truncates at the end. The full text should be revealed with a tooltip on hover."
+    },
+    {
+      "type": "guideline",
+      "content": "Icon-only or truncated label segmented controls can be hard to identify. They should display a tooltip after a brief hover, showing the name and a keyboard shortcut, if applicable."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented controls are only meant to be used to change the way you view information on a page. They should not be used for navigating, filtering content, or taking actions."
+    },
+    {
+      "type": "guideline",
+      "content": "Use a segmented control when the primary goal is to switch views of content. Tabs are reserved for navigation. Action groups are for triggering actions. Tag groups are for filtering content."
+    },
+    {
+      "type": "guideline",
+      "content": "It may not make sense in every case to include icons. If the items are too complicated to convey in an icon, don’t force it. Keep in mind that if one segmented control has an icon, then they all should have an icon."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented control groups work best with 2 to 5 items. If your component needs more than 5 items, consider using a dropdown or radio button group instead."
+    },
+    {
+      "type": "guideline",
+      "content": "Segmented control groups are meant for switching views on a page. To navigate to a different page or progressively disclose different content, use tabs instead. To perform actions or make a selection, use action groups."
+    }
+  ],
   "options": {
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     },
     "isFluid": {
       "type": "boolean",
@@ -30,14 +93,7 @@
     "alignment": {
       "type": "string",
       "default": "start",
-      "values": [
-        {
-          "value": "start"
-        },
-        {
-          "value": "center"
-        }
-      ]
+      "values": [{ "value": "start" }, { "value": "center" }]
     },
     "hideTracker": {
       "type": "boolean",
@@ -51,14 +107,7 @@
     "keyboardActivation": {
       "type": "string",
       "default": "manual",
-      "values": [
-        {
-          "value": "manual"
-        },
-        {
-          "value": "automatic"
-        }
-      ]
+      "values": [{ "value": "manual" }, { "value": "automatic" }]
     },
     "items": {
       "type": "array",
@@ -91,30 +140,16 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "segmented-control-item-height",
-      "context": "Height "
-    },
-    {
-      "token": "corner-radius-medium-default",
-      "context": "Corner radius"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon "
-    },
+    { "token": "segmented-control-item-height", "context": "Height " },
+    { "token": "corner-radius-medium-default", "context": "Corner radius" },
+    { "token": "workflow-icon-size-100", "context": "Icon " },
     {
       "token": "component-edge-to-visual-only-100",
       "context": "Spacing (top/bottom to edge, workflow icon only)"
     },
-    {
-      "token": "text-to-visual-100",
-      "context": "Spacing (icon to label)"
-    },
+    { "token": "text-to-visual-100", "context": "Spacing (icon to label)" },
     {
       "token": "component-edge-to-visual-100",
       "context": "Spacing (start/end edges, workflow icon with label)"
@@ -143,22 +178,13 @@
       "token": "spacing-75",
       "context": "Spacing (between segmented control items)"
     },
-    {
-      "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": "segmented-control-selection-border-width",
       "context": "Selection border"
     },
-    {
-      "token": "gray-600",
-      "context": "Segmented control items (no track)"
-    },
+    { "token": "gray-600", "context": "Segmented control items (no track)" },
     {
       "token": "neutral-subdued-content-color-hover",
       "context": "Segmented control items (no track)"
@@ -179,70 +205,29 @@
       "token": "neutral-content-color-key-focus",
       "context": "Segmented control items (no track)"
     },
-    {
-      "token": "gray-200",
-      "context": "Segmented control items (no track)"
-    },
+    { "token": "gray-200", "context": "Segmented control items (no track)" },
     {
       "token": "neutral-subdued-content-color-default",
       "context": "Segmented control items (with track)"
     },
-    {
-      "token": "gray-25",
-      "context": "Segmented control items (with track)"
-    },
-    {
-      "token": "gray-100",
-      "context": "Segmented control items (with track)"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Label"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Label"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Label"
-    }
+    { "token": "gray-25", "context": "Segmented control items (with track)" },
+    { "token": "gray-100", "context": "Segmented control items (with track)" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "disabled-background-color", "context": "Disabled" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "default-font-family", "context": "Label" },
+    { "token": "default-font-style", "context": "Label" },
+    { "token": "regular-font-weight", "context": "Label" },
+    { "token": "font-size-100", "context": "Label" },
+    { "token": "line-height-100", "context": "Label" }
   ],
   "accessibility": {
     "intents": ["choose"],
     "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/select-box.json

@@ -4,68 +4,109 @@
   "specVersion": "1.0.0-draft",
   "name": "select-box",
   "displayName": "Select box",
+  "description": "Select boxes allow users to choose options in a workflow.",
   "meta": {
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/select-box/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Select boxes allow users to choose options in a workflow."
     },
-    "orientation": {
-      "type": "string",
-      "default": "vertical",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
-    },
-    "body": {
-      "type": "string"
-    },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "Select boxes allow users to choose options in a workflow. Both single-select and multi-select versions use checkboxes to show selection. Multi-select boxes display unchecked checkboxes by default to signal that multiple choices are allowed. Single-select boxes only show an unchecked checkbox on hover. If showCheckbox is false, selection is only shown using the dark border."
     },
-    "hideIllustration": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "A select box in a disabled state shows that the items within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an option may become available later. Individual boxes may be disabled or the entire group may be disabled."
     },
-    "showCheckbox": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "Illustrations are optional but recommended and included by default."
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "A label is required in select boxes. It acts as the title of the select box and explains its action or purpose.. Ideally, the label should be kept concise, even in the horizontal orientation."
+    },
+    {
+      "type": "guideline",
+      "content": "Body is optional in select boxes. If no value is entered for the body, then it will not appear in the component. Body is usually reserved for the horizontal version of select boxes."
+    },
+    {
+      "type": "guideline",
+      "content": "A select box is vertical by default, which works best when metadata is limited to a short title, with or without an illustration. The horizontal orientation is recommended when the select box includes longer-form metadata."
+    },
+    {
+      "type": "guideline",
+      "content": "Minimum and maximum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts."
+    },
+    {
+      "type": "guideline",
+      "content": "All select boxes should be the same size as one another. Keep metadata concise, and make the size of the box large enough to accommodate longer text when translated to other languages."
+    },
+    {
+      "type": "guideline",
+      "content": "When the title of the select box is too long for the available horizontal space, it wraps to another line. Wrapped text should not affect the size of an individual select box. Each box in a group should have enough space to allow for longer, localized text to fit as necessary."
     },
-    "multiple": {
-      "type": "boolean",
-      "default": false,
-      "description": "Set to true to allow multiple selections."
-    }
-  },
-  "states": [
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Clicking a select box does not immediately move to the next step in the sequence. After making a selection, the user must initiate the next step by choosing a button or similar component outside the select box group."
     },
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "A select box group can be navigated using a keyboard. The keyboard focus state takes the button’s visual hover state and adds a blue ring to the button in focus."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Illustrations should be used when they help clarify the content. If the items are too complex to represent visually, it may be better to omit them. For consistency, if one select box includes an illustration, all select boxes in the group should include one."
+    },
+    {
+      "type": "guideline",
+      "content": "Select box groups work best with 3 to 9 items. If your experience needs more than 9 items, consider using a dropdown, checkboxes, or radio button group instead."
+    },
+    {
+      "type": "guideline",
+      "content": "Select boxes are used to choose an item from a group. If clicking an item is meant to immediately trigger an action, use an action group instead."
+    },
+    {
+      "type": "guideline",
+      "content": "All select boxes in a group should be the same size to maintain visual consistency and usability."
+    },
+    {
+      "type": "guideline",
+      "content": "Select boxes use a checkbox to indicate both single- and multi-selection. Don’t use radio buttons for single-selection."
+    },
+    {
+      "type": "guideline",
+      "content": "Some cases may make more sense for the user to select one or a few options in a group of select boxes, but if the use case doesn’t make sense to be checking a selection, showCheckbox can be false and the highlight style can be used instead. There is no visual differentiation between single- and multi-select behaviors when checkboxes are not present."
     }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+  "options": {
+    "label": { "type": "string" },
+    "orientation": {
+      "type": "string",
+      "default": "vertical",
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
+    },
+    "body": { "type": "string" },
+    "isSelected": { "type": "boolean", "default": false },
+    "hideIllustration": { "type": "boolean", "default": false },
+    "showCheckbox": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false },
+    "multiple": {
+      "type": "boolean",
+      "default": false,
+      "description": "Set to true to allow multiple selections."
+    }
   },
+  "states": [
+    { "name": "down", "trigger": "interaction" },
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
     {
       "token": "select-box-vertical-height",
@@ -111,162 +152,61 @@
       "token": "select-box-horizontal-illustration-to-label",
       "context": "Spacing (illustration to label, horizontal)"
     },
-    {
-      "token": "border-width-200",
-      "context": "Border (Selected)"
-    },
-    {
-      "token": "component-size-difference-down",
-      "context": "Down state"
-    },
-    {
-      "token": "component-size-width-ratio-down",
-      "context": "Down state"
-    },
+    { "token": "border-width-200", "context": "Border (Selected)" },
+    { "token": "component-size-difference-down", "context": "Down state" },
+    { "token": "component-size-width-ratio-down", "context": "Down state" },
     {
       "token": "component-size-minimum-perspective-down",
       "context": "Down state"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Border (Selected)"
-    },
-    {
-      "token": "corner-radius-700",
-      "context": "Border radius"
-    },
+    { "token": "focus-indicator-thickness", "context": "Border (Selected)" },
+    { "token": "corner-radius-700", "context": "Border radius" },
     {
       "token": "select-box-edge-to-checkbox",
       "context": "Spacing (top/side edge to checkbox)"
     },
-    {
-      "token": "default-font-family",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Text (vertical)"
-    },
-    {
-      "token": "bold-font-weight",
-      "context": "Text (horizontal)"
-    },
-    {
-      "token": "background-layer-2-color",
-      "context": "Background"
-    },
+    { "token": "default-font-family", "context": "Text (vertical)" },
+    { "token": "regular-font-weight", "context": "Text (vertical)" },
+    { "token": "default-font-style", "context": "Text (vertical)" },
+    { "token": "font-size-100", "context": "Text (vertical)" },
+    { "token": "line-height-100", "context": "Text (vertical)" },
+    { "token": "cjk-line-height-100", "context": "Text (vertical)" },
+    { "token": "bold-font-weight", "context": "Text (horizontal)" },
+    { "token": "background-layer-2-color", "context": "Background" },
     {
       "token": "neutral-content-color-default",
       "context": "Illustration color"
     },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Illustration color"
-    },
-    {
-      "token": "netural-content-color-focus",
-      "context": "Illustration color"
-    },
+    { "token": "neutral-content-color-hover", "context": "Illustration color" },
+    { "token": "netural-content-color-focus", "context": "Illustration color" },
     {
       "token": "select-box-selected-border-color",
       "context": "Border (selected)"
     },
-    {
-      "token": "gray-900",
-      "context": "Border (selected)"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Border (focus)"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "drop-shadow-emphasized-default-x",
-      "context": "Default"
-    },
-    {
-      "token": "drop-shadow-emphasized-default-y",
-      "context": "Default"
-    },
-    {
-      "token": "drop-shadow-emphasized-default-blur",
-      "context": "Default"
-    },
-    {
-      "token": "drop-shadow-emphasized-default-color",
-      "context": "Default"
-    },
-    {
-      "token": "drop-shadow-emphasized-hover-x",
-      "context": "Hover"
-    },
-    {
-      "token": "drop-shadow-emphasized-hover-y",
-      "context": "Hover"
-    },
-    {
-      "token": "drop-shadow-emphasized-hover-blur",
-      "context": "Hover"
-    },
-    {
-      "token": "drop-shadow-emphasized-hover-color",
-      "context": "Hover"
-    },
-    {
-      "token": "drop-shadow-elevated-x",
-      "context": "Focus"
-    },
-    {
-      "token": "drop-shadow-elevated-y",
-      "context": "Focus"
-    },
-    {
-      "token": "drop-shadow-elevated-blur",
-      "context": "Focus"
-    },
-    {
-      "token": "drop-shadow-elevated-color",
-      "context": "Focus"
-    }
+    { "token": "gray-900", "context": "Border (selected)" },
+    { "token": "focus-indicator-color", "context": "Border (focus)" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "disabled-background-color", "context": "Disabled" },
+    { "token": "drop-shadow-emphasized-default-x", "context": "Default" },
+    { "token": "drop-shadow-emphasized-default-y", "context": "Default" },
+    { "token": "drop-shadow-emphasized-default-blur", "context": "Default" },
+    { "token": "drop-shadow-emphasized-default-color", "context": "Default" },
+    { "token": "drop-shadow-emphasized-hover-x", "context": "Hover" },
+    { "token": "drop-shadow-emphasized-hover-y", "context": "Hover" },
+    { "token": "drop-shadow-emphasized-hover-blur", "context": "Hover" },
+    { "token": "drop-shadow-emphasized-hover-color", "context": "Hover" },
+    { "token": "drop-shadow-elevated-x", "context": "Focus" },
+    { "token": "drop-shadow-elevated-y", "context": "Focus" },
+    { "token": "drop-shadow-elevated-blur", "context": "Focus" },
+    { "token": "drop-shadow-elevated-color", "context": "Focus" }
   ],
   "accessibility": {
     "intents": ["select"],
     "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" }
     ]
   }
 }