@adobe/spectrum-design-data 3.3.0-beta.0 → 3.3.0-beta.1

package/components/contextual-help.json

@@ -16,171 +16,132 @@
     },
     {
       "type": "guideline",
-      "content": "Contextual help displays additional information about the state of a nearby component or an entire view. It explains high-level concepts and can link to more detailed guidance."
+      "content": "Keyboard focus.\n\nA 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": "To make sure that a popover will stay within certain boundaries (e.g., a browser window) it’s possible to define a container, and a container padding value, to respect."
+      "content": "Tooltip when the label is hidden.\n\nWhen the button label is hidden, a tooltip is shown on hover that displays the label text and, if appropriate, a keyboard shortcut."
     },
     {
       "type": "guideline",
-      "content": "The cross offset is the placement offset on the cross axis (x-axis for top and bottom, y-axis for left and right)."
+      "content": "Flexible width.\n\nThe width of a button automatically adjusts to fit the label text. The padding on each side of the button is equal to half its height."
     },
     {
       "type": "guideline",
-      "content": "A contextual help can have up to one link."
+      "content": "Minimum width.\n\nButtons have a minimum width of 2.25× the height of the button. This ensures that small buttons retain an identifiable shape."
     },
     {
       "type": "guideline",
-      "content": "The offset is the distance between the action button and the popover edge. There is a default value but this can also be adjusted depending on the context."
+      "content": "Text overflow.\n\nWhen the button text is too long for the horizontal space available, it wraps to form another line."
     },
     {
       "type": "guideline",
-      "content": "Indicates whether contents are informative or provides helpful guidance."
+      "content": "Cursor style.\n\nButtons use the default arrow cursor for all states, including hover and down. The only exception occurs on the web; if the button is using the href property it will display the pointer cursor instead."
     },
     {
       "type": "guideline",
-      "content": "Contextual help can be used to explain why a component is disabled and how to enable it. Don’t make disabled components interactive (with focus states or hovering) as a way to display contextual information."
+      "content": "Delay before pending state.\n\nSome progress can be very quick. In order to avoid showing a progress circle for a fraction of a second, which results in an unpleasant flickering, there is a delay of 1 second before the pending state appears. During this delay, the button continues to visually respond to interactive events (e.g., hover), but additional clicks do not result in repeated submissions."
     },
     {
       "type": "guideline",
-      "content": "There are two size options for the action button in contextual help: extra-small and small. Regardless of size, the action button should be quiet and display only an icon."
+      "content": "Tooltip vs. contextual help.\n\nA tooltip shows in-line information about the element that a user is hovering or focusing on. Contextual help describes a larger experience, such as something that's associated with that element in a broader sense. Use contextual help to communicate information about an entire view, rather than a specific element of the experience (e.g., in high-level section headers). Tooltips are meant for a few words or a short sentence, such as showing the label for an icon-only button. Contextual help offers more space to give more information, or to describe where a user can find further help."
+    },
+    {
+      "type": "guideline",
+      "content": "Help text vs. contextual help.\n\nHelp text is readily visible, in-line information about a specific UI element. The information in the contextual help component is about an entire experience or view, is hidden within a popover, and only appears once a user interacts with the icon-only action button. Use help text for critical information that a user needs to know to complete a task. Don't hide essential information in contextual help; it's intended to supplement the experience with minimal disruption."
+    },
+    {
+      "type": "guideline",
+      "content": "More information about disabled components.\n\nContextual help can be used to explain why a component is disabled and how to enable it. Don't make disabled components interactive (with focus states or hovering) as a way to display contextual information."
+    },
+    {
+      "type": "guideline",
+      "content": "Action button component size.\n\nThere are two size options for the action button in contextual help: extra-small and small. Regardless of size, the action button should be quiet and display only an icon."
+    },
+    {
+      "type": "guideline",
+      "content": "Informative vs. helpful content.\n\nThe content within the contextual help's popover reflects the icon it's associated with: either the info icon or the help icon. Use the info icon for informative content: specific, brief, and contextual guidance. This is best for supplemental or nice-to-know information, in-line with a label or a component (if there is no label). The content should be instructive in tone. Use the help icon for helpful content: more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts. This may include an image, video, or link and should be helpful in tone."
+    },
+    {
+      "type": "guideline",
+      "content": "Use proper formatting.\n\nFor this component, don't add a period to the end of the title. A question mark is acceptable, depending on the context. For the description, add a period to the end of the sentence, even if it's only a single sentence. If using a standalone link, do not add punctuation to the end of the link text."
+    },
+    {
+      "type": "guideline",
+      "content": "When to use a standalone link.\n\nIf using a standalone link, make sure that the landing experience is intuitive, helpful, and naturally builds upon the information being introduced in the component. For example, don't link to an external sales website unless the information there is directly related to a user being able to do something within the product. A generic \"Learn more\" can be acceptable, but it's more helpful to include another word or two in the link text that gives more context about the landing experience."
+    },
+    {
+      "type": "guideline",
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the button is mirrored. The icon is placed on the right side of the text."
+    },
+    {
+      "type": "guideline",
+      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
+    },
+    {
+      "type": "guideline",
+      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
+    },
+    {
+      "type": "guideline",
+      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.Text contrast minimums 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
     }
   ],
   "options": {
     "icon": {
       "type": "string",
       "default": "info",
-      "values": [
-        {
-          "value": "info"
-        },
-        {
-          "value": "help"
-        }
-      ]
+      "values": [{ "value": "info" }, { "value": "help" }]
     },
     "popoverPlacement": {
       "type": "string",
       "default": "bottom start",
       "values": [
-        {
-          "value": "top"
-        },
-        {
-          "value": "top left"
-        },
-        {
-          "value": "top right"
-        },
-        {
-          "value": "top start"
-        },
-        {
-          "value": "top end"
-        },
-        {
-          "value": "bottom"
-        },
-        {
-          "value": "bottom left"
-        },
-        {
-          "value": "bottom right"
-        },
-        {
-          "value": "bottom start"
-        },
-        {
-          "value": "bottom end"
-        },
-        {
-          "value": "left"
-        },
-        {
-          "value": "left top"
-        },
-        {
-          "value": "left bottom"
-        },
-        {
-          "value": "start"
-        },
-        {
-          "value": "start top"
-        },
-        {
-          "value": "start bottom"
-        },
-        {
-          "value": "right"
-        },
-        {
-          "value": "right top"
-        },
-        {
-          "value": "right bottom"
-        },
-        {
-          "value": "end"
-        },
-        {
-          "value": "end top"
-        },
-        {
-          "value": "end bottom"
-        }
+        { "value": "top" },
+        { "value": "top left" },
+        { "value": "top right" },
+        { "value": "top start" },
+        { "value": "top end" },
+        { "value": "bottom" },
+        { "value": "bottom left" },
+        { "value": "bottom right" },
+        { "value": "bottom start" },
+        { "value": "bottom end" },
+        { "value": "left" },
+        { "value": "left top" },
+        { "value": "left bottom" },
+        { "value": "start" },
+        { "value": "start top" },
+        { "value": "start bottom" },
+        { "value": "right" },
+        { "value": "right top" },
+        { "value": "right bottom" },
+        { "value": "end" },
+        { "value": "end top" },
+        { "value": "end bottom" }
       ]
     },
-    "popoverOffset": {
-      "type": "number",
-      "default": 8
-    },
+    "popoverOffset": { "type": "number", "default": 8 },
     "href": {
       "type": "string",
       "description": "Optional URL within contextual help content like a 'Learn more' link."
     },
-    "popoverCrossOffset": {
-      "type": "number",
-      "default": 0
-    },
-    "containerPadding": {
-      "type": "number",
-      "default": 8
-    }
+    "popoverCrossOffset": { "type": "number", "default": 0 },
+    "containerPadding": { "type": "number", "default": 8 }
   },
   "states": [
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "open",
-      "trigger": "prop"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
+    { "name": "down", "trigger": "interaction" },
+    { "name": "open", "trigger": "prop" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "intents": ["trigger"],
     "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/date-picker.json

@@ -16,91 +16,39 @@
     },
     {
       "type": "guideline",
-      "content": "Date pickers allow selection of a single date or a date range. They include a calendar within a popover, with optional manual entry. Date range variants support selecting a start and end date in one field."
+      "content": "Displaying the popover calendar.\n\nThe calendar popover is displayed or hidden when the user selects the in-field button (the calendar icon)."
     },
     {
       "type": "guideline",
-      "content": "Calendar popover displays a grid of days spanning one, two, or three months, enabling users to select a single date or a range."
+      "content": "Range selection.\n\nIf a user selects a day preceding the first selection, that earlier day becomes the start of the range. For example: First selection: Jan 3. This is the start of the range. Second selection: Jan 1. This is the new start of the range. The range is now Jan 1–3 in the calendar popover and date field. A third selection resets the range. For example: Third selection: Jan 4. This is the start of a new range. Current state: Jan 4 (no end of range). The calendar popover displays Jan 4 as the start of the range but with no defined end. The date field remains populated by the user's last complete input (Jan 1-3) until they indicate the end of their new range."
     },
     {
       "type": "guideline",
-      "content": "Date field allows users to enter and edit date values. Users can edit each part of a date value, such as the day, month, and year, by interacting with individual segments. A date field includes a label, segments for each value of the date, and an in-field button to allow the user to open the calendar popover."
+      "content": "Individual segments for date field.\n\nDate pickers display placeholder values in individual segments by default. This is to makes it easier for users to focus and edit specific values like the day, month, or year without re-entering the entire date. This approach reduces input errors, improves accessibility, and supports faster, more precise interactions. It also adapts well to different regional formats, enhancing clarity across locales."
     },
     {
       "type": "guideline",
-      "content": "The range of days the user has selected (a start date and an end date)."
+      "content": "Single date or date range.\n\nDate pickers can be used to select a single date or a date range (a start date and an end date)."
     },
     {
       "type": "guideline",
-      "content": "The selected date allows a user to see which date they have selected within the calendar popover."
+      "content": "Date range selection.\n\nWhen a date picker is formatted to allow a range, it displays a placeholder by default. When the user first interacts with the date field, the first value of the placeholder is in focus. This is to allow the user to edit the individual segments. When the user opens the popover without interacting, it displays the current day along with the month and year based on their locale. However, the date field will continue to show the placeholder until the user either completes the range in the field or within the calendar popover. If the user inputs a date range within the date field that spans more than the maximum of three months that the calendar popover allows, the calendar popover will only show the first three consecutive months within that range."
     },
     {
       "type": "guideline",
-      "content": "A single date picker only displays a single date within the date field as well as a single month within the calendar popover."
+      "content": "Granularity.\n\nThe date field can also capture time values with precision down to the second, and may include time zone information. The calendar popover can also include time-specific fields, allowing users to specify start and end times."
     },
     {
       "type": "guideline",
-      "content": "A double date picker displays a date range within the date field as well as two consecutive months within the calendar popover."
+      "content": "Required or optional.\n\nDate pickers can be marked as optional or required, depending on the situation. For required date pickers, there are two styling options: a \"(required)\" label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means. Optional date pickers are either denoted with text added to the end of the label — \"(optional)\" — or have no indication at all. 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": "A triple date picker displays a date range within the date field as well as three consecutive months within the calendar popover."
+      "content": "Read-only states vs. disabled states.\n\nA read-only state of date picker means that the user cannot interact with the field, and they can only read what the field is displaying. Therefore, the in-field button is not clickable. In the disabled state, the read-only state of date picker allows the user to focus on a value—even though they cannot change the value. A disabled date picker means that the user cannot interact with the field, but not for the same reasons as a read-only scenario. For example, a date picker may be temporarily disabled because the user needs to complete a dependent task (such as filling out another field) somewhere within their experience. A disabled date picker does not allow for the ability to focus on a value, or to change its value."
     },
     {
       "type": "guideline",
-      "content": "The calendar popover is displayed or hidden when the user selects the in-field button (the calendar icon)."
-    },
-    {
-      "type": "guideline",
-      "content": "If a user selects a day preceding the first selection, that earlier day becomes the start of the range. For example:"
-    },
-    {
-      "type": "guideline",
-      "content": "A third selection resets the range. For example:"
-    },
-    {
-      "type": "guideline",
-      "content": "Date pickers display placeholder values in individual segments by default. This is to makes it easier for users to focus and edit specific values like the day, month, or year without re-entering the entire date."
-    },
-    {
-      "type": "guideline",
-      "content": "This approach reduces input errors, improves accessibility, and supports faster, more precise interactions. It also adapts well to different regional formats, enhancing clarity across locales."
-    },
-    {
-      "type": "guideline",
-      "content": "Date pickers can be used to select a single date or a date range (a start date and an end date)."
-    },
-    {
-      "type": "guideline",
-      "content": "When a date picker is formatted to allow a range, it displays a placeholder by default. When the user first interacts with the date field, the first value of the placeholder is in focus. This is to allow the user to edit the individual segments. When the user opens the popover without interacting, it displays the current day along with the month and year based on their locale. However, the date field will continue to show the placeholder until the user either completes the range in the field or within the calendar popover."
-    },
-    {
-      "type": "guideline",
-      "content": "If the user inputs a date range within the date field that spans more than the maximum of three months that the calendar popover allows, the calendar popover will only show the first three consecutive months within that range."
-    },
-    {
-      "type": "guideline",
-      "content": "The date field can also capture time values with precision down to the second, and may include time zone information. The calendar popover can also include time-specific fields, allowing users to specify start and end times."
-    },
-    {
-      "type": "guideline",
-      "content": "Date pickers can be marked as optional or required, depending on the situation. For required date pickers, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means. Optional date pickers are either denoted with text added to the end of the label — “(optional)” — or have no indication at all."
-    },
-    {
-      "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": "A read-only state of date picker means that the user cannot interact with the field, and they can only read what the field is displaying. Therefore, the in-field button is not clickable. In the disabled state, the read-only state of date picker allows the user to focus on a value—even though they cannot change the value."
-    },
-    {
-      "type": "guideline",
-      "content": "A disabled date picker means that the user cannot interact with the field, but not for the same reasons as a read-only scenario. For example, a date picker may be temporarily disabled because the user needs to complete a dependent task (such as filling out another field) somewhere within their experience. A disabled date picker does not allow for the ability to focus on a value, or to change its value."
-    },
-    {
-      "type": "guideline",
-      "content": "A date picker can be marked as having an error to show that a value needs to be entered in order to move forward, or that an entered value is invalid. In this scenario, displaying error text beneath the date field can aid the user in understanding how to resolve it. Error text within the calendar popover may also be helpful to aid the user in understanding what the error is signaling."
+      "content": "Error.\n\nA date picker can be marked as having an error to show that a value needs to be entered in order to move forward, or that an entered value is invalid. In this scenario, displaying error text beneath the date field can aid the user in understanding how to resolve it. Error text within the calendar popover may also be helpful to aid the user in understanding what the error is signaling."
     }
   ],
   "options": {
@@ -109,15 +57,9 @@
       "default": "single",
       "description": "Controls the number of months displayed in the calendar popover.",
       "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "double"
-        },
-        {
-          "value": "triple"
-        }
+        { "value": "single" },
+        { "value": "double" },
+        { "value": "triple" }
       ]
     },
     "selectedDate": {
@@ -128,14 +70,8 @@
       "type": "object",
       "description": "The currently selected date range, used when selectionMode is range.",
       "properties": {
-        "start": {
-          "type": "string",
-          "description": "Range start date."
-        },
-        "end": {
-          "type": "string",
-          "description": "Range end date."
-        }
+        "start": { "type": "string", "description": "Range start date." },
+        "end": { "type": "string", "description": "Range end date." }
       }
     },
     "dateField": {
@@ -151,22 +87,10 @@
           "enum": ["top", "side"],
           "default": "top"
         },
-        "hideLabel": {
-          "type": "boolean",
-          "default": false
-        },
-        "isDisabled": {
-          "type": "boolean",
-          "default": false
-        },
-        "isReadOnly": {
-          "type": "boolean",
-          "default": false
-        },
-        "isRequired": {
-          "type": "boolean",
-          "default": false
-        },
+        "hideLabel": { "type": "boolean", "default": false },
+        "isDisabled": { "type": "boolean", "default": false },
+        "isReadOnly": { "type": "boolean", "default": false },
+        "isRequired": { "type": "boolean", "default": false },
         "isError": {
           "type": "boolean",
           "default": false,
@@ -191,10 +115,7 @@
       "type": "object",
       "description": "Configuration for the calendar popover.",
       "properties": {
-        "isDisabled": {
-          "type": "boolean",
-          "default": false
-        },
+        "isDisabled": { "type": "boolean", "default": false },
         "minValue": {
           "type": "string",
           "description": "The minimum allowed date that a user may select."
@@ -259,14 +180,9 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "strikethrough-day-thickness",
-      "context": "Strikethrough day "
-    },
+    { "token": "strikethrough-day-thickness", "context": "Strikethrough day " },
     {
       "token": "date-picker-text-to-in-field-button",
       "context": "Spacing (value to in-field button)"
@@ -277,21 +193,9 @@
     "focusable": true,
     "keyboardIntents": ["navigate-items", "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" }
     ]
   }
 }

package/components/divider.json

@@ -22,41 +22,28 @@
       "type": "do-dont",
       "content": "Don't overuse dividers",
       "dont": "Dividers lose their value when overused. Use them sparingly to avoid creating unnecessary noise."
+    },
+    {
+      "type": "guideline",
+      "content": "Cursor guidelines.\n\nCursor Usage Default (Arrow)Use the default cursor for non-interactive elements like the divider."
+    },
+    {
+      "type": "guideline",
+      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 2. Operable Requirement Criterion Level Compliance Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component."
     }
   ],
   "options": {
     "size": {
       "type": "string",
       "default": "s",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "vertical"
-        }
-      ]
+      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }

package/components/drop-zone.json

@@ -16,27 +16,35 @@
     },
     {
       "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."
+      "content": "Dragging file type over drop zone area.\n\nWhen a user drags a file over the drop zone ( onDragOver ), the border and background styling update to reflect an active state. This visual cue helps users understand that the drop zone is ready to accept the file, reducing uncertainty."
     },
     {
       "type": "guideline",
-      "content": "A button is an optional element to prompt the user to take action."
+      "content": "Dropping file type within drop zone area.\n\nWhen a user drops a file into the designated drop zone ( onDrop ), the zone should respond with clear visual feedback—this is typically achieved through displaying a button over the drop zone area informing the user that they may replace their content type. This feedback indicates that the user successfully dropped their file type into the zone and is permitted to replace it."
     },
     {
       "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."
+      "content": "Leaving drop zone area.\n\nWhen a user drags a file outside the designated drop zone ( onDragLeave ), any visual indicators—such as borders or background styling should revert to their default state."
     },
     {
       "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."
+      "content": "Clearly communicate accepted file types.\n\nIndicate 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."
+      "content": "Provide immediate visual feedback.\n\nWhen 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."
+      "content": "Allow the user to replace file types.\n\nVisual 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."
+    },
+    {
+      "type": "guideline",
+      "content": "Writing the title.\n\nUse the content pattern of \"Drag and drop your {item}\" for the drop zone's title. The \"drag and drop\" phrasing communicates why the UI is appearing in the way that it is, and guides a user for what they need to do in the interaction. Don't use punctuation at the end of the title."
+    },
+    {
+      "type": "guideline",
+      "content": "Writing the description.\n\nThe drop zone's body area elaborates on the title and offers more information about how to complete the interaction. In-line links can offer other ways to accomplish the task, such as launching the user's file browser or taking them to another resource. Write the description using full sentences, and include periods at the end of each sentence."
     }
   ],
   "options": {
@@ -50,17 +58,7 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "actionLabel": {
       "type": "string",
@@ -79,24 +77,14 @@
       "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" },
   "accessibility": {
     "intents": ["input"],
     "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" }
     ]
   }
 }