@adobe/spectrum-design-data 3.3.0 → 3.4.0

package/components/drop-zone.json

@@ -9,13 +9,6 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/drop-zone/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "DropZone",
-      "package": "@react-spectrum/s2"
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -23,27 +16,42 @@
     },
     {
       "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": "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": "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": "A button is an optional element to prompt the user to take action."
+      "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": "Drop zones come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option."
+      "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": "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": "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": "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": "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": "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": "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."
+    }
+  ],
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "DropZone",
+      "package": "@react-spectrum/s2"
     }
   ],
   "options": {
@@ -57,17 +65,7 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "actionLabel": {
       "type": "string",
@@ -86,24 +84,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" }
     ]
   }
 }

package/components/field-label.json

@@ -16,110 +16,73 @@
     },
     {
       "type": "guideline",
-      "content": "Field labels provide context for associated input fields. They describe the expected content or data type."
+      "content": "Text overflow.\n\nWhen the field label is too long for the available horizontal space, it wraps to form another line."
     },
     {
       "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."
+      "content": "Mark the minority of inputs in a form as required or optional.\n\nIn a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form. 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."
     },
     {
       "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."
+      "content": "For field label text, use a short, catch-all description (1-3 words) of the information that a user needs to provide. Field label text that gets too long can be overwhelming and distracting, especially in complex interactions and long forms. Supplementary information or requirements about what to input can be shown in help text below the field, or in a tooltip."
     },
     {
       "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."
+      "content": "Use verbs like \"enter,\" \"add,\" or \"input\" in a field label sparingly.\n\nField labels generally communicate what a user should input, rather than direct them as to how to do it. The component design of fields and other inputs already implies that a user needs to enter, add, or input information in order to move forward with a task or workflow. If the interaction may be new or unfamiliar it can be helpful to guide a user with action prompts using these verbs, but for more common patterns (such as forms), this can get redundant and clutter an interface."
     },
     {
       "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."
+      "content": "Don't add a colon at the end of a field label.\n\nDon't add a colon (:) at the end of a field label to imply that the label text applies to the field it accompanies. The design of the component already communicates the relationship between the label and the input field."
     },
     {
       "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."
+      "content": "Use sentence case.\n\nFollowing Adobe's UX writing style, field labels are written in sentence case unless they contain words that are branded terms."
     },
     {
       "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."
+      "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": "When the field label is too long for the available horizontal space, it wraps to form another line."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Moves focus onto or off of the button. Space or Enter Executes 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": "In a single form, mark only the required fields or only the optional fields, depending on whichever is less frequent in the entire form."
+      "content": "Cursor guidelines.\n\nCursor Usage Pointer Use the pointer cursor for all interactive components."
     },
     {
       "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."
+      "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 A Non‑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, AAA Buttons 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 A Color 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 AA Large 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 AA Buttons should be built in such a way that they can be resized without assistive technology up to 200%. Visual presentation 1.4.8 AAA The 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 AA The visual presentation of icons and various states have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line 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, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
     }
   ],
   "options": {
-    "label": {
-      "type": "string"
-    },
+    "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
-    }
+    "isRequired": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
   },
   "anatomy": [
-    {
-      "name": "asterisk",
-      "description": "Required-field indicator."
-    }
+    { "name": "asterisk", "description": "Required-field indicator." }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }

package/components/help-text.json

@@ -16,68 +16,43 @@
     },
     {
       "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."
+      "content": "Text overflow.\n\nWhen the text is too long for the available horizontal space, it wraps to form another line."
     },
     {
       "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."
+      "content": "Use the optional icon depending on the accompanying component.\n\nFor 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. For components such as text field, text area, picker, and combo box, where there is already an icon communicating an error, it's not necessary to include another icon in the help text. For checkbox groups or radio button groups, where there is no icon to communicate an error, include the optional icon."
     },
     {
       "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."
+      "content": "Switch the help text description with an error message.\n\nHelp 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. Because one replaces the other, the language of the help text description and the error need to work together to convey the same 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. 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. Learn how this applies to help text for text field, text area, combo box, and picker."
     },
     {
       "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."
+      "content": "Write error messages that show a solution.\n\nCommunicate 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. 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.\" Learn how this applies to help text for text field, text area, combo box, and picker."
     },
     {
       "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:"
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the help text is mirrored. The icon is placed on the right side of the text."
     },
     {
       "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."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Moves focus onto or off of the button. Space or Enter Executes 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": "When the text is too long for the available horizontal space, it wraps to form another line."
+      "content": "Cursor guidelines.\n\nCursor Usage Pointer Use the pointer cursor for all interactive components."
     },
     {
       "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.”"
+      "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 A Non‑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, AAA Buttons 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 A Color 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 AA Large 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 AA Buttons should be built in such a way that they can be resized without assistive technology up to 200%. Visual presentation 1.4.8 AAA The 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 AA The visual presentation of icons and various states have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line 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, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
     }
   ],
   "options": {
-    "text": {
-      "type": "string"
-    },
+    "text": { "type": "string" },
     "variant": {
       "type": "string",
       "default": "neutral",
-      "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "negative"
-        }
-      ]
+      "values": [{ "value": "neutral" }, { "value": "negative" }]
     },
     "hideIcon": {
       "type": "boolean",
@@ -88,18 +63,10 @@
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
     "isDisabled": {
@@ -108,10 +75,6 @@
       "description": "Help text cannot be both disabled and negative variant."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }

package/components/illustrated-message.json

@@ -29,87 +29,57 @@
     },
     {
       "type": "guideline",
-      "content": "Illustrated messages pair text with imagery to communicate a message with visual emphasis. They’re commonly used in empty states, feedback states, and error messaging."
+      "content": "Motion in illustrated message.\n\nMotion is an optional feature of illustrations, but it is not a requirement. When used, they should feel natural, intentional, and aligned with the emotional and functional goals of the message."
     },
     {
       "type": "guideline",
-      "content": "The secondary button provides a less prominent action that supports the overall message but is not the primary goal. It offers users an alternative path that’s relevant but lower priority."
+      "content": "Buttons in illustrated message.\n\nButtons in an illustrated message are designed to guide users toward a clear next step by translating the message's intent into direct, actionable choices. They help users understand what will happen next and support decision-making within the context of the message."
     },
     {
       "type": "guideline",
-      "content": "The primary button serves as the main call to action. It’s the clearest, most direct path forward for the user, and it should align with the purpose of the message. In an illustrated message—where visuals and copy work together to guide attention—the primary button anchors the experience."
+      "content": "Horizontal vs. vertical illustrations.\n\nHorizontal orientation works best when there's ample screen space, such as on desktop or wide containers, and when the message needs to sit alongside related content. It allows for a balanced layout where the illustration and text can appear side by side, supporting quick scanning and visual clarity. Vertical orientation is suited for constrained spaces like mobile screens or narrow containers. It supports a linear, top-to-bottom flow that guides the user through the illustration, description, and action in sequence."
     },
     {
       "type": "guideline",
-      "content": "The description supports the illustration and buttons by delivering the core message in plain language. It helps users quickly grasp the purpose of the message and decide what to do next."
+      "content": "Illustrations and attention hierarchy.\n\nThe different styles of illustrations are connected to the Spectrum 2 concept of attention hierarchy. Linear illustrations are elements that communicate lower attention, as they blend in well with the rest of the UI. They can be used multiple times in a layout without drawing too much attention. Gradient illustrations are high attention elements that should be used sparingly and selectively. Only one illustration, element, or group of elements should have high attention on a page. Learn more about this with the Spectrum 2 attention hierarchy guidelines."
     },
     {
       "type": "guideline",
-      "content": "A clear title for the description section in an illustrated message"
+      "content": "Use linear style when showing several illustrations together.\n\nThe linear illustration style works well for layouts that feature a number of illustrations together (such as a collection of cards). Linear illustrations draw a lower level of attention and blend in well with the UI, so it's appropriate to use them in a collection of elements. Gradient illustrations draw a lot of attention in multiples, so they need to be used sparingly and sparsely."
     },
     {
       "type": "guideline",
-      "content": "Orientation affects how users perceive and interact with content. Illustrated message layout can be horizontal or vertical."
+      "content": "Use gradient illustrations thoughtfully.\n\nGradient illustrations are high attention elements in the layout. Use them strategically and thoughtfully to draw the user's attention and to provoke a delightful moment. Gradient illustrations draw more attention because they're very colorful. Using more than one in a given view will make the UI too busy and too loud. Use gradient illustrations sparingly to guide a user's attention to engaging, high-value actions such as uploads, starting projects, or commenting."
     },
     {
-      "type": "guideline",
-      "content": "Illustrated messages come in three different sizes: small, medium, and large. The medium size is the default and most frequently used option."
-    },
-    {
-      "type": "guideline",
-      "content": "The illustration sets the tone and draws attention. It visually reinforces the message’s purpose and helps users quickly understand the context before reading any text or taking action."
-    },
-    {
-      "type": "guideline",
-      "content": "Motion is an optional feature of illustrations, but it is not a requirement. When used, they should feel natural, intentional, and aligned with the emotional and functional goals of the message."
+      "type": "do-dont",
+      "content": "Don't resize illustrations",
+      "dont": "Don't scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes."
     },
     {
       "type": "guideline",
-      "content": "Buttons in an illustrated message are designed to guide users toward a clear next step by translating the message’s intent into direct, actionable choices. They help users understand what will happen next and support decision-making within the context of the message."
+      "content": "Motion in illustrated messages can be used optionally to enhance engagement and reinforce meaning without overwhelming the user. When applied thoughtfully, they add subtle motion to the illustration—such as a gentle bounce, fade, or loop—that draws attention and supports the tone of the message. These animations should be purposeful: they can signal success, soften interruptions, or guide the eye toward the primary action. However, they should never distract from the content or slow down the experience. Use them sparingly, especially in system messages or time-sensitive flows, and ensure they perform well across devices."
     },
     {
       "type": "guideline",
-      "content": "Horizontal orientation works best when there’s ample screen space, such as on desktop or wide containers, and when the message needs to sit alongside related content. It allows for a balanced layout where the illustration and text can appear side by side, supporting quick scanning and visual clarity."
+      "content": "Use linear illustrations for errors or critical messages.\n\nErrors or critical messages should only use linear illustrations. Gradient illustrations use colors that can be misunderstood as semantic colors (e.g., green for positive, red for negative). They also have an upbeat and inspirational tone, which isn't appropriate in situations where a user may be frustrated by something that's an inconvenience or is disruptive to them in accomplishing their work."
     },
     {
       "type": "guideline",
-      "content": "Vertical orientation is suited for constrained spaces like mobile screens or narrow containers. It supports a linear, top-to-bottom flow that guides the user through the illustration, description, and action in sequence."
+      "content": "Offer an actionable solution when possible.\n\nLinks and buttons can be included in an illustrated message's description to offer an actionable solution (e.g., when there is a need to upload files or contact product support). Compared to links, buttons add more visibility to actions, helping to direct a user to what to do next. Respect button ordering when using buttons in an illustrated message."
     },
     {
       "type": "guideline",
-      "content": "The linear illustration style works well for layouts that feature a number of illustrations together (such as a collection of cards). Linear illustrations draw a lower level of attention and blend in well with the UI, so it’s appropriate to use them in a collection of elements. Gradient illustrations draw a lot of attention in multiples, so they need to be used sparingly and sparsely."
+      "content": "Drag and drop vs. illustrated message.\n\nUse drag and drop when the user needs to complete a hands-on task—like uploading files, rearranging items, or customizing content. It's an interaction pattern that supports direct manipulation, giving users a sense of control and immediacy. Drag and drop is ideal when the goal is action-oriented and the interface benefits from tactile engagement. Use an illustrated message when the goal is to communicate a state, guide a decision, or prompt an action. Illustrated messages are best for moments of transition—empty states, confirmations, errors, or onboarding—where visual context and clear messaging help orient the user. They're not interactive themselves, but they support interaction by setting expectations and offering clear next steps."
     },
     {
-      "type": "guideline",
-      "content": "Gradient illustrations draw more attention because they’re very colorful. Using more then one in a given view will make the UI too busy and too loud. Use gradient illustrations sparingly to guide a user’s attention to engaging, high-value actions such as uploads, starting projects, or commenting."
-    },
-    {
-      "type": "guideline",
-      "content": "Don’t scale or resize linear illustrations. The stroke weight and the corner radii are already set to work best in the given canvas sizes."
-    },
-    {
-      "type": "guideline",
-      "content": "Motion in illustrated messages can be used optionally to enhance engagement and reinforce meaning without overwhelming the user. When applied thoughtfully, they add subtle motion to the illustration—such as a gentle bounce, fade, or loop—that draws attention and supports the tone of the message."
+      "type": "do-dont",
+      "content": "Don't create your own linear illustrations",
+      "dont": "It's essential to have consistency in tone and metaphors across all Adobe products. Don't create your own linear illustrations or alter existing ones. If you need a new linear illustration, make a request using Workfront."
     },
     {
       "type": "guideline",
-      "content": "These animations should be purposeful: they can signal success, soften interruptions, or guide the eye toward the primary action. However, they should never distract from the content or slow down the experience. Use them sparingly, especially in system messages or time-sensitive flows, and ensure they perform well across devices."
-    },
-    {
-      "type": "guideline",
-      "content": "Errors or critical messages should only use linear illustrations. Gradient illustrations use colors that can be misunderstood as semantic colors (e.g., green for positive, red for negative). They also have an upbeat and inspirational tone, which isn’t appropriate in situations where a user may be frustrated by something that’s an inconvenience or is disruptive to them in accomplishing their work."
-    },
-    {
-      "type": "guideline",
-      "content": "Use drag and drop when the user needs to complete a hands-on task—like uploading files, rearranging items, or customizing content. It’s an interaction pattern that supports direct manipulation, giving users a sense of control and immediacy. Drag and drop is ideal when the goal is action-oriented and the interface benefits from tactile engagement."
-    },
-    {
-      "type": "guideline",
-      "content": "Use an illustrated message when the goal is to communicate a state, guide a decision, or prompt an action. Illustrated messages are best for moments of transition—empty states, confirmations, errors, or onboarding—where visual context and clear messaging help orient the user. They’re not interactive themselves, but they support interaction by setting expectations and offering clear next steps."
-    },
-    {
-      "type": "guideline",
-      "content": "An illustrated message can be interruptive, so make it readily apparent that it’s adding value to a user’s experience or is putting the user on the right path to accomplish their goals. Don’t use an illustrated message for purely promotional purposes or for upsells of unrelated actions."
+      "content": "Show value.\n\nAn illustrated message can be interruptive, so make it readily apparent that it's adding value to a user's experience or is putting the user on the right path to accomplish their goals. Don't use an illustrated message for purely promotional purposes or for upsells of unrelated actions."
     }
   ],
   "options": {
@@ -121,30 +91,13 @@
       "type": "string",
       "default": "m",
       "description": "Size of the illustration.",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "orientation": {
       "type": "string",
       "default": "vertical",
       "description": "Orientation of the illustrated message.",
-      "values": [
-        {
-          "value": "vertical"
-        },
-        {
-          "value": "horizontal"
-        }
-      ]
+      "values": [{ "value": "vertical" }, { "value": "horizontal" }]
     },
     "title": {
       "type": "string",
@@ -163,10 +116,6 @@
       "description": "Label for the secondary action button. If undefined, no secondary action is shown."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }