@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/close-button.json

@@ -9,79 +9,66 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/close-button/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "The close button is used inside of other components, like a toast or an action bar, for closing or dismissing its parent component."
+    },
+    {
+      "type": "guideline",
+      "content": "A close button in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later."
+    },
+    {
+      "type": "guideline",
+      "content": "Use this option when a close button needs to be placed on top of a color background or visual. Static color close buttons are available in black or white, regardless of color theme."
+    },
+    {
+      "type": "guideline",
+      "content": "Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of color theme. Make sure that the background and the close button color meet the minimum color contrast ratio."
+    },
+    {
+      "type": "guideline",
+      "content": "The icon inside of the close button comes in two options: regular and large. These scale up and down for each close button size. This is a cross UI icon, not a workflow icon or the letter “x.”"
+    },
+    {
+      "type": "guideline",
+      "content": "Close buttons come 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; they should be used to create a hierarchy of importance within the page."
+    },
+    {
+      "type": "guideline",
+      "content": "A close button can be navigated using a keyboard. The keyboard focus state takes the close button’s visual hover state and adds a ring to the button in focus."
+    }
+  ],
   "options": {
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
-    "iconSize": {
-      "type": "string"
-    },
+    "iconSize": { "type": "string" },
     "staticColor": {
       "type": "string",
       "description": "Static color must not be set for the default version of this component.",
-      "values": [
-        {
-          "value": "white"
-        },
-        {
-          "value": "black"
-        }
-      ]
+      "values": [{ "value": "white" }, { "value": "black" }]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
+    "isDisabled": { "type": "boolean", "default": false }
   },
   "states": [
-    {
-      "name": "hover",
-      "trigger": "interaction"
-    },
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "component-height-75",
-      "context": "Button size"
-    },
-    {
-      "token": "component-height-100",
-      "context": "Button size"
-    },
-    {
-      "token": "component-height-200",
-      "context": "Button size"
-    },
-    {
-      "token": "component-height-300",
-      "context": "Button size"
-    },
+    { "token": "component-height-75", "context": "Button size" },
+    { "token": "component-height-100", "context": "Button size" },
+    { "token": "component-height-200", "context": "Button size" },
+    { "token": "component-height-300", "context": "Button size" },
     {
       "token": "component-size-difference-down",
       "context": "Button size (down)"
@@ -94,58 +81,19 @@
       "token": "component-size-minimum-perspective-down",
       "context": "Button size (down)"
     },
-    {
-      "token": "cross-icon-size-200",
-      "context": "Cross icon size"
-    },
-    {
-      "token": "cross-icon-size-300",
-      "context": "Cross icon size"
-    },
-    {
-      "token": "cross-icon-size-400",
-      "context": "Cross icon size"
-    },
-    {
-      "token": "cross-icon-size-500",
-      "context": "Cross icon size"
-    },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus ring "
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus ring "
-    },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Cross icon"
-    },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Cross icon"
-    },
-    {
-      "token": "neutral-content-color-down",
-      "context": "Cross icon"
-    },
-    {
-      "token": "neutral-content-color-key-focus",
-      "context": "Cross icon"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Cross icon"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "gray-100",
-      "context": "Background "
-    },
+    { "token": "cross-icon-size-200", "context": "Cross icon size" },
+    { "token": "cross-icon-size-300", "context": "Cross icon size" },
+    { "token": "cross-icon-size-400", "context": "Cross icon size" },
+    { "token": "cross-icon-size-500", "context": "Cross icon size" },
+    { "token": "focus-indicator-thickness", "context": "Focus ring " },
+    { "token": "focus-indicator-gap", "context": "Focus ring " },
+    { "token": "neutral-content-color-default", "context": "Cross icon" },
+    { "token": "neutral-content-color-hover", "context": "Cross icon" },
+    { "token": "neutral-content-color-down", "context": "Cross icon" },
+    { "token": "neutral-content-color-key-focus", "context": "Cross icon" },
+    { "token": "disabled-content-color", "context": "Cross icon" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "gray-100", "context": "Background " },
     {
       "token": "transparent-white-800",
       "context": "Cross icon (static white)"
@@ -182,10 +130,7 @@
       "token": "static-black-focus-indicator-color",
       "context": "Focus ring (static black) "
     },
-    {
-      "token": "transparent-black-100",
-      "context": "Background (static black)"
-    }
+    { "token": "transparent-black-100", "context": "Background (static black)" }
   ],
   "accessibility": {
     "role": "button",
@@ -193,16 +138,8 @@
     "focusable": true,
     "keyboardIntents": ["activate"],
     "wcag": [
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }

package/components/coach-indicator.json

@@ -9,75 +9,77 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/coach-indicator/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Coach indicators help guide users through interfaces by highlighting important areas or features during onboarding and feature discovery."
+    },
+    {
+      "type": "guideline",
+      "content": "If not set to white, the coach indicator uses the default color."
+    },
+    {
+      "type": "guideline",
+      "content": "The rounding of the indicator is determined by the shape of the object that it is highlighting. There are three types of rounding for coach indicators: no rounding, default rounding, and full rounding."
+    },
+    {
+      "type": "guideline",
+      "content": "No rounding means that there is no rounding on the object being indicated. In this case, a 6 px border radius rounding is applied to the coach indicator."
+    },
+    {
+      "type": "guideline",
+      "content": "Default rounding happens when an object has its own rounding, but isn’t fully rounded. In this case, the coach indicator should have the same rounding of that object with a 2 px gap."
+    },
+    {
+      "type": "guideline",
+      "content": "Full rounding occurs when an object already has a rounded style that gives it a pill shape (e.g., a button). In this case, the coach indicator is also rounded."
+    },
+    {
+      "type": "guideline",
+      "content": "The animation is always on the coach indicator. When an implementation is unable to animate the coach indicator, it can use a non-animated version to provide a similar experience."
+    },
+    {
+      "type": "guideline",
+      "content": "Coach indicators adopt the shape of the object they highlight. A 2 px space separates the indicator from the object’s placement area, creating padding on all sides."
+    },
+    {
+      "type": "guideline",
+      "content": "When an indicator needs to be placed on top of a visual, use the static white option. Static white does not change values depending upon the color theme."
+    },
+    {
+      "type": "guideline",
+      "content": "Coach indicators are typically paired with coach marks to create accessible user onboarding experiences. When using coach indicators:"
+    }
+  ],
   "options": {
     "cornerRounding": {
       "type": "string",
       "values": [
-        {
-          "value": "none"
-        },
-        {
-          "value": "corner-radius-75"
-        },
-        {
-          "value": "corner-radius-100"
-        },
-        {
-          "value": "corner-radius-200"
-        },
-        {
-          "value": "corner-radius-300"
-        },
-        {
-          "value": "corner-radius-400"
-        },
-        {
-          "value": "corner-radius-500"
-        },
-        {
-          "value": "corner-radius-600"
-        },
-        {
-          "value": "corner-radius-700"
-        },
-        {
-          "value": "corner-radius-800"
-        },
-        {
-          "value": "full"
-        }
+        { "value": "none" },
+        { "value": "corner-radius-75" },
+        { "value": "corner-radius-100" },
+        { "value": "corner-radius-200" },
+        { "value": "corner-radius-300" },
+        { "value": "corner-radius-400" },
+        { "value": "corner-radius-500" },
+        { "value": "corner-radius-600" },
+        { "value": "corner-radius-700" },
+        { "value": "corner-radius-800" },
+        { "value": "full" }
       ]
     },
     "staticColor": {
       "type": "string",
       "description": "If not set to white, the coach indicator uses the default color.",
-      "values": [
-        {
-          "value": "white"
-        }
-      ]
+      "values": [{ "value": "white" }]
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "coach-indicator-collapsed-ring-thickness",
-      "context": "Ring"
-    },
-    {
-      "token": "coach-indicator-expanded-ring-thickness",
-      "context": "Ring"
-    },
-    {
-      "token": "coach-indicator-collapsed-gap",
-      "context": "Ring"
-    },
-    {
-      "token": "coach-indicator-expanded-gap",
-      "context": "Ring"
-    },
+    { "token": "coach-indicator-collapsed-ring-thickness", "context": "Ring" },
+    { "token": "coach-indicator-expanded-ring-thickness", "context": "Ring" },
+    { "token": "coach-indicator-collapsed-gap", "context": "Ring" },
+    { "token": "coach-indicator-expanded-gap", "context": "Ring" },
     {
       "token": "coach-indicator-collapsed-ring-rounding-increment",
       "context": "Rounding"
@@ -86,20 +88,9 @@
       "token": "coach-indicator-expanded-ring-rounding-increment",
       "context": "Rounding"
     },
-    {
-      "token": "coach-indicator-color",
-      "context": "Indicator (Default)"
-    },
-    {
-      "token": "coach-indicator-opacity",
-      "context": "Indicator (Default)"
-    },
-    {
-      "token": "white",
-      "context": "Indicator (Static white)"
-    }
+    { "token": "coach-indicator-color", "context": "Indicator (Default)" },
+    { "token": "coach-indicator-opacity", "context": "Indicator (Default)" },
+    { "token": "white", "context": "Indicator (Static white)" }
   ],
-  "accessibility": {
-    "focusable": false
-  }
+  "accessibility": { "focusable": false }
 }

package/components/coach-mark.json

@@ -9,13 +9,75 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/coach-mark/"
   },
-  "options": {
-    "title": {
-      "type": "string"
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Coach marks provide contextual guidance to users by highlighting specific interface elements."
+    },
+    {
+      "type": "guideline",
+      "content": "Coach marks are temporary messages that provide guidance during new or unfamiliar experiences. They can appear as a single message or be sequenced into a tour."
+    },
+    {
+      "type": "guideline",
+      "content": "Actions is an area for certain configurations of a Coach mark and can contain an action menu, keyboard shortcut, or both. When both are enabled, the component layout adjusts to display the keyboard shortcut below the title."
+    },
+    {
+      "type": "guideline",
+      "content": "Coach marks can contain images or videos that relate to their content, such as demonstrations of gestures, the feature being used, or illustrations."
+    },
+    {
+      "type": "guideline",
+      "content": "Coach marks must include a title. Titles appear in bold at the top of the coach mark and use a few words to convey its purpose."
+    },
+    {
+      "type": "guideline",
+      "content": "All coach marks must have a description. Descriptions briefly communicate the information and context needed to educate a user about a new or unfamiliar product experience."
+    },
+    {
+      "type": "guideline",
+      "content": "When the text of a header or description is too long for the available horizontal space, it wraps to form another line. The steps in a tour are always shown in full and never wrap or truncate."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, the step counter appears next to the title. If an action menu is also used, the keyboard shortcut appears below the title instead."
+    },
+    {
+      "type": "guideline",
+      "content": "Choose a width for coach marks that is spacious enough to accommodate all of their content. In a tour that includes several coach marks, keep the width consistent across each one."
+    },
+    {
+      "type": "guideline",
+      "content": "The “Previous” button should always be a quiet secondary button."
+    },
+    {
+      "type": "guideline",
+      "content": "The “Skip tour” and “Restart tour” options should only be available within the more actions menu."
+    },
+    {
+      "type": "guideline",
+      "content": "Titles help with way finding and setting context for what a user is learning about. Summarize the description of the coach mark in a few concise words. In a tour, use a different title for each coach mark to keep users active and engaged. Avoid repeating the title in the description."
     },
-    "description": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "Coach marks are meant to provide quick overviews of functionality. Content should be at least a few words, but no more than a few sentences."
+    },
+    {
+      "type": "guideline",
+      "content": "The primary action should be brief and consistent. Use \"OK\" for a single coach mark. Within a tour, use “Next” for all but the last step, and “Finish” for the last step. Don’t use different primary action names for every step in a tour."
+    },
+    {
+      "type": "guideline",
+      "content": "When a part of the tour is dependent on a user taking an action, it’s okay to put the primary button in the disabled state as long as the user has a way to exit the tour. For a one-off coach mark, this means the primary button should remain as a route to dismiss. In a tour, it’s recommended to have the more actions menu present."
     },
+    {
+      "type": "guideline",
+      "content": "When part of the tour is dependent on a user action, don't force users to confirm that they've taken that action."
+    }
+  ],
+  "options": {
+    "title": { "type": "string" },
+    "description": { "type": "string" },
     "hideImage": {
       "type": "boolean",
       "default": false,
@@ -49,22 +111,11 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "coach-mark-width",
-      "context": "Width"
-    },
-    {
-      "token": "coach-mark-minimum-width",
-      "context": "Width"
-    },
-    {
-      "token": "coach-mark-maximum-width",
-      "context": "Width"
-    },
+    { "token": "coach-mark-width", "context": "Width" },
+    { "token": "coach-mark-minimum-width", "context": "Width" },
+    { "token": "coach-mark-maximum-width", "context": "Width" },
     {
       "token": "coach-mark-edge-to-content",
       "context": "Spacing (top/bottom/start/end edge to text)"
@@ -81,89 +132,34 @@
       "token": "coach-mark-pagination-text-to-bottom-edge",
       "context": "Spacing (pagination to bottom)"
     },
-    {
-      "token": "coach-mark-media-minimum-height",
-      "context": "Media (16:9)"
-    },
-    {
-      "token": "coach-mark-media-height",
-      "context": "Media (4:3)"
-    },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (action button to menu)"
-    },
-    {
-      "token": "title-sans-serif-font-family",
-      "context": "Title"
-    },
-    {
-      "token": "title-sans-serif-font-weight",
-      "context": "Title"
-    },
-    {
-      "token": "title-serif-font-style",
-      "context": "Title"
-    },
-    {
-      "token": "coach-mark-title-font-size",
-      "context": "Title"
-    },
-    {
-      "token": "title-line-height",
-      "context": "Title"
-    },
-    {
-      "token": "body-sans-serif-font-family",
-      "context": "Body"
-    },
-    {
-      "token": "body-sans-serif-font-weight",
-      "context": "Body"
-    },
-    {
-      "token": "body-serif-font-style",
-      "context": "Body"
-    },
-    {
-      "token": "coach-mark-body-font-size",
-      "context": "Body"
-    },
-    {
-      "token": "line-height-200",
-      "context": "Body"
-    },
-    {
-      "token": "medium-font-weight",
-      "context": "Pagination"
-    },
+    { "token": "coach-mark-media-minimum-height", "context": "Media (16:9)" },
+    { "token": "coach-mark-media-height", "context": "Media (4:3)" },
+    { "token": "spacing-100", "context": "Spacing (action button to menu)" },
+    { "token": "title-sans-serif-font-family", "context": "Title" },
+    { "token": "title-sans-serif-font-weight", "context": "Title" },
+    { "token": "title-serif-font-style", "context": "Title" },
+    { "token": "coach-mark-title-font-size", "context": "Title" },
+    { "token": "title-line-height", "context": "Title" },
+    { "token": "body-sans-serif-font-family", "context": "Body" },
+    { "token": "body-sans-serif-font-weight", "context": "Body" },
+    { "token": "body-serif-font-style", "context": "Body" },
+    { "token": "coach-mark-body-font-size", "context": "Body" },
+    { "token": "line-height-200", "context": "Body" },
+    { "token": "medium-font-weight", "context": "Pagination" },
     {
       "token": "coach-mark-pagination-body-font-size",
       "context": "Pagination"
     },
-    {
-      "token": "heading-color",
-      "context": "Color"
-    },
-    {
-      "token": "body-color",
-      "context": "Color"
-    },
-    {
-      "token": "coach-mark-pagination-color",
-      "context": "Color"
-    }
+    { "token": "heading-color", "context": "Color" },
+    { "token": "body-color", "context": "Color" },
+    { "token": "coach-mark-pagination-color", "context": "Color" }
   ],
   "accessibility": {
     "intents": ["dismiss"],
     "focusable": true,
     "keyboardIntents": ["dismiss"],
     "wcag": [
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }