@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/alert-banner.json

@@ -9,126 +9,154 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/alert-banner/"
   },
-  "options": {
-    "text": {
-      "type": "string"
-    },
-    "variant": {
-      "type": "string",
-      "default": "neutral",
-      "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "informative"
-        },
-        {
-          "value": "negative"
-        },
-        {
-          "value": "accent"
-        }
-      ]
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Alert banners show pressing and high-signal messages, such as system alerts. They're meant to be noticed and prompt users to take action."
     },
-    "actionLabel": {
-      "type": "string",
-      "description": "If undefined, this button does not appear."
+    {
+      "type": "guideline",
+      "content": "Alert banners communicate high-priority messages that need immediate attention. They appear prominently in the interface and often prompt an action."
     },
-    "isDismissible": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
     {
-      "token": "workflow-icon-size-100",
-      "context": "Icon asset"
+      "type": "guideline",
+      "content": "An alert banner can include an icon-only close button to dismiss it."
     },
     {
-      "token": "alert-banner-minimum-height",
-      "context": "Height"
+      "type": "guideline",
+      "content": "An alert banner ideally provides a way for a user to address an issue in-line with an action. It can have both an icon-only close button and a button with a contextual action to take. There should never be more than one button with a contextual action in an alert banner."
     },
     {
-      "token": "alert-banner-width",
-      "context": "Width"
+      "type": "guideline",
+      "content": "An alert banner always has a semantic meaning and uses semantic colors. Only gray (neutral), blue (informative), and red (negative) are available as options."
     },
     {
-      "token": "text-to-visual-300",
-      "context": "Spacing (icon to text)"
+      "type": "guideline",
+      "content": "Text is required for all alert banners. The message should be concise and, if applicable, describe the next step that a user can take."
     },
     {
-      "token": "spacing-300",
-      "context": "Spacing (start edge to text and icon)"
+      "type": "guideline",
+      "content": "When the text is too long for the available horizontal space, it wraps to form another line. In actionable alert banners, the button moves below the text prior to text wrapping."
     },
     {
-      "token": "spacing-100",
-      "context": "Spacing (close button to end edge)"
+      "type": "guideline",
+      "content": "Whenever possible, add an in-line action button if there's a way for a user to quickly address the issue associated with an alert."
     },
     {
-      "token": "spacing-200",
-      "context": "Spacing (close button to end edge)"
+      "type": "guideline",
+      "content": "The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert."
     },
     {
-      "token": "alert-banner-top-to-workflow-icon",
-      "context": "Spacing (top/bottom edge to icon)"
+      "type": "guideline",
+      "content": "Alert banners should be reserved only for high-signal, system-level alert messages, such as internet connection issues, expirations of subscriptions, or major changes."
     },
     {
-      "token": "alert-banner-top-to-text",
-      "context": "Spacing (top/bottom edge to text)"
+      "type": "guideline",
+      "content": "Don’t use yellow or orange colors for errors because the contrast is not accessible."
     },
     {
-      "token": "alert-banner-bottom-to-text",
-      "context": "Spacing (top/bottom edge to text)"
+      "type": "guideline",
+      "content": "If you need to show a “notice” message or other non-critical communication, use the gray (neutral) or blue (informative) semantic color options. Reserve the red (negative) option only for errors that directly interrupt or block a user’s experience — not for nice-to-know information."
     },
     {
-      "token": "neutral-subdued-background-color-default",
-      "context": "Background"
+      "type": "guideline",
+      "content": "Don't include more than one action in an alert banner. Having more than one action to choose from can be overwhelming, and it can become difficult for users to decide what to do next in such a small space."
     },
     {
-      "token": "informative-background-color-default",
-      "context": "Background"
+      "type": "guideline",
+      "content": "Alert banners should appear at the top of a page, below the header."
     },
     {
-      "token": "negative-background-color-default",
-      "context": "Background"
+      "type": "guideline",
+      "content": "Don't show multiple alert banners at the same time. If a new alert banner appears with a higher priority message, it should replace an existing alert banner of lesser importance until the higher priority one has been addressed."
     },
     {
-      "token": "default-font-family",
-      "context": "Text"
+      "type": "guideline",
+      "content": "Overlay an alert banner when it's expected to fade in and out without impacting the content underneath it, and when it's not hiding any important actions or information by being there. An alert banner should only overlay content if it is dismissible."
     },
     {
-      "token": "regular-font-weight",
-      "context": "Text"
+      "type": "guideline",
+      "content": "Push an alert banner when it's expected to stay in place, when it's not dismissible, or when no information should be hidden from the view."
     },
     {
-      "token": "default-font-style",
-      "context": "Text"
+      "type": "guideline",
+      "content": "If a user dismisses an alert banner without addressing an error that needs to be resolved, it should come back into view at the next possible occasion."
     },
     {
-      "token": "font-size-100",
-      "context": "Text"
+      "type": "guideline",
+      "content": "Never allow alert banners to time out. Since these are system-level messages, they should not dismiss on their own unless there is a change in the system that resolves an issue (e.g., regaining internet connectivity after losing it)."
     },
     {
-      "token": "line-height-100",
-      "context": "Text"
+      "type": "guideline",
+      "content": "When used in the app frame, the alert banner appears above the Top App Bar (TAB) and header, or above the header if the TAB isn’t active."
     },
     {
-      "token": "cjk-line-height-100",
-      "context": "Text"
+      "type": "guideline",
+      "content": "Learn more about how the Top App Bar (TAB) works in the app frame."
     }
   ],
+  "options": {
+    "text": { "type": "string" },
+    "variant": {
+      "type": "string",
+      "default": "neutral",
+      "values": [
+        { "value": "neutral" },
+        { "value": "informative" },
+        { "value": "negative" },
+        { "value": "accent" }
+      ]
+    },
+    "actionLabel": {
+      "type": "string",
+      "description": "If undefined, this button does not appear."
+    },
+    "isDismissible": { "type": "boolean", "default": false }
+  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "workflow-icon-size-100", "context": "Icon asset" },
+    { "token": "alert-banner-minimum-height", "context": "Height" },
+    { "token": "alert-banner-width", "context": "Width" },
+    { "token": "text-to-visual-300", "context": "Spacing (icon to text)" },
+    {
+      "token": "spacing-300",
+      "context": "Spacing (start edge to text and icon)"
+    },
+    { "token": "spacing-100", "context": "Spacing (close button to end edge)" },
+    { "token": "spacing-200", "context": "Spacing (close button to end edge)" },
+    {
+      "token": "alert-banner-top-to-workflow-icon",
+      "context": "Spacing (top/bottom edge to icon)"
+    },
+    {
+      "token": "alert-banner-top-to-text",
+      "context": "Spacing (top/bottom edge to text)"
+    },
+    {
+      "token": "alert-banner-bottom-to-text",
+      "context": "Spacing (top/bottom edge to text)"
+    },
+    {
+      "token": "neutral-subdued-background-color-default",
+      "context": "Background"
+    },
+    {
+      "token": "informative-background-color-default",
+      "context": "Background"
+    },
+    { "token": "negative-background-color-default", "context": "Background" },
+    { "token": "default-font-family", "context": "Text" },
+    { "token": "regular-font-weight", "context": "Text" },
+    { "token": "default-font-style", "context": "Text" },
+    { "token": "font-size-100", "context": "Text" },
+    { "token": "line-height-100", "context": "Text" },
+    { "token": "cjk-line-height-100", "context": "Text" }
+  ],
   "accessibility": {
     "focusable": false,
     "wcag": [
-      {
-        "criterion": "4.1.3",
-        "level": "AA",
-        "title": "Status Messages"
-      }
+      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
     ]
   }
 }

package/components/alert-dialog.json

@@ -9,155 +9,115 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/alert-dialog/"
   },
-  "options": {
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
-    },
-    "variant": {
-      "type": "string",
-      "default": "confirmation",
-      "values": [
-        {
-          "value": "confirmation"
-        },
-        {
-          "value": "information"
-        },
-        {
-          "value": "warning"
-        },
-        {
-          "value": "destructive"
-        },
-        {
-          "value": "error"
-        }
-      ]
-    },
-    "primaryActionLabel": {
-      "type": "string"
-    },
-    "secondaryActionLabel": {
-      "type": "string",
-      "description": "If undefined, this button does not appear."
-    },
-    "cancelActionLabel": {
-      "type": "string",
-      "default": "cancel",
-      "description": "If undefined, this button does not appear."
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
-    {
-      "token": "heading-sans-serif-font-family",
-      "context": "Title"
-    },
+  "documentBlocks": [
     {
-      "token": "heading-sans-serif-font-weight",
-      "context": "Title"
+      "type": "purpose",
+      "content": "Alert dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions until an action is selected."
     },
     {
-      "token": "heading-sans-serif-font-style",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Alert dialogs present critical information that must be acknowledged. They appear over the interface and block further interaction until an action is selected."
     },
     {
-      "token": "alert-dialog-title-font-size",
-      "context": "Title"
+      "type": "guideline",
+      "content": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
     },
     {
-      "token": "heading-line-height",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Alert dialogs can include up to three buttons if a secondary outline button label is defined. If no label is defined, the button won’t appear. The secondary outline button should use a short, actionable phrase that clearly communicates the result of selecting the action—typically describing the previous step or an alternative choice."
     },
     {
-      "token": "heading-color",
-      "context": "Title"
+      "type": "guideline",
+      "content": "An alert dialog must include at least one button. The primary action label refers to the rightmost button in the dialog footer for languages that read left to right. It should use a short, actionable phrase that clearly communicates the result of selecting the action—whether that means moving forward or dismissing the dialog."
     },
     {
-      "token": "body-sans-serif-font-family",
-      "context": "Description"
+      "type": "guideline",
+      "content": "Use the appropriate variant based on the context of the message:"
     },
     {
-      "token": "body-sans-serif-font-weight",
-      "context": "Description"
+      "type": "guideline",
+      "content": "Alert dialogs should include a description when available. The description briefly communicates any additional information or context a user needs to make a decision based on the options presented."
     },
     {
-      "token": "body-sans-serif-font-style",
-      "context": "Description"
+      "type": "guideline",
+      "content": "All alert dialogs must have a title. The title appears at the top of the dialog and uses a few words to convey the outcome of what will happen if a user continues with the primary action."
     },
     {
-      "token": "alert-dialog-body-font-size",
-      "context": "Description"
+      "type": "guideline",
+      "content": "When the title and description text are too long for the available horizontal space, they wrap to form another line."
     },
     {
-      "token": "line-height-200",
-      "context": "Description"
+      "type": "guideline",
+      "content": "Alert dialogs can include up to three buttons. When horizontal space is limited, the buttons stack vertically. Buttons should be ordered by ascending importance, with the most critical action placed at the end or bottom of the stack."
     },
     {
-      "token": "body-color",
-      "context": "Description"
+      "type": "guideline",
+      "content": "Alert dialogs are interruptive, so they should be reserved for important information that users must acknowledge before continuing a task or workflow. Use them only when absolutely necessary—not for low-priority notifications or excessive confirmations."
     },
     {
-      "token": "alert-dialog-maximum-width",
-      "context": "Maximum width"
-    },
-    {
-      "token": "alert-dialog-minimum-width",
-      "context": "Minimum width"
-    },
-    {
-      "token": "corner-radius-extra-large-default",
-      "context": "Rounding"
-    },
-    {
-      "token": "spacing-500",
-      "context": "Spacing (edge to content)"
+      "type": "guideline",
+      "content": "Alert dialogs are designed to pause the experience until a decision is made, so only one should appear at a time. Avoid opening an alert dialog from within another. If a situation seems to require a sequence of decisions, consider using a different design pattern."
+    }
+  ],
+  "options": {
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "variant": {
+      "type": "string",
+      "default": "confirmation",
+      "values": [
+        { "value": "confirmation" },
+        { "value": "information" },
+        { "value": "warning" },
+        { "value": "destructive" },
+        { "value": "error" }
+      ]
     },
-    {
-      "token": "spacing-400",
-      "context": "Spacing (edge to content)"
+    "primaryActionLabel": { "type": "string" },
+    "secondaryActionLabel": {
+      "type": "string",
+      "description": "If undefined, this button does not appear."
     },
+    "cancelActionLabel": {
+      "type": "string",
+      "default": "cancel",
+      "description": "If undefined, this button does not appear."
+    }
+  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "heading-sans-serif-font-family", "context": "Title" },
+    { "token": "heading-sans-serif-font-weight", "context": "Title" },
+    { "token": "heading-sans-serif-font-style", "context": "Title" },
+    { "token": "alert-dialog-title-font-size", "context": "Title" },
+    { "token": "heading-line-height", "context": "Title" },
+    { "token": "heading-color", "context": "Title" },
+    { "token": "body-sans-serif-font-family", "context": "Description" },
+    { "token": "body-sans-serif-font-weight", "context": "Description" },
+    { "token": "body-sans-serif-font-style", "context": "Description" },
+    { "token": "alert-dialog-body-font-size", "context": "Description" },
+    { "token": "line-height-200", "context": "Description" },
+    { "token": "body-color", "context": "Description" },
+    { "token": "alert-dialog-maximum-width", "context": "Maximum width" },
+    { "token": "alert-dialog-minimum-width", "context": "Minimum width" },
+    { "token": "corner-radius-extra-large-default", "context": "Rounding" },
+    { "token": "spacing-500", "context": "Spacing (edge to content)" },
+    { "token": "spacing-400", "context": "Spacing (edge to content)" },
     {
       "token": "alert-dialog-top-to-alert-icon",
       "context": "Icon asset (error and warning variants)"
     },
-    {
-      "token": "spacing-300",
-      "context": "Spacing (title to description)"
-    },
+    { "token": "spacing-300", "context": "Spacing (title to description)" },
     {
       "token": "workflow-icon-size-100",
       "context": "Icon (error and warning variants)"
     },
-    {
-      "token": "spacing-100",
-      "context": "Minimum spacing (title to icon)"
-    },
-    {
-      "token": "background-color-layer2",
-      "context": "Background"
-    },
-    {
-      "token": "overlay-color",
-      "context": "Overlay"
-    },
-    {
-      "token": "overlay-opacity",
-      "context": "Overlay"
-    },
-    {
-      "token": "notice-visual-color",
-      "context": "Icon (warning variant)"
-    },
-    {
-      "token": "negative-visual-color",
-      "context": "Icon (error variant)"
-    }
+    { "token": "spacing-100", "context": "Minimum spacing (title to icon)" },
+    { "token": "background-color-layer2", "context": "Background" },
+    { "token": "overlay-color", "context": "Overlay" },
+    { "token": "overlay-opacity", "context": "Overlay" },
+    { "token": "notice-visual-color", "context": "Icon (warning variant)" },
+    { "token": "negative-visual-color", "context": "Icon (error variant)" }
   ],
   "accessibility": {
     "role": "dialog",
@@ -165,16 +125,8 @@
     "focusable": false,
     "keyboardIntents": ["dismiss"],
     "wcag": [
-      {
-        "criterion": "2.4.3",
-        "level": "A",
-        "title": "Focus Order"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "2.4.3", "level": "A", "title": "Focus Order" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }