@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/drop-zone.json

@@ -9,6 +9,36 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/drop-zone/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "A drop zone allows users to drag and drop files or other content into a designated area."
+    },
+    {
+      "type": "guideline",
+      "content": "Drop zones accept dragged and dropped objects. They support upload and file management workflows, and are commonly used to move or add content within an interface."
+    },
+    {
+      "type": "guideline",
+      "content": "A button is an optional element to prompt the user to take action."
+    },
+    {
+      "type": "guideline",
+      "content": "Drop zones come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option."
+    },
+    {
+      "type": "guideline",
+      "content": "Indicate to users the accepted file types to let users know what they can upload before interacting. This can be done through helper text or placeholder content."
+    },
+    {
+      "type": "guideline",
+      "content": "When a file is dragged over or dropped into the zone, provide the user with visual feedback such as highlighting the border or changing the background, to confirm the interaction is recognized."
+    },
+    {
+      "type": "guideline",
+      "content": "Visual styling that indicates a user can replace file types within a dropzone should clearly communicate interactivity and the potential for change without disrupting the overall layout. This is typically achieved through subtle but intuitive cues such as displaying a button over the drop zone area informing the user that they may replace their content type."
+    }
+  ],
   "options": {
     "accept": {
       "type": "array",
@@ -20,17 +50,7 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "actionLabel": {
       "type": "string",
@@ -49,18 +69,10 @@
       "description": "Callback function called when a file is dragged out of the drop zone."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "drop-zone-width",
-      "context": "Component width"
-    },
-    {
-      "token": "spacing-400",
-      "context": "Padding"
-    },
+    { "token": "drop-zone-width", "context": "Component width" },
+    { "token": "spacing-400", "context": "Padding" },
     {
       "token": "drop-zone-content-maximum-width",
       "context": "Content width (maximum)"
@@ -85,30 +97,15 @@
       "token": "spacing-200",
       "context": "Spacing (illustration to title area) "
     },
-    {
-      "token": "spacing-75",
-      "context": "Spacing (title area to body area) "
-    },
-    {
-      "token": "spacing-300",
-      "context": "Spacing (body area to action) "
-    },
-    {
-      "token": "component-height-300",
-      "context": "Text area (filled, hover)"
-    },
+    { "token": "spacing-75", "context": "Spacing (title area to body area) " },
+    { "token": "spacing-300", "context": "Spacing (body area to action) " },
+    { "token": "component-height-300", "context": "Text area (filled, hover)" },
     {
       "token": "component-edge-to-text-300",
       "context": "Text area (filled, hover)"
     },
-    {
-      "token": "component-top",
-      "context": "Text area (filled, hover)"
-    },
-    {
-      "token": "text-300",
-      "context": "Text area (filled, hover)"
-    },
+    { "token": "component-top", "context": "Text area (filled, hover)" },
+    { "token": "text-300", "context": "Text area (filled, hover)" },
     {
       "token": "component-bottom-to-text-300",
       "context": "Text area (filled, hover)"
@@ -133,10 +130,7 @@
       "token": "drop-zone-cjk-title-font-size",
       "context": "Title area and body area"
     },
-    {
-      "token": "title-line-height",
-      "context": "Title area and body area"
-    },
+    { "token": "title-line-height", "context": "Title area and body area" },
     {
       "token": "body-sans-serif-font-family",
       "context": "Title area and body area"
@@ -153,50 +147,23 @@
       "token": "drop-zone-body-font-size",
       "context": "Title area and body area"
     },
-    {
-      "token": "body-line-height",
-      "context": "Title area and body area"
-    },
+    { "token": "body-line-height", "context": "Title area and body area" },
     {
       "token": "sans-serif-font-family",
       "context": "Title area and body area"
     },
-    {
-      "token": "bold-font-weight",
-      "context": "Title area and body area"
-    },
-    {
-      "token": "default-font-size",
-      "context": "Title area and body area"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Title area and body area"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Title area and body area"
-    },
-    {
-      "token": "grey-300",
-      "context": "Border color"
-    },
+    { "token": "bold-font-weight", "context": "Title area and body area" },
+    { "token": "default-font-size", "context": "Title area and body area" },
+    { "token": "font-size-300", "context": "Title area and body area" },
+    { "token": "line-height-100", "context": "Title area and body area" },
+    { "token": "grey-300", "context": "Border color" },
     {
       "token": "neutral-content-color-default",
       "context": "Illustration color"
     },
-    {
-      "token": "accent-content-color",
-      "context": "Illustration color"
-    },
-    {
-      "token": "heading-color",
-      "context": "Title and body color"
-    },
-    {
-      "token": "body-color",
-      "context": "Title and body color"
-    },
+    { "token": "accent-content-color", "context": "Illustration color" },
+    { "token": "heading-color", "context": "Title and body color" },
+    { "token": "body-color", "context": "Title and body color" },
     {
       "token": "accent-visual-color",
       "context": "Border and background color (empty, hover)"
@@ -223,16 +190,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/field-label.json

@@ -9,81 +9,83 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/field-label/"
   },
-  "options": {
-    "label": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Field labels give context to the information that a user needs to input. They're commonly used in forms."
+    },
+    {
+      "type": "guideline",
+      "content": "Field labels provide context for associated input fields. They describe the expected content or data type."
+    },
+    {
+      "type": "guideline",
+      "content": "A field label in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an input field may become available later."
+    },
+    {
+      "type": "guideline",
+      "content": "Inputs can be marked as required or optional, depending on the situation, using a necessity indicator. There are two styles for the necessity indicator: icon or text."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, the necessity indicator is shown with an asterisk icon. Required inputs are marked with this at the end of the label. If you use this icon, be sure to include hint text to explain what it means. The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself. Optional inputs do not have an icon."
+    },
+    {
+      "type": "guideline",
+      "content": "Alternatively, the necessity indicator can be shown with text. This appends text that reads either “(required)” or “(optional)” at the end of the label."
+    },
+    {
+      "type": "guideline",
+      "content": "Field labels come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option with medium-sized inputs. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page. Both small and medium field labels have the same font size, but different paddings when used as side labels."
+    },
+    {
+      "type": "guideline",
+      "content": "A label can be placed either on top or on the side of an input. This option affects the bounding box of the component to ensure proper alignment. 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": "When the field label is too long for the available horizontal space, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form."
     },
+    {
+      "type": "guideline",
+      "content": "If most of the input fields are optional, only the required fields should be given an asterisk icon or have labels appended with “(required).” If most of the input fields are required, only the optional fields should be appended with “(optional).” An asterisk icon should never be used to note that a field is optional."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
     "labelPosition": {
       "type": "string",
       "default": "top",
-      "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "side"
-        }
-      ]
+      "values": [{ "value": "top" }, { "value": "side" }]
     },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
     "necessityIndicator": {
       "type": "string",
       "default": "icon",
-      "values": [
-        {
-          "value": "text"
-        },
-        {
-          "value": "icon"
-        }
-      ]
+      "values": [{ "value": "text" }, { "value": "icon" }]
     },
-    "isRequired": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "isRequired": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
   },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "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": "field-label-text-to-asterisk-small",
       "context": "Spacing (label to asterisk icon)"
@@ -148,18 +150,9 @@
       "token": "component-bottom-to-text-300",
       "context": "Spacing (top/bottom edge to label)"
     },
-    {
-      "token": "asterisk-icon-size-100",
-      "context": "Asterisk UI icon asset"
-    },
-    {
-      "token": "asterisk-icon-size-200",
-      "context": "Asterisk UI icon asset"
-    },
-    {
-      "token": "asterisk-icon-size-300",
-      "context": "Asterisk UI icon asset"
-    },
+    { "token": "asterisk-icon-size-100", "context": "Asterisk UI icon asset" },
+    { "token": "asterisk-icon-size-200", "context": "Asterisk UI icon asset" },
+    { "token": "asterisk-icon-size-300", "context": "Asterisk UI icon asset" },
     {
       "token": "neutral-subdued-content-color-default",
       "context": "Label and asterisk icon"
@@ -168,52 +161,17 @@
       "token": "disabled-content-color",
       "context": "Label and asterisk icon (disabled)"
     },
-    {
-      "token": "white",
-      "context": "Label and asterisk icon (white)"
-    },
-    {
-      "token": "black",
-      "context": "Label and asterisk icon (black)"
-    },
-    {
-      "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": "white", "context": "Label and asterisk icon (white)" },
+    { "token": "black", "context": "Label and asterisk icon (black)" },
+    { "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": {
-    "focusable": false
-  }
+  "accessibility": { "focusable": false }
 }

package/components/help-text.json

@@ -9,21 +9,66 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/help-text/"
   },
-  "options": {
-    "text": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Help text provides either an informative description or an error message that gives more context about what a user needs to input. It’s commonly used in forms."
+    },
+    {
+      "type": "guideline",
+      "content": "Help text provides additional context for an input field, such as descriptions, instructions, or error messages. It’s commonly used in forms to clarify what’s expected or to explain validation."
+    },
+    {
+      "type": "guideline",
+      "content": "Help text using the neutral variant can be displayed in a disabled state. The text appears with a lighter gray that matches the style of other components in a disabled state. Help text using the negative variant cannot be displayed in a disabled state because it communicates an error, and error messages should not be visible when the component is disabled."
+    },
+    {
+      "type": "guideline",
+      "content": "Help text comes 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 and pair them with components of the same size to respect the built-in hierarchy."
+    },
+    {
+      "type": "guideline",
+      "content": "Help text has two variants: neutral and negative. The neutral variant is used to convey informative messages, while the negative variant is used to convey error messages."
+    },
+    {
+      "type": "guideline",
+      "content": "The text can accommodate either a description or an error message, giving extra context and guidance. Sometimes this communicates what to input or select, and sometimes it communicates how. It includes information such as:"
+    },
+    {
+      "type": "guideline",
+      "content": "Regardless of the kind of message, it should be clear and concise. Use 1-2 short, complete sentences that end with a period (never an exclamation point). When showing formatting examples, it's not necessary to end with a period."
+    },
+    {
+      "type": "guideline",
+      "content": "When the text is too long for the available horizontal space, it wraps to form another line."
+    },
+    {
+      "type": "guideline",
+      "content": "For the optional icon that can be displayed with the negative variant, usage depends on what kind of component the help text is accompanying. Whether to include the optional icon with the negative variant depends on the component that the help text accompanies."
     },
+    {
+      "type": "guideline",
+      "content": "Help text displays either a description (the neutral variant) or an error message (the negative variant) in the same space. 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": "Since one gets replaced by Because one replaces the other, the language of the help text description and the error need to work together to communicate convey the same message messaging. The description text explains the requirements or adds supplementary context for how to successfully interact with a component. The error message text restates the same requirements, guiding the user to fix the issue. tells a user how to fix the error by re-stating the interaction requirements. Make sure that the help text description and error message include the same essential information so that it isn’t lost if one replaces the other."
+    },
+    {
+      "type": "guideline",
+      "content": "Communicate error messages in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user."
+    },
+    {
+      "type": "guideline",
+      "content": "For help text, usually the error is related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”"
+    }
+  ],
+  "options": {
+    "text": { "type": "string" },
     "variant": {
       "type": "string",
       "default": "neutral",
-      "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "negative"
-        }
-      ]
+      "values": [{ "value": "neutral" }, { "value": "negative" }]
     },
     "hideIcon": {
       "type": "boolean",
@@ -34,18 +79,10 @@
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
     "isDisabled": {
@@ -54,46 +91,17 @@
       "description": "Help text cannot be both disabled and negative variant."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "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": "workflow-icon-size-75",
-      "context": "Icon size"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon size"
-    },
-    {
-      "token": "workflow-icon-size-200",
-      "context": "Icon size"
-    },
-    {
-      "token": "workflow-icon-size-300",
-      "context": "Icon size"
-    },
-    {
-      "token": "text-to-visual-75",
-      "context": "Spacing (alert icon to text)"
-    },
+    { "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": "workflow-icon-size-75", "context": "Icon size" },
+    { "token": "workflow-icon-size-100", "context": "Icon size" },
+    { "token": "workflow-icon-size-200", "context": "Icon size" },
+    { "token": "workflow-icon-size-300", "context": "Icon size" },
+    { "token": "text-to-visual-75", "context": "Spacing (alert icon to text)" },
     {
       "token": "text-to-visual-100",
       "context": "Spacing (alert icon to text)"
@@ -154,10 +162,7 @@
       "token": "component-bottom-to-text-300",
       "context": "Spacing (top/bottom edge to text)"
     },
-    {
-      "token": "neutral-subdued-content-color-default",
-      "context": "Text"
-    },
+    { "token": "neutral-subdued-content-color-default", "context": "Text" },
     {
       "token": "disabled-content-color-default",
       "context": "Text and alert icon (disabled)"
@@ -166,44 +171,15 @@
       "token": "negative-content-color-default",
       "context": "Text and alert icon (warning)"
     },
-    {
-      "token": "default-font-family",
-      "context": "Text"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Text"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Text"
-    },
-    {
-      "token": "font-size-75",
-      "context": "Text"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Text"
-    },
-    {
-      "token": "font-size-200",
-      "context": "Text"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Text"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Text"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Text"
-    }
+    { "token": "default-font-family", "context": "Text" },
+    { "token": "regular-font-weight", "context": "Text" },
+    { "token": "default-font-style", "context": "Text" },
+    { "token": "font-size-75", "context": "Text" },
+    { "token": "font-size-100", "context": "Text" },
+    { "token": "font-size-200", "context": "Text" },
+    { "token": "font-size-300", "context": "Text" },
+    { "token": "line-height-100", "context": "Text" },
+    { "token": "cjk-line-height-100", "context": "Text" }
   ],
-  "accessibility": {
-    "focusable": false
-  }
+  "accessibility": { "focusable": false }
 }