@adobe/spectrum-design-data 0.4.0 → 0.6.0

package/components/action-button.json

@@ -9,14 +9,47 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/action-button/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Action buttons perform tasks or mark selections. They're suited for task-based workflows where buttons don't need to draw attention."
+    },
+    {
+      "type": "guideline",
+      "content": "Text overflow.\n\nWhen the action button 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": "Keyboard focus.\n\nAn action button 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."
+    },
+    {
+      "type": "guideline",
+      "content": "Use tooltips.\n\nIcon-only action buttons can be hard to identify. They should always show a tooltip upon hovering for a short period of time, displaying the name and possibly a keyboard shortcut."
+    },
+    {
+      "type": "guideline",
+      "content": "Isolated action buttons.\n\nIf you have an icon-only or text-only isolated action button, use the standard style to make sure it's more easily identifiable as a button."
+    },
+    {
+      "type": "guideline",
+      "content": "Only group related actions with a hold icon.\n\nWhen using a hold icon to switch actions, only group the actions that are part of the same family. Don't group unrelated actions just for the sake of saving space."
+    },
+    {
+      "type": "guideline",
+      "content": "Respect hold icon placement.\n\nIn left-to-right interfaces, the hold icon is always in the bottom right corner of the action button. It's a symbolic indicator that shows that a popover menu will appear on hold. Don't change the placement of the hold icon based on the design of the interface."
     },
-    "hideLabel": {
-      "type": "boolean",
-      "default": false
+    {
+      "type": "guideline",
+      "content": "When to use static black and static white.\n\nTo ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast."
     },
+    {
+      "type": "guideline",
+      "content": "Selected state text color.\n\nThe text color on the selected state of the over-background variant can be customized to match the background it's on. Use the background color for selected text when the action button is on a solid color, and is dark enough to meet a 4.5:1 contrast ratio with a white background (or black background, for the static black variant).\n\nUse black text when the button is on top of an image, or if the background is too low-contrast to meet the 4.5:1 contrast ratio."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
+    "hideLabel": { "type": "boolean", "default": false },
     "icon": {
       "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
       "description": "Icon must be present if the label is not defined."
@@ -25,97 +58,39 @@
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "xs"
-        },
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "xs" },
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
-    "isQuiet": {
-      "type": "boolean",
-      "default": false
-    },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
-    },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
+    "isQuiet": { "type": "boolean", "default": false },
+    "isSelected": { "type": "boolean", "default": false },
+    "isEmphasized": { "type": "boolean", "default": false },
     "staticColor": {
       "type": "string",
       "description": "Static color must not be set for the default version of this component.",
-      "values": [
-        {
-          "value": "white"
-        },
-        {
-          "value": "black"
-        }
-      ]
+      "values": [{ "value": "white" }, { "value": "black" }]
     },
     "selectedTextColor": {
       "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/hex-color.json"
     },
-    "hasHoldIcon": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
+    "hasHoldIcon": { "type": "boolean", "default": false },
+    "isDisabled": { "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" },
   "tokenBindings": [
-    {
-      "token": "component-height-50",
-      "context": "Height"
-    },
-    {
-      "token": "component-height-75",
-      "context": "Height"
-    },
-    {
-      "token": "component-height-100",
-      "context": "Height"
-    },
-    {
-      "token": "component-height-200",
-      "context": "Height"
-    },
-    {
-      "token": "component-height-300",
-      "context": "Height"
-    },
+    { "token": "component-height-50", "context": "Height" },
+    { "token": "component-height-75", "context": "Height" },
+    { "token": "component-height-100", "context": "Height" },
+    { "token": "component-height-200", "context": "Height" },
+    { "token": "component-height-300", "context": "Height" },
     {
       "token": "component-size-difference-down",
       "context": "Component size (down)"
@@ -128,66 +103,21 @@
       "token": "component-size-minimum-perspective-down",
       "context": "Component size (down)"
     },
-    {
-      "token": "corner-radius-medium-size-extra-small",
-      "context": "Rounding"
-    },
-    {
-      "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": "corner-radius-medium-size-extra-large",
-      "context": "Rounding"
-    },
-    {
-      "token": "workflow-icon-size-50",
-      "context": "Icon"
-    },
-    {
-      "token": "workflow-icon-size-75",
-      "context": "Icon"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon"
-    },
-    {
-      "token": "workflow-icon-size-200",
-      "context": "Icon"
-    },
-    {
-      "token": "workflow-icon-size-300",
-      "context": "Icon"
-    },
-    {
-      "token": "text-to-visual-50",
-      "context": "Spacing (icon to label)"
-    },
-    {
-      "token": "text-to-visual-75",
-      "context": "Spacing (icon to label)"
-    },
-    {
-      "token": "text-to-visual-100",
-      "context": "Spacing (icon to label)"
-    },
-    {
-      "token": "text-to-visual-200",
-      "context": "Spacing (icon to label)"
-    },
-    {
-      "token": "text-to-visual-300",
-      "context": "Spacing (icon to label)"
-    },
+    { "token": "corner-radius-medium-size-extra-small", "context": "Rounding" },
+    { "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": "corner-radius-medium-size-extra-large", "context": "Rounding" },
+    { "token": "workflow-icon-size-50", "context": "Icon" },
+    { "token": "workflow-icon-size-75", "context": "Icon" },
+    { "token": "workflow-icon-size-100", "context": "Icon" },
+    { "token": "workflow-icon-size-200", "context": "Icon" },
+    { "token": "workflow-icon-size-300", "context": "Icon" },
+    { "token": "text-to-visual-50", "context": "Spacing (icon to label)" },
+    { "token": "text-to-visual-75", "context": "Spacing (icon to label)" },
+    { "token": "text-to-visual-100", "context": "Spacing (icon to label)" },
+    { "token": "text-to-visual-200", "context": "Spacing (icon to label)" },
+    { "token": "text-to-visual-300", "context": "Spacing (icon to label)" },
     {
       "token": "component-edge-to-visual-50",
       "context": "Spacing (start/end edges)"
@@ -288,14 +218,8 @@
       "token": "component-top-to-text-300",
       "context": "Spacing (top edge to label)"
     },
-    {
-      "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": "action-button-edge-to-hold-icon-extra-small",
       "context": "Spacing (edge to hold icon)"
@@ -316,54 +240,18 @@
       "token": "action-button-edge-to-hold-icon-extra-large",
       "context": "Spacing (edge to hold icon)"
     },
-    {
-      "token": "default-font-family",
-      "context": "Label"
-    },
-    {
-      "token": "medium-font-weight",
-      "context": "Label"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-50",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-75",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-200",
-      "context": "Label"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "gray-100",
-      "context": "Background "
-    },
-    {
-      "token": "gray-200",
-      "context": "Background "
-    },
+    { "token": "default-font-family", "context": "Label" },
+    { "token": "medium-font-weight", "context": "Label" },
+    { "token": "default-font-style", "context": "Label" },
+    { "token": "font-size-50", "context": "Label" },
+    { "token": "font-size-75", "context": "Label" },
+    { "token": "font-size-100", "context": "Label" },
+    { "token": "font-size-200", "context": "Label" },
+    { "token": "font-size-300", "context": "Label" },
+    { "token": "line-height-100", "context": "Label" },
+    { "token": "cjk-line-height-100", "context": "Label" },
+    { "token": "gray-100", "context": "Background " },
+    { "token": "gray-200", "context": "Background " },
     {
       "token": "neutral-content-color-default",
       "context": "Label, icon, and hold icon"
@@ -428,18 +316,9 @@
       "token": "disabled-content-color",
       "context": "Label, icon, and hold icon (disabled)"
     },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "transparent-white-100",
-      "context": "Background "
-    },
-    {
-      "token": "transparent-white-200",
-      "context": "Background "
-    },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "transparent-white-100", "context": "Background " },
+    { "token": "transparent-white-200", "context": "Background " },
     {
       "token": "transparent-white-800",
       "context": "Label, icon, and hold icon"
@@ -468,14 +347,8 @@
       "token": "static-white-focus-indicator-color",
       "context": "Focus ring (white)"
     },
-    {
-      "token": "transparent-black-100",
-      "context": "Background "
-    },
-    {
-      "token": "transparent-black-200",
-      "context": "Background "
-    },
+    { "token": "transparent-black-100", "context": "Background " },
+    { "token": "transparent-black-200", "context": "Background " },
     {
       "token": "transparent-black-800",
       "context": "Label, icon, and hold icon"
@@ -507,16 +380,8 @@
     "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/action-group.json

@@ -9,77 +9,106 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/action-group/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "An action group is a grouping of action buttons that are related to each other."
+    },
+    {
+      "type": "guideline",
+      "content": "An action group in a disabled state shows that the action buttons 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 action group may become available later."
+    },
+    {
+      "type": "guideline",
+      "content": "When selection is enabled, an action group's selection behavior can be set to allow for an empty selection, or not."
+    },
+    {
+      "type": "guideline",
+      "content": "When selection is enabled, an action group can allow for single or multiple selection of action buttons."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, selection is not enabled in an action group. This is used for action groups that offer direct actions, rather than toggling."
+    },
+    {
+      "type": "guideline",
+      "content": "Selection can be enabled for an action group to allow for toggling. This can be used to disclose parts of an interface (for example, showing or hiding panels) or to switch between views (for example, grid or list views)."
+    },
+    {
+      "type": "guideline",
+      "content": "Like action buttons, action groups are not emphasized by default. This is optimal for when the action group is not the core part of an interface, such as in application panels, where all components are monochrome in order to direct focus to the content."
+    },
+    {
+      "type": "guideline",
+      "content": "The emphasized action group has a blue background for its selected state in order to provide a visual prominence that meets the accessible color contrast ratio. This is optimal for when the selection should call attention, such as within a tool bar."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, an action group uses not-quiet action buttons. This style works best in a dense array of controls where the background helps to separate action buttons from the surrounding container, or to give visibility to isolated buttons."
+    },
+    {
+      "type": "guideline",
+      "content": "Alternatively, quiet action groups can have no visible background until they’re interacted with. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read."
+    },
+    {
+      "type": "guideline",
+      "content": "An action group can become justified. By default, it is not justified since the action button size depends on the label and/or icon inside each button. When an action group is justified, it takes up the entire available container width, divided equally for each action button that is inside the group."
+    },
+    {
+      "type": "guideline",
+      "content": "Action groups come in two densities: regular and compact. The compact density retains the same font and icon sizes, but has tighter spacing. The action buttons also become connected for non-quiet action groups."
+    },
+    {
+      "type": "guideline",
+      "content": "Action groups come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
+    },
+    {
+      "type": "guideline",
+      "content": "An action group can be either horizontal or vertical in its orientation. By default, an action group is horizontal. The vertical option should be reserved for when horizontal space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "When there are more actions than the action group has horizontal space for, overflowMode collapse will use an Action menu to contain additional actions. This is used in the components like action bar or panels to show an array of actions to select from when horizontal space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "When multiple items can be selected at a time use an action group when taking actions or making choices from a list of options. Action group is the preferred competent to use when those actions are simple (1-2 words or icon only). If you are switching views or navigating to different content, a segmented control is the preferred component."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the fully justified variant when using the vertical compact action group (both the quiet and not quiet options). This will ensure the buttons have the same width."
+    }
+  ],
   "options": {
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
     "density": {
       "type": "string",
       "default": "regular",
-      "values": [
-        {
-          "value": "regular"
-        },
-        {
-          "value": "compact"
-        }
-      ]
-    },
-    "isJustified": {
-      "type": "boolean",
-      "default": false
-    },
-    "isQuiet": {
-      "type": "boolean",
-      "default": false
-    },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
-    "enableSelection": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "regular" }, { "value": "compact" }]
     },
+    "isJustified": { "type": "boolean", "default": false },
+    "isQuiet": { "type": "boolean", "default": false },
+    "isEmphasized": { "type": "boolean", "default": false },
+    "enableSelection": { "type": "boolean", "default": false },
     "selectionMode": {
       "type": "string",
       "default": "single",
       "description": "Only applicable if selection is enabled",
-      "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "multiple"
-        }
-      ]
+      "values": [{ "value": "single" }, { "value": "multiple" }]
     },
     "allowsEmptySelection": {
       "type": "boolean",
@@ -89,46 +118,19 @@
     "overflowMode": {
       "type": "string",
       "default": "wrap",
-      "values": [
-        {
-          "value": "wrap"
-        },
-        {
-          "value": "collapse"
-        }
-      ]
+      "values": [{ "value": "wrap" }, { "value": "collapse" }]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "isDisabled": { "type": "boolean", "default": false }
   },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "spacing-75",
-      "context": "Spacing (horizontal, regular)"
-    },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (horizontal, regular)"
-    },
-    {
-      "token": "spacing-50",
-      "context": "Spacing (horizontal, compact)"
-    }
+    { "token": "spacing-75", "context": "Spacing (horizontal, regular)" },
+    { "token": "spacing-100", "context": "Spacing (horizontal, regular)" },
+    { "token": "spacing-50", "context": "Spacing (horizontal, compact)" }
   ],
   "accessibility": {
     "intents": ["trigger"],
     "focusable": false,
-    "wcag": [
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      }
-    ]
+    "wcag": [{ "criterion": "2.1.1", "level": "A", "title": "Keyboard" }]
   }
 }