@adobe/spectrum-design-data 0.0.0-size-token-taxonomy-20260929225107

package/components/action-button.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/action-button.json",
+  "specVersion": "1.0.0-draft",
+  "name": "action-button",
+  "displayName": "Action button",
+  "description": "Action buttons allow users to perform an action or mark a selection. They're used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren't meant to draw a lot of attention.",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/action-button/"
+  },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "ActionButton",
+      "package": "@spectrum-web-components/action-button",
+      "notes": "Spectrum Web Components custom element: sp-action-button."
+    },
+    {
+      "platform": "web",
+      "componentName": "ActionButton",
+      "package": "@react-spectrum/button"
+    }
+  ],
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Action buttons perform tasks or mark selections. They're suited for task-based workflows where buttons don't need to draw attention."
+    },
+    {
+      "type": "guideline",
+      "content": "Text overflow.\n\nWhen the action button text is too long for the available horizontal space, it truncates at the end. The full text should be revealed with a tooltip on hover."
+    },
+    {
+      "type": "guideline",
+      "content": "Keyboard focus.\n\nAn action button can be navigated using a keyboard. The keyboard focus state takes the button's visual hover state and adds a blue ring to the button in focus."
+    },
+    {
+      "type": "guideline",
+      "content": "Use tooltips.\n\nIcon-only action buttons can be hard to identify. They should always show a tooltip upon hovering for a short period of time, displaying the name and possibly a keyboard shortcut."
+    },
+    {
+      "type": "guideline",
+      "content": "Isolated action buttons.\n\nIf you have an icon-only or text-only isolated action button, use the standard style to make sure it's more easily identifiable as a button."
+    },
+    {
+      "type": "guideline",
+      "content": "Only group related actions with a hold icon.\n\nWhen using a hold icon to switch actions, only group the actions that are part of the same family. Don't group unrelated actions just for the sake of saving space."
+    },
+    {
+      "type": "guideline",
+      "content": "Respect hold icon placement.\n\nIn left-to-right interfaces, the hold icon is always in the bottom right corner of the action button. It's a symbolic indicator that shows that a popover menu will appear on hold. Don't change the placement of the hold icon based on the design of the interface."
+    },
+    {
+      "type": "guideline",
+      "content": "When to use static black and static white.\n\nTo ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast."
+    },
+    {
+      "type": "guideline",
+      "content": "Selected state text color.\n\nThe text color on the selected state of the over-background variant can be customized to match the background it's on. Use the background color for selected text when the action button is on a solid color, and is dark enough to meet a 4.5:1 contrast ratio with a white background (or black background, for the static black variant).\n\nUse black text when the button is on top of an image, or if the background is too low-contrast to meet the 4.5:1 contrast ratio."
+    }
+  ],
+  "options": {
+    "label": {
+      "type": "string"
+    },
+    "hideLabel": {
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
+      "description": "Icon must be present if the label is not defined."
+    },
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [
+        {
+          "value": "xs"
+        },
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
+      ]
+    },
+    "isQuiet": {
+      "type": "boolean",
+      "default": false
+    },
+    "isSelected": {
+      "type": "boolean",
+      "default": false
+    },
+    "isEmphasized": {
+      "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"
+        }
+      ]
+    },
+    "selectedTextColor": {
+      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/hex-color.json"
+    },
+    "hasHoldIcon": {
+      "type": "boolean",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "states": [
+    {
+      "name": "hover",
+      "trigger": "interaction"
+    },
+    {
+      "name": "down",
+      "trigger": "interaction"
+    },
+    {
+      "name": "keyboard-focus",
+      "trigger": "interaction"
+    }
+  ],
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
+  "accessibility": {
+    "role": "button",
+    "intents": ["trigger"],
+    "focusable": true,
+    "keyboardIntents": ["activate"],
+    "wcag": [
+      {
+        "criterion": "2.1.1",
+        "level": "A",
+        "title": "Keyboard"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
+    ]
+  }
+}

package/components/action-group.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/action-group.json",
+  "specVersion": "1.0.0-draft",
+  "name": "action-group",
+  "displayName": "Action group",
+  "description": "An action group is a grouping of action buttons that are related to each other.",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/action-group/"
+  },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "An action group is a grouping of action buttons that are related to each other."
+    },
+    {
+      "type": "guideline",
+      "content": "An action group in a disabled state shows that the action buttons within the group exist, but are not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action group may become available later."
+    },
+    {
+      "type": "guideline",
+      "content": "When selection is enabled, an action group's selection behavior can be set to allow for an empty selection, or not."
+    },
+    {
+      "type": "guideline",
+      "content": "When selection is enabled, an action group can allow for single or multiple selection of action buttons."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, selection is not enabled in an action group. This is used for action groups that offer direct actions, rather than toggling."
+    },
+    {
+      "type": "guideline",
+      "content": "Selection can be enabled for an action group to allow for toggling. This can be used to disclose parts of an interface (for example, showing or hiding panels) or to switch between views (for example, grid or list views)."
+    },
+    {
+      "type": "guideline",
+      "content": "Like action buttons, action groups are not emphasized by default. This is optimal for when the action group is not the core part of an interface, such as in application panels, where all components are monochrome in order to direct focus to the content."
+    },
+    {
+      "type": "guideline",
+      "content": "The emphasized action group has a blue background for its selected state in order to provide a visual prominence that meets the accessible color contrast ratio. This is optimal for when the selection should call attention, such as within a tool bar."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, an action group uses not-quiet action buttons. This style works best in a dense array of controls where the background helps to separate action buttons from the surrounding container, or to give visibility to isolated buttons."
+    },
+    {
+      "type": "guideline",
+      "content": "Alternatively, quiet action groups can have no visible background until they’re interacted with. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read."
+    },
+    {
+      "type": "guideline",
+      "content": "An action group can become justified. By default, it is not justified since the action button size depends on the label and/or icon inside each button. When an action group is justified, it takes up the entire available container width, divided equally for each action button that is inside the group."
+    },
+    {
+      "type": "guideline",
+      "content": "Action groups come in two densities: regular and compact. The compact density retains the same font and icon sizes, but has tighter spacing. The action buttons also become connected for non-quiet action groups."
+    },
+    {
+      "type": "guideline",
+      "content": "Action groups 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": "An action group can be either horizontal or vertical in its orientation. By default, an action group is horizontal. The vertical option should be reserved for when horizontal space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "When there are more actions than the action group has horizontal space for, overflowMode collapse will use an Action menu to contain additional actions. This is used in the components like action bar or panels to show an array of actions to select from when horizontal space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "When multiple items can be selected at a time use an action group when taking actions or making choices from a list of options. Action group is the preferred competent to use when those actions are simple (1-2 words or icon only). If you are switching views or navigating to different content, a segmented control is the preferred component."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the fully justified variant when using the vertical compact action group (both the quiet and not quiet options). This will ensure the buttons have the same width."
+    }
+  ],
+  "options": {
+    "orientation": {
+      "type": "string",
+      "default": "horizontal",
+      "values": [
+        {
+          "value": "horizontal"
+        },
+        {
+          "value": "vertical"
+        }
+      ]
+    },
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
+      ]
+    },
+    "density": {
+      "type": "string",
+      "default": "regular",
+      "values": [
+        {
+          "value": "regular"
+        },
+        {
+          "value": "compact"
+        }
+      ]
+    },
+    "isJustified": {
+      "type": "boolean",
+      "default": false
+    },
+    "isQuiet": {
+      "type": "boolean",
+      "default": false
+    },
+    "isEmphasized": {
+      "type": "boolean",
+      "default": false
+    },
+    "enableSelection": {
+      "type": "boolean",
+      "default": false
+    },
+    "selectionMode": {
+      "type": "string",
+      "default": "single",
+      "description": "Only applicable if selection is enabled",
+      "values": [
+        {
+          "value": "single"
+        },
+        {
+          "value": "multiple"
+        }
+      ]
+    },
+    "allowsEmptySelection": {
+      "type": "boolean",
+      "default": false,
+      "description": "Only applicable if selection is enabled"
+    },
+    "overflowMode": {
+      "type": "string",
+      "default": "wrap",
+      "values": [
+        {
+          "value": "wrap"
+        },
+        {
+          "value": "collapse"
+        }
+      ]
+    },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
+  "accessibility": {
+    "intents": ["trigger"],
+    "focusable": false,
+    "wcag": [
+      {
+        "criterion": "2.1.1",
+        "level": "A",
+        "title": "Keyboard"
+      }
+    ]
+  }
+}

package/components/alert-banner.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/alert-banner.json",
+  "specVersion": "1.0.0-draft",
+  "name": "alert-banner",
+  "displayName": "Alert banner",
+  "description": "Alert banners show pressing and high-signal messages, such as system alerts. They're meant to be noticed and prompt users to take action.",
+  "meta": {
+    "category": "feedback",
+    "documentationUrl": "https://spectrum.adobe.com/page/alert-banner/"
+  },
+  "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Alert banners communicate high-priority messages that need immediate attention. They appear prominently in the interface and often prompt an action."
+    },
+    {
+      "type": "guideline",
+      "content": "An alert banner can include an icon-only close button to dismiss it."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "The close button is optional, depending on context. Consider adding one to let a user easily dismiss the alert."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Don’t use yellow or orange colors for errors because the contrast is not accessible."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Alert banners should appear at the top of a page, below the header."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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)."
+    },
+    {
+      "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."
+    },
+    {
+      "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
+    }
+  },
+  "anatomy": [
+    {
+      "name": "alert-icon",
+      "description": "Icon indicating the alert's severity."
+    }
+  ],
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
+  "accessibility": {
+    "focusable": false,
+    "wcag": [
+      {
+        "criterion": "4.1.3",
+        "level": "AA",
+        "title": "Status Messages"
+      }
+    ]
+  }
+}

package/components/alert-dialog.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/alert-dialog.json",
+  "specVersion": "1.0.0-draft",
+  "name": "alert-dialog",
+  "displayName": "Alert dialog",
+  "description": "Alert dialogs display important information that users need to acknowledge. They appear over the interface and block further interactions until an action is selected.",
+  "meta": {
+    "category": "feedback",
+    "documentationUrl": "https://spectrum.adobe.com/page/alert-dialog/"
+  },
+  "documentBlocks": [
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the appropriate variant based on the context of the message:"
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "When the title and description text are too long for the available horizontal space, they wrap to form another line."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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"
+        }
+      ]
+    },
+    "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"
+  },
+  "accessibility": {
+    "role": "dialog",
+    "intents": ["dismiss"],
+    "focusable": false,
+    "keyboardIntents": ["dismiss"],
+    "wcag": [
+      {
+        "criterion": "2.4.3",
+        "level": "A",
+        "title": "Focus Order"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
+    ]
+  }
+}