@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/illustrated-message.json

@@ -9,6 +9,96 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/illustrated-message/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "An illustrated message displays an illustration with a short title and description, often used for empty states or error states."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "A clear title for the description section in an illustrated message"
+    },
+    {
+      "type": "guideline",
+      "content": "Orientation affects how users perceive and interact with content. Illustrated message layout can be horizontal or vertical."
+    },
+    {
+      "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": "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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": "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."
+    }
+  ],
   "options": {
     "illustration": {
       "type": "string",
@@ -18,30 +108,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",
@@ -60,9 +133,7 @@
       "description": "Label for the secondary action button. If undefined, no secondary action is shown."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
     {
       "token": "illustrated-message-vertical-maximum-width",
@@ -72,14 +143,8 @@
       "token": "illustrated-message-horizontal-maximum-width",
       "context": "Maximum width (Horizontal variant)"
     },
-    {
-      "token": "spacing-200",
-      "context": "Spacing (Illustration to heading)"
-    },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (Illustration to heading)"
-    },
+    { "token": "spacing-200", "context": "Spacing (Illustration to heading)" },
+    { "token": "spacing-100", "context": "Spacing (Illustration to heading)" },
     {
       "token": "spacing-75",
       "context": "Spacing (Heading to description - vertical)"
@@ -88,22 +153,10 @@
       "token": "spacing-300",
       "context": "Spacing (Description to action - vertical)"
     },
-    {
-      "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": "title-line-height",
-      "context": "Title"
-    },
+    { "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": "title-line-height", "context": "Title" },
     {
       "token": "illustrated-message-small-title-font-size",
       "context": "Title"
@@ -128,22 +181,10 @@
       "token": "illustrated-message-large-cjk-title-font-size",
       "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": "line-height-200",
-      "context": "Description"
-    },
+    { "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": "line-height-200", "context": "Description" },
     {
       "token": "illustrated-message-small-body-font-size",
       "context": "Description"
@@ -160,16 +201,8 @@
       "token": "neutral-content-color-default",
       "context": "Illustration color"
     },
-    {
-      "token": "heading-color",
-      "context": "Heading color"
-    },
-    {
-      "token": "body-color",
-      "context": "Description color"
-    }
+    { "token": "heading-color", "context": "Heading color" },
+    { "token": "body-color", "context": "Description color" }
   ],
-  "accessibility": {
-    "focusable": false
-  }
+  "accessibility": { "focusable": false }
 }

package/components/in-line-alert.json

@@ -9,29 +9,44 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/in-line-alert/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "In-line alerts display a non-modal message associated with objects in a view. These are often used in form validation, providing a place to aggregate feedback related to multiple fields."
+    },
+    {
+      "type": "guideline",
+      "content": "In-line alerts display non-modal messages connected to elements in a view. They’re often used in forms to show validation feedback across multiple fields."
+    },
+    {
+      "type": "guideline",
+      "content": "An in-line alert can have up to one button. This label should be kept concise, and it should only be used when there’s a direct action available that is related to the in-line alert text."
+    },
+    {
+      "type": "guideline",
+      "content": "Heading is optional for in-line alerts."
+    },
+    {
+      "type": "guideline",
+      "content": "The outline style is the default for in-line alerts."
+    },
+    { "type": "guideline", "content": "There are five semantic variants:" },
+    {
+      "type": "guideline",
+      "content": "When the title of an in-line alert is too long for the available horizontal space, it wraps to form another line. The optional icon in the top-right corner stays aligned to the top."
+    }
+  ],
   "options": {
     "variant": {
       "type": "string",
       "default": "neutral",
       "values": [
-        {
-          "value": "neutral"
-        },
-        {
-          "value": "informative"
-        },
-        {
-          "value": "positive"
-        },
-        {
-          "value": "notice"
-        },
-        {
-          "value": "negative"
-        },
-        {
-          "value": "accent"
-        }
+        { "value": "neutral" },
+        { "value": "informative" },
+        { "value": "positive" },
+        { "value": "notice" },
+        { "value": "negative" },
+        { "value": "accent" }
       ]
     },
     "style": {
@@ -39,15 +54,9 @@
       "default": "outline",
       "description": "The visual style of the alert.",
       "values": [
-        {
-          "value": "bold"
-        },
-        {
-          "value": "subtle"
-        },
-        {
-          "value": "outline"
-        }
+        { "value": "bold" },
+        { "value": "subtle" },
+        { "value": "outline" }
       ]
     },
     "href": {
@@ -63,50 +72,27 @@
       "description": "If undefined, this button does not appear."
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "border-width-200",
-      "context": "Border "
-    },
-    {
-      "token": "corner-radius-700",
-      "context": "Rounding"
-    },
-    {
-      "token": "workflow-icon-size-100",
-      "context": "Icon"
-    },
-    {
-      "token": "in-line-alert-minimum-width",
-      "context": "Minimum width"
-    },
+    { "token": "border-width-200", "context": "Border " },
+    { "token": "corner-radius-700", "context": "Rounding" },
+    { "token": "workflow-icon-size-100", "context": "Icon" },
+    { "token": "in-line-alert-minimum-width", "context": "Minimum width" },
     {
       "token": "spacing-300",
       "context": "Spacing (Top/Bottom/Start/End edge to Content)"
     },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (Title to Description) "
-    },
+    { "token": "spacing-100", "context": "Spacing (Title to Description) " },
     {
       "token": "spacing-200",
       "context": "Spacing (Description to Link, Description to Button, Link to Button) "
     },
-    {
-      "token": "component-height-50",
-      "context": "Minimum title area height"
-    },
+    { "token": "component-height-50", "context": "Minimum title area height" },
     {
       "token": "heading-color",
       "context": "Title and Description (Border fill)"
     },
-    {
-      "token": "body-color",
-      "context": "Title and Description (Border fill)"
-    },
+    { "token": "body-color", "context": "Title and Description (Border fill)" },
     {
       "token": "background-layer-2-color",
       "context": "Background (Border fill)"
@@ -151,10 +137,7 @@
       "token": "neutral-subtle-background-color-default",
       "context": "Background and Icon (Subtle fill, Neutral)"
     },
-    {
-      "token": "white",
-      "context": "Title and Description (Bold fill)"
-    },
+    { "token": "white", "context": "Title and Description (Bold fill)" },
     {
       "token": "black",
       "context": "Title and Description (Bold fill, Notice)"
@@ -191,14 +174,8 @@
       "token": "heading-sans-serif-font-style",
       "context": "Title and Description"
     },
-    {
-      "token": "heading-size-xxs",
-      "context": "Title and Description"
-    },
-    {
-      "token": "heading-line-height",
-      "context": "Title and Description"
-    },
+    { "token": "heading-size-xxs", "context": "Title and Description" },
+    { "token": "heading-line-height", "context": "Title and Description" },
     {
       "token": "body-sans-serif-font-family",
       "context": "Title and Description"
@@ -211,23 +188,13 @@
       "token": "body-sans-serif-font-style",
       "context": "Title and Description"
     },
-    {
-      "token": "body-size-s",
-      "context": "Title and Description"
-    },
-    {
-      "token": "body-line-height",
-      "context": "Title and Description"
-    }
+    { "token": "body-size-s", "context": "Title and Description" },
+    { "token": "body-line-height", "context": "Title and Description" }
   ],
   "accessibility": {
     "focusable": false,
     "wcag": [
-      {
-        "criterion": "4.1.3",
-        "level": "AA",
-        "title": "Status Messages"
-      }
+      { "criterion": "4.1.3", "level": "AA", "title": "Status Messages" }
     ]
   }
 }

package/components/link.json

@@ -9,94 +9,89 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/link/"
   },
-  "options": {
-    "variant": {
-      "type": "string",
-      "default": "primary",
-      "values": [
-        {
-          "value": "primary"
-        },
-        {
-          "value": "secondary"
-        }
-      ]
-    },
-    "isQuiet": {
-      "type": "boolean",
-      "default": false
-    },
-    "staticColor": {
-      "type": "string",
-      "description": "Static color must not be set for the default version of this component.",
-      "values": [
-        {
-          "value": "white"
-        },
-        {
-          "value": "black"
-        }
-      ]
-    }
-  },
-  "states": [
+  "documentBlocks": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "purpose",
+      "content": "Links allow users to navigate to a different location. They can be presented inside a paragraph or as standalone text."
     },
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Links provide navigation to a different location. They can appear within a paragraph or as standalone text."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
+      "type": "guideline",
+      "content": "Use the static color option when a link needs to be placed on top of a color background or visual. Static color links are available in black or white, regardless of color theme. They can also be placed on top of a custom background that isn’t part of a Spectrum color theme."
+    },
     {
-      "token": "accent-content-color-default",
-      "context": "Text (primary)"
+      "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 link color meet the minimum color contrast ratio."
     },
     {
-      "token": "accent-content-color-hover",
-      "context": "Text (primary)"
+      "type": "guideline",
+      "content": "All links can have a quiet style, without an underline. This style should only be used when the placement and context of the link is explicit enough that a visible underline isn’t necessary."
     },
     {
-      "token": "accent-content-color-down",
-      "context": "Text (primary)"
+      "type": "guideline",
+      "content": "The variant property defines the visual style of a link and includes two options: primary and secondary."
     },
     {
-      "token": "accent-content-color-key-focus",
-      "context": "Text (primary)"
+      "type": "guideline",
+      "content": "The primary variant is the default style and displays the link in Spectrum blue. It is intended to draw attention to the link and is suitable when the blue color complements the surrounding content without being overwhelming."
     },
     {
-      "token": "neutral-content-color-default",
-      "context": "Text (secondary)"
+      "type": "guideline",
+      "content": "The secondary variant uses the same gray color as the surrounding paragraph text. Its subdued appearance is ideal for scenarios where multiple links are present in a block of text and the primary variant would be too visually dominant."
     },
     {
-      "token": "neutral-content-color-hover",
-      "context": "Text (secondary)"
+      "type": "guideline",
+      "content": "Links are for usage in body copy and are not appropriate in titles. Consider using a different component if you're looking for a larger or more prominent call to action, such as a button."
     },
     {
-      "token": "neutral-content-color-down",
-      "context": "Text (secondary)"
+      "type": "guideline",
+      "content": "Be mindful of link placement and language, and create experiences that are inclusive of users navigating with screen readers. Screen readers pull a list of links — only the link text, and not including other surrounding language — to determine the content of the page."
     },
     {
-      "token": "neutral-content-color-key-focus",
-      "context": "Text (secondary)"
+      "type": "guideline",
+      "content": "People using screen readers may tab between links without getting the text in between, so very generic link wording like “learn more” or “click here” doesn’t communicate any context from elsewhere in the experience. Identify the target of each link directly in the link text to communicate context and set clear expectations about where the link will go."
     },
     {
-      "token": "white",
-      "context": "Text (white)"
+      "type": "guideline",
+      "content": "Quiet links are less accessible, so don't use them for links that are critical to an experience. Quiet links are commonly used in website footers, where there are several lists of links that are shortcuts to other pages."
+    }
+  ],
+  "options": {
+    "variant": {
+      "type": "string",
+      "default": "primary",
+      "values": [{ "value": "primary" }, { "value": "secondary" }]
     },
+    "isQuiet": { "type": "boolean", "default": false },
+    "staticColor": {
+      "type": "string",
+      "description": "Static color must not be set for the default version of this component.",
+      "values": [{ "value": "white" }, { "value": "black" }]
+    }
+  },
+  "states": [
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "accent-content-color-default", "context": "Text (primary)" },
+    { "token": "accent-content-color-hover", "context": "Text (primary)" },
+    { "token": "accent-content-color-down", "context": "Text (primary)" },
+    { "token": "accent-content-color-key-focus", "context": "Text (primary)" },
+    { "token": "neutral-content-color-default", "context": "Text (secondary)" },
+    { "token": "neutral-content-color-hover", "context": "Text (secondary)" },
+    { "token": "neutral-content-color-down", "context": "Text (secondary)" },
     {
-      "token": "black",
-      "context": "Text (black)"
+      "token": "neutral-content-color-key-focus",
+      "context": "Text (secondary)"
     },
+    { "token": "white", "context": "Text (white)" },
+    { "token": "black", "context": "Text (black)" },
     {
       "token": "default-font-family",
       "context": "Standalone variant, Default style"
@@ -133,18 +128,9 @@
       "token": "regular-font-weight",
       "context": "Inline variant, Default style"
     },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus ring"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus ring"
-    }
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "focus-indicator-thickness", "context": "Focus ring" },
+    { "token": "focus-indicator-gap", "context": "Focus ring" }
   ],
   "accessibility": {
     "role": "link",
@@ -152,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" }
     ]
   }
 }