@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/standard-dialog.json

@@ -9,154 +9,144 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/standard-dialog/"
   },
-  "options": {
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
-    },
-    "hideImage": {
-      "type": "boolean",
-      "default": false,
-      "description": "Optional image to display in dialog."
-    },
-    "size": {
-      "type": "string",
-      "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
-    },
-    "hideCloseButton": {
-      "type": "boolean",
-      "default": false
-    },
-    "footerContent": {
-      "type": "string",
-      "description": "Optional footer content to display in the dialog footer like a checkbox."
-    },
-    "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": [
+  "documentBlocks": [
     {
-      "token": "standard-dialog-maximum-width-small",
-      "context": "Maximum width"
+      "type": "purpose",
+      "content": "Standard dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions until an action is selected."
     },
     {
-      "token": "standard-dialog-maximum-width-medium",
-      "context": "Maximum width"
+      "type": "guideline",
+      "content": "Standard dialogs are containers that appear over the interface to present contextual information, tasks, or workflows. They’re centered on the screen and used for moderately complex actions that require focused attention. Interactions outside the dialog are blocked until it's dismissed or completed."
     },
     {
-      "token": "standard-dialog-maximum-width-large",
-      "context": "Maximum width"
+      "type": "guideline",
+      "content": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
     },
     {
-      "token": "standard-dialog-minimum-width",
-      "context": "Minimum width"
+      "type": "guideline",
+      "content": "Standard 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": "corner-radius-extra-large-default",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "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": "spacing-500",
-      "context": "Spacing (edge to content)"
+      "type": "guideline",
+      "content": "The presence of a close button determines whether a dialog is dismissible."
     },
     {
-      "token": "spacing-400",
-      "context": "Spacing (edge to content)"
+      "type": "guideline",
+      "content": "In both cases, pressing the Escape key should close the dialog and return the page to its previous state. This action should behave the same as clicking a close or cancel button."
     },
     {
-      "token": "spacing-300",
-      "context": "Spacing (title to description)"
+      "type": "guideline",
+      "content": "Standard dialogs are available in three widths:"
     },
     {
-      "token": "spacing-200",
-      "context": "Spacing (edge to close button)"
+      "type": "guideline",
+      "content": "Dialogs automatically scale down to 90% of the screen width on smaller viewports. Height is flexible and adjusts to fit the content."
     },
     {
-      "token": "background-color-layer2",
-      "context": "Background"
+      "type": "guideline",
+      "content": "Standard dialogs can include a full-bleed cover image at the top. Dialogs with a cover image should not be dismissible and rely on buttons in the footer area to close the dialog."
     },
     {
-      "token": "overlay-color",
-      "context": "Overlay"
+      "type": "guideline",
+      "content": "Standard dialogs can include an optional description. Use the description to briefly provide additional context or information that helps users make an informed decision based on the available actions."
     },
     {
-      "token": "overlay-opacity",
-      "context": "Overlay"
+      "type": "guideline",
+      "content": "All standard dialogs must include a title. The title appears at the top of the dialog and should briefly describe the expected outcome if the user proceeds with the primary action. If a cover image is shown, the title will appear below it."
     },
     {
-      "token": "title-sans-serif-font-family",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Standard dialogs appear in the center of the screen."
     },
     {
-      "token": "title-sans-serif-font-weight",
-      "context": "Title"
+      "type": "guideline",
+      "content": "When the title and description text are too long for the available horizontal space, they wrap to form another line."
     },
     {
-      "token": "title-sans-serif-font-style",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Standard 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": "standard-dialog-title-font-size",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Avoid using a dismissible dialog when the user needs to confirm an action or make a decision. Instead, use a dismissible dialog for information that is optional or nice to know—content that can be quickly dismissed without requiring user action."
     },
     {
-      "token": "title-line-height",
-      "context": "Title"
+      "type": "guideline",
+      "content": "A dismissible dialog should not include buttons in the footer. Instead, the dialog is dismissed by clicking the close button or the background overlay."
     },
     {
-      "token": "heading-color",
-      "context": "Title"
+      "type": "guideline",
+      "content": "Most dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is “Delete conversation,” the primary action button label should be “Delete.”"
+    }
+  ],
+  "options": {
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "hideImage": {
+      "type": "boolean",
+      "default": false,
+      "description": "Optional image to display in dialog."
     },
-    {
-      "token": "body-sans-serif-font-family",
-      "context": "Description"
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
-    {
-      "token": "body-sans-serif-font-weight",
-      "context": "Description"
+    "hideCloseButton": { "type": "boolean", "default": false },
+    "footerContent": {
+      "type": "string",
+      "description": "Optional footer content to display in the dialog footer like a checkbox."
     },
-    {
-      "token": "body-sans-serif-font-style",
-      "context": "Description"
+    "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": "standard-dialog-body-font-size",
-      "context": "Description"
+      "token": "standard-dialog-maximum-width-small",
+      "context": "Maximum width"
     },
     {
-      "token": "line-height-200",
-      "context": "Description"
+      "token": "standard-dialog-maximum-width-medium",
+      "context": "Maximum width"
     },
     {
-      "token": "body-color",
-      "context": "Description"
-    }
+      "token": "standard-dialog-maximum-width-large",
+      "context": "Maximum width"
+    },
+    { "token": "standard-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": "spacing-300", "context": "Spacing (title to description)" },
+    { "token": "spacing-200", "context": "Spacing (edge to close button)" },
+    { "token": "background-color-layer2", "context": "Background" },
+    { "token": "overlay-color", "context": "Overlay" },
+    { "token": "overlay-opacity", "context": "Overlay" },
+    { "token": "title-sans-serif-font-family", "context": "Title" },
+    { "token": "title-sans-serif-font-weight", "context": "Title" },
+    { "token": "title-sans-serif-font-style", "context": "Title" },
+    { "token": "standard-dialog-title-font-size", "context": "Title" },
+    { "token": "title-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": "standard-dialog-body-font-size", "context": "Description" },
+    { "token": "line-height-200", "context": "Description" },
+    { "token": "body-color", "context": "Description" }
   ],
   "accessibility": {
     "role": "dialog",
@@ -164,16 +154,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" }
     ]
   }
 }

package/components/standard-panel.json

@@ -9,75 +9,127 @@
     "category": "containers",
     "documentationUrl": "https://spectrum.adobe.com/page/standard-panel/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Standard Panels provide a flexible container for grouping related content and actions."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard panels are containers used to group related content or tools in a consistent layout. They support a range of sizes, densities, and configurations to fit different use cases across products. Panels can be placed alongside primary content to provide supporting controls or information."
+    },
+    {
+      "type": "guideline",
+      "content": "Determines whether the close button is visible in the top right corner of the panel. Set to true to hide the button when panel dismissal is not required."
+    },
+    {
+      "type": "guideline",
+      "content": "Determines whether the gripper is visible at the top center of the panel. Set to true to hide the gripper when panel dragging is not required."
+    },
+    {
+      "type": "guideline",
+      "content": "Specifies the visual style of the panel. Use primary for panels that require high emphasis with the primary background color, and secondary for panels that require lower emphasis."
+    },
+    {
+      "type": "guideline",
+      "content": "There are three density options for standard panel: compact, regular, and spacious. Regular is the default and recommended for layouts in creative tools, marketing, or analytics products. Use spacious for lighter-weight web experiences, such as Adobe Express. Use compact for complex professional tools where maximizing screen space is essential."
+    },
+    {
+      "type": "guideline",
+      "content": "Defines the panel’s layout behavior. Use anchored when the panel is docked alongside other panels on the same surface. Use floating when the panel is undocked and positioned above the application surface. Use dragged for the panel’s appearance while it is being moved."
+    },
+    {
+      "type": "guideline",
+      "content": "Controls whether the panel content is organized into sections. When set to true, the panel displays content without structural segmentation, allowing full customization based on product or experience needs. When set to false, the panel uses an embedded accordion component to divide content into smaller, structured segments, each customizable while maintaining a standardized layout for clarity and consistency."
+    },
+    {
+      "type": "guideline",
+      "content": "Determines whether the panel title is visible at the top of the panel."
+    },
+    {
+      "type": "guideline",
+      "content": "Determines whether the back button is visible at the top of the panel, positioned to the left of the panel title."
+    },
+    {
+      "type": "guideline",
+      "content": "Determines the size of the panel title. Options are small and medium. Use medium to establish visual hierarchy. Use small for compact layouts or secondary panels."
+    },
+    {
+      "type": "guideline",
+      "content": "A standard panel can sometimes be dragged and rearranged, or undocked to become a floating panel. In this case, display the gripper at the top of the panel, then click and drag to detach it."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard panel uses an Accordion subcomponent to manage collapsible content sections. It can be configured to allow multiple sections to expand independently or restrict expansion to a single section at a time."
+    },
+    {
+      "type": "guideline",
+      "content": "A panel can scroll internally, and a group of panels can also scroll as a unit. Panels always scroll independently from the canvas or page content. The header and footer areas of a panel can remain fixed during scrolling."
+    },
+    {
+      "type": "guideline",
+      "content": "When users scroll in the outer areas of a panel — such as the header, footer, or sides — the entire panel group scrolls. When scrolling within the inner content area, only the panel’s content scrolls, while the header and footer (if present) stay in place."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard panel supports three widths: small, medium, and large. The small size is best for a single column of items, such as swatches or navigation elements. Medium is the default for most scenarios and works well for tools that interact with a canvas area, including filters, sliders, text boxes, or swatches. The large size is ideal for panels where users browse or search for content, such as images, assets, cards, or templates."
+    },
+    {
+      "type": "guideline",
+      "content": "The panel title can act as a label for the fields in the panel, if the design is reviewed and approved by an accessibility expert."
+    },
+    {
+      "type": "guideline",
+      "content": "Use a single panel density across a product to maintain visual consistency. Mixing densities within the same experience is not recommended."
+    },
+    {
+      "type": "guideline",
+      "content": "The choice of density often depends on context, user preference, and device type. Compact saves space in complex professional tools, regular balances usability across a range of products, and spacious improves comfort in lighter-weight experiences."
+    },
+    {
+      "type": "guideline",
+      "content": "Anchored panels are docked in fixed areas of the workspace and grouped with other panels on the same surface. They cannot move freely outside their designated location unless undocked. This layout helps maintain a consistent and organized workspace, making it easier for users to access essential tools without obstructing the canvas or working area. A common example is the layers panel docked to the right side of Photoshop."
+    },
+    {
+      "type": "guideline",
+      "content": "Floating panels are undocked and can be moved freely anywhere on the screen, independent of the main workspace. This style offers flexibility, especially when working across multiple monitors or when isolating a panel improves focus. A common example is a Properties panel floating near artwork in Illustrator for quick access."
+    },
+    {
+      "type": "guideline",
+      "content": "Dragging refers to manually moving a panel by clicking and dragging the gripper. This interaction allows users to reposition a panel within the workspace. A dragged panel can be docked into a new location (anchored) or left to float independently. This behavior supports workspace customization, helping users tailor panel placement to fit their workflow. For example, dragging the Tools panel from the left side of Photoshop to float next to the canvas."
+    }
+  ],
   "options": {
     "container": {
       "type": "string",
       "default": "anchored",
       "values": [
-        {
-          "value": "anchored"
-        },
-        {
-          "value": "floating"
-        },
-        {
-          "value": "dragged"
-        }
+        { "value": "anchored" },
+        { "value": "floating" },
+        { "value": "dragged" }
       ]
     },
-    "label": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
-    },
-    "value": {
-      "type": "string"
-    },
+    "label": { "type": "string" },
+    "description": { "type": "string" },
+    "value": { "type": "string" },
     "density": {
       "type": "string",
       "default": "regular",
       "values": [
-        {
-          "value": "compact"
-        },
-        {
-          "value": "regular"
-        },
-        {
-          "value": "spacious"
-        }
+        { "value": "compact" },
+        { "value": "regular" },
+        { "value": "spacious" }
       ]
     },
     "style": {
       "type": "string",
       "default": "primary",
-      "values": [
-        {
-          "value": "primary"
-        },
-        {
-          "value": "secondary"
-        }
-      ]
-    },
-    "hideGripper": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "primary" }, { "value": "secondary" }]
     },
-    "hideCloseButton": {
-      "type": "boolean",
-      "default": false
-    },
-    "hideDivider": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "hideGripper": { "type": "boolean", "default": false },
+    "hideCloseButton": { "type": "boolean", "default": false },
+    "hideDivider": { "type": "boolean", "default": false }
   },
-  "accessibility": {
-    "focusable": false
-  }
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "accessibility": { "focusable": false }
 }