@adobe/spectrum-design-data 0.3.0 → 0.6.0

package/components/checkbox-group.json

@@ -9,83 +9,75 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/checkbox-group/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "A checkbox group is a grouping of checkboxes that are related to each other."
+    },
+    {
+      "type": "guideline",
+      "content": "When a description is present and an error is triggered, it is replaced with an error message. Once the error is resolved, the help text description reappears."
+    },
+    {
+      "type": "guideline",
+      "content": "A checkbox group in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. The field label, checkboxes, and help text are all displayed in a disabled state when the checkbox group is disabled."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkbox groups can be either horizontal or vertical. By default, checkbox groups are stacked vertically. Use a horizontal checkbox group when vertical space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkbox groups can be marked as optional or required, depending on the situation. Optional checkbox groups are either denoted with text added to the end of the label — “(optional)” — or have no indication at all."
+    },
+    {
+      "type": "guideline",
+      "content": "For required checkbox groups, there are two necessity indicator options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means."
+    },
+    {
+      "type": "guideline",
+      "content": "The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself."
+    },
+    {
+      "type": "guideline",
+      "content": "Labels can be placed either on top or on the side. 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": "Checkbox groups should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These checkbox groups without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
     "labelPosition": {
       "type": "string",
       "default": "top",
-      "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "side"
-        }
-      ]
+      "values": [{ "value": "top" }, { "value": "side" }]
     },
     "necessityIndicator": {
       "type": "string",
       "default": "icon",
-      "values": [
-        {
-          "value": "text"
-        },
-        {
-          "value": "icon"
-        }
-      ]
-    },
-    "isRequired": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "text" }, { "value": "icon" }]
     },
+    "isRequired": { "type": "boolean", "default": false },
     "orientation": {
       "type": "string",
       "default": "vertical",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
-    },
-    "isError": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "description": {
-      "type": "string"
-    },
-    "errorMessage": {
-      "type": "string"
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "isError": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false },
+    "description": { "type": "string" },
+    "errorMessage": { "type": "string" }
   },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [],
   "accessibility": {
     "intents": ["choose"],
     "focusable": false,
     "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/checkbox.json

@@ -9,15 +9,86 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/checkbox/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes support selecting one or more items from a list. Each item can be selected independently or in combination with others."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes can be marked as having an error to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. For example, in a form that requires a user to acknowledge legal terms before proceeding, the checkbox would show an unchecked error to communicate that it needs to be selected."
+    },
+    {
+      "type": "guideline",
+      "content": "A checkbox in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, checkboxes are not emphasized (gray). This version is optimal for when the checkbox 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."
+    },
+    {
+      "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 checkbox need to be noticed."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes 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": "Checkboxes can be in an indeterminate state when they represent both selected and not selected values."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes can be selected or not selected."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes should always have a label. When the label is not defined, a checkbox becomes standalone. Standalone checkboxes are only used when their connection to other components is clear and they give sufficient context — for example, in application panels."
+    },
+    {
+      "type": "guideline",
+      "content": "A checkbox can be navigated using a keyboard. The keyboard focus state takes the checkbox’s visual hover state and adds a blue ring to the checkbox in focus."
+    },
+    {
+      "type": "guideline",
+      "content": "When the label is too long for the horizontal space available, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "Emphasized checkboxes are optimal for forms, settings, etc. where the checkboxes need to be noticed, or to bring attention to selected items such as cards or table rows. Not emphasized checkboxes are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
+    },
+    {
+      "type": "guideline",
+      "content": "Standalone checkboxes should be used in situations where the context is clear without an associated text label. An example of this would be when a checkbox is connected to other controls inside of a panel."
+    },
+    {
+      "type": "guideline",
+      "content": "Checkboxes and radio buttons are not interchangeable. A set of checkboxes should be used to select as many options as desired (or none). A set of radio buttons should be used to select only a single option from a list of mutually exclusive options."
+    },
+    {
+      "type": "guideline",
+      "content": "Use checkboxes to show selection, such as choosing multiple table rows. Use switches to show activation, like turning a setting on or off. Unlike switches, checkboxes can display an error state."
+    },
+    {
+      "type": "guideline",
+      "content": "Sets of checkboxes should always have a clear label that describes what the list of options represents and guides users what to do. This is important for accessibility, since a screen reader will read the label before each option."
+    },
+    {
+      "type": "guideline",
+      "content": "When a checkbox represents multiple values that are not identical, the checkbox should appear in the indeterminate state. Any subsequent click or tap should select the checkbox, and update all values to be selected. Another click or tap after that should deselect the checkbox, and update all values to be not selected."
+    }
+  ],
   "options": {
     "label": {
       "type": "string",
       "description": "When the label is not defined, the checkbox appears as a standalone checkbox."
     },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
-    },
+    "isSelected": { "type": "boolean", "default": false },
     "isIndeterminate": {
       "type": "boolean",
       "default": false,
@@ -27,63 +98,26 @@
       "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
-    },
-    "isError": {
-      "type": "boolean",
-      "default": false
-    }
+    "isEmphasized": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isError": { "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": "checkbox-control-size-small",
-      "context": "S2 Control (size)"
-    },
-    {
-      "token": "checkbox-control-size-medium",
-      "context": "S2 Control (size)"
-    },
-    {
-      "token": "checkbox-control-size-large",
-      "context": "S2 Control (size)"
-    },
+    { "token": "checkbox-control-size-small", "context": "S2 Control (size)" },
+    { "token": "checkbox-control-size-medium", "context": "S2 Control (size)" },
+    { "token": "checkbox-control-size-large", "context": "S2 Control (size)" },
     {
       "token": "checkbox-control-size-extra-large",
       "context": "S2 Control (size)"
@@ -116,22 +150,10 @@
       "token": "neutral-background-color-selected-key-focus",
       "context": "S2 Control (selected, non emphasized)"
     },
-    {
-      "token": "component-height-75",
-      "context": "Minimum height"
-    },
-    {
-      "token": "component-height-100",
-      "context": "Minimum height"
-    },
-    {
-      "token": "component-height-200",
-      "context": "Minimum height"
-    },
-    {
-      "token": "component-height-300",
-      "context": "Minimum height"
-    },
+    { "token": "component-height-75", "context": "Minimum height" },
+    { "token": "component-height-100", "context": "Minimum height" },
+    { "token": "component-height-200", "context": "Minimum height" },
+    { "token": "component-height-300", "context": "Minimum height" },
     {
       "token": "component-size-difference-down",
       "context": "Component size (down)"
@@ -144,10 +166,7 @@
       "token": "component-size-minimum-perspective-down",
       "context": "Component size (down)"
     },
-    {
-      "token": "border-width-200",
-      "context": "Control (border)"
-    },
+    { "token": "border-width-200", "context": "Control (border)" },
     {
       "token": "corner-radius-small-size-small",
       "context": "Control (rounding)"
@@ -164,22 +183,10 @@
       "token": "corner-radius-small-size-extra-large",
       "context": "Control (rounding)"
     },
-    {
-      "token": "text-to-control-75",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-100",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-200",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-300",
-      "context": "Spacing (control to label)"
-    },
+    { "token": "text-to-control-75", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-100", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-200", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-300", "context": "Spacing (control to label)" },
     {
       "token": "component-top-to-text-75",
       "context": "Spacing (top/bottom edge to label)"
@@ -212,38 +219,17 @@
       "token": "component-bottom-to-text-300",
       "context": "Spacing (top/bottom 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": "spacing-300",
       "context": "Checkbox group spacing (horizontal)"
     },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-down",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-key-focus",
-      "context": "Label"
-    },
-    {
-      "token": "gray-25",
-      "context": "Control"
-    },
+    { "token": "neutral-content-color-default", "context": "Label" },
+    { "token": "neutral-content-color-hover", "context": "Label" },
+    { "token": "neutral-content-color-down", "context": "Label" },
+    { "token": "neutral-content-color-key-focus", "context": "Label" },
+    { "token": "gray-25", "context": "Control" },
     {
       "token": "accent-content-color-default",
       "context": "Control (selected, emphasized)"
@@ -260,58 +246,19 @@
       "token": "accent-content-color-key-focus",
       "context": "Control (selected, emphasized)"
     },
-    {
-      "token": "disabled-content-color",
-      "context": "Label (disabled)"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "negative-color-900",
-      "context": "Checkbox colors"
-    },
-    {
-      "token": "negative-color-1000",
-      "context": "Checkbox colors"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Label"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Label"
-    },
-    {
-      "token": "default-font-style",
-      "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": "disabled-content-color", "context": "Label (disabled)" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "negative-color-900", "context": "Checkbox colors" },
+    { "token": "negative-color-1000", "context": "Checkbox colors" },
+    { "token": "default-font-family", "context": "Label" },
+    { "token": "regular-font-weight", "context": "Label" },
+    { "token": "default-font-style", "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" }
   ],
   "accessibility": {
     "role": "checkbox",
@@ -319,21 +266,9 @@
     "focusable": true,
     "keyboardIntents": ["activate"],
     "wcag": [
-      {
-        "criterion": "1.3.1",
-        "level": "A",
-        "title": "Info and Relationships"
-      },
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }