@adobe/spectrum-design-data 3.3.0-beta.1 → 3.3.0

package/components/button-group.json

@@ -9,6 +9,19 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/button-group/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "ButtonGroup",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "ButtonGroup",
+      "importPath": "@adobe/spectrum-wc/components/button-group",
+      "notes": "Spectrum 2 web component custom element: swc-button-group."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,76 +29,107 @@
     },
     {
       "type": "guideline",
-      "content": "Overflow.\n\nWhen horizontal space is limited, button groups stack vertically. Buttons are stacked by the importance of the action, with the most critical or primary action at the bottom."
+      "content": "Button groups organize related buttons into a single group for presenting multiple, related actions."
     },
     {
       "type": "guideline",
-      "content": "Use the recommended option for subsequent actions.\n\nThe most critical action within a button group should be an accent, primary, or negative button (fill or outline). The other actions should always be a secondary outline button."
+      "content": "A button group in a disabled state shows that the 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 a button group may become available later."
     },
     {
       "type": "guideline",
-      "content": "Align button groups based on content.\n\nButton groups are aligned contextually. In general, button groups are left-aligned to follow content such as a block of text. They are center-aligned in the context of an empty state. And, they should be right-aligned inside container components such as dialogs, popovers, or cards."
+      "content": "This option stacks button groups vertically when horizontal space is limited, placing the most important action at the bottom."
     },
     {
       "type": "guideline",
-      "content": "Respect button order within a group.\n\nThe order of button priority should match the alignment of surrounding text. When text is left-aligned, buttons should be arranged so that the leftmost button is the most critical. When text is right- or center- aligned, the most critical action should be the furthest right."
+      "content": "Button 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": "Use icons only for the most critical actions.\n\nNot all buttons in a group require an icon, but buttons with icons should always be of a higher priority than ones without icons. If the most critical action in a group doesn't have an icon, don't use icons in the remaining lower-level actions."
+      "content": "A button group can be either horizontal or vertical in its orientation. By default, a button group is horizontal. Use vertical option when horizontal space is limited."
     },
     {
       "type": "guideline",
-      "content": "Use a button group to show additional actions.\n\nInstead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action."
+      "content": "When horizontal space is limited, button groups stack vertically. Buttons are stacked by the importance of the action, with the most critical or primary action at the bottom."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the button group is mirrored."
+      "content": "Button groups are aligned contextually. In general, button groups are left-aligned to follow content such as a block of text. They are center-aligned in the context of an empty state. And, they should be right-aligned inside container components such as dialogs, popovers, or cards."
     },
     {
       "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button group. Focus is placed on the primary button of the group.Shift + TabMoves focus to the previous component.Space or EnterExecutes the selected action within the button group. Focus remains on the active button to preserve context across the group. If the action opens or closes a related container, focus moves into the resulting context or returns to the triggering buttonArrow keysMoves focus through the group of buttons."
+      "content": "The order of button priority should match the alignment of surrounding text. When text is left-aligned, buttons should be arranged so that the leftmost button is the most critical. When text is right- or center- aligned, the most critical action should be the furthest right."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components in every state."
+      "content": "Not all buttons in a group require an icon, but buttons with icons should always be of a higher priority than ones without icons. If the most critical action in a group doesn’t have an icon, don’t use icons in the remaining lower-level actions."
     },
     {
       "type": "guideline",
-      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Orientation 1.3.4 AAButton groups are available in both vertical and horizontal orientations.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.Text contrast 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Non-text contrast 1.4.11 AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size when text is wrapped in buttons. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
+      "content": "Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action."
     }
   ],
   "options": {
     "orientation": {
       "type": "string",
       "default": "horizontal",
-      "values": [{ "value": "horizontal" }, { "value": "vertical" }]
+      "values": [
+        {
+          "value": "horizontal"
+        },
+        {
+          "value": "vertical"
+        }
+      ]
     },
     "size": {
       "type": "string",
       "pattern": "^(x?s|m|x{0,3}l)$",
       "default": "m",
       "values": [
-        { "value": "s" },
-        { "value": "m" },
-        { "value": "l" },
-        { "value": "xl" }
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
       ]
     },
     "overflowMode": {
       "type": "string",
       "default": "wrap",
-      "values": [{ "value": "wrap" }, { "value": "collapse" }]
+      "values": [
+        {
+          "value": "wrap"
+        },
+        {
+          "value": "collapse"
+        }
+      ]
     },
-    "isDisabled": { "type": "boolean", "default": false }
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "group",
     "intents": ["trigger"],
     "focusable": false,
     "wcag": [
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }

package/components/button.json

@@ -9,10 +9,23 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/button/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "importPath": "@adobe/spectrum-wc/components/button",
+      "notes": "Spectrum 2 web component custom element: swc-button."
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
-      "content": "Buttons allow users to perform an action or to navigate to another page."
+      "content": "Buttons enable actions or navigation between views. They come in multiple styles to support different levels of emphasis, and are commonly used to guide progression through a flow."
     },
     {
       "type": "guideline",
@@ -49,7 +62,7 @@
     {
       "type": "do-dont",
       "content": "Don't override color",
-      "dont": "Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible"
+      "dont": "Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible."
     },
     {
       "type": "guideline",
@@ -58,51 +71,15 @@
     {
       "type": "do-dont",
       "content": "Don't use the pending state for long progress",
-      "dont": "The pending state should be reserved for indeterminate actions that are expected to take 5 seconds or less. For determinate or longer actions, use a progress bar or progress circle outside of the button."
+      "dont": "The pending state should be reserved for indeterminate actions that are expected to take 5 seconds or less. For determinate or longer actions, use a [progress bar](https://spectrum.adobe.com/page/progress-bar/) or [progress circle](https://spectrum.adobe.com/page/progress-circle/) outside of the button."
     },
     {
       "type": "guideline",
-      "content": "Use a button group to show additional actions.\n\nInstead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action."
+      "content": "Use a button group to show additional actions.\n\nInstead of a single split button (now a deprecated component), use a [button group](https://spectrum.adobe.com/page/button-group/) to show any additional actions related to the most critical action."
     },
     {
       "type": "guideline",
       "content": "Display a popover when featuring subsequent options.\n\nIn some instances, it's possible to have a call to action button display a popover (or tray) to feature subsequent options. These options should extend and parallel the action of the button. Do not include arbitrary or unrelated options."
-    },
-    {
-      "type": "guideline",
-      "content": "Be concise.\n\nButton text should be concise: 1 or 2 words, no longer than 4 words, with fewer than 20 characters including spaces. Don't use punctuation marks such as periods or exclamation points."
-    },
-    {
-      "type": "guideline",
-      "content": "Write labels as verbs.\n\nA button represents an action, so its label needs to reflect the action that a user is taking — which is a verb. Labels written as nouns or adjectives tend to be unclear and disorienting."
-    },
-    {
-      "type": "guideline",
-      "content": "Clearly state the action.\n\nMake sure that a button's label clearly states the outcome of the action. Use the same word or phrase as found elsewhere in the experience. For example, when designing a form for people to sign up for a trial offer, use \"Sign up\" as the call to action for completing the form. Phrases like \"Start trial\" skip the sign up step. Words like \"Submit\" or \"Enter,\" while technically correct, focus on the action of finishing filling out the form itself, rather than what the user is actually doing by filling it out (signing up for something)."
-    },
-    {
-      "type": "guideline",
-      "content": "Use sentence case.\n\nButton text should always be in sentence case. Never use capitalization to emphasize a specific button."
-    },
-    {
-      "type": "guideline",
-      "content": "Be aware of tone.\n\nEmoji and exclamation points aren't appropriate for the functional, utilitarian nature of buttons. Keep the label to just text, with no punctuation or extra decoration."
-    },
-    {
-      "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the button is mirrored. The icon is placed on the right side of the text."
-    },
-    {
-      "type": "guideline",
-      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
-    },
-    {
-      "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
-    },
-    {
-      "type": "guideline",
-      "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.Text contrast minimums 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
     }
   ],
   "options": {
@@ -111,30 +88,62 @@
       "default": "accent",
       "description": "Visual emphasis level.",
       "values": [
-        { "value": "accent" },
-        { "value": "negative" },
-        { "value": "primary" },
-        { "value": "secondary" }
+        {
+          "value": "accent"
+        },
+        {
+          "value": "negative"
+        },
+        {
+          "value": "primary"
+        },
+        {
+          "value": "secondary"
+        }
       ]
     },
     "style": {
       "type": "string",
       "default": "fill",
-      "values": [{ "value": "fill" }, { "value": "outline" }]
+      "values": [
+        {
+          "value": "fill"
+        },
+        {
+          "value": "outline"
+        }
+      ]
     },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        { "value": "s" },
-        { "value": "m" },
-        { "value": "l" },
-        { "value": "xl" }
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
       ]
     },
-    "isDisabled": { "type": "boolean", "default": false },
-    "isPending": { "type": "boolean", "default": false },
-    "isLabelHidden": { "type": "boolean", "default": false },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "isPending": {
+      "type": "boolean",
+      "default": false
+    },
+    "isLabelHidden": {
+      "type": "boolean",
+      "default": false
+    },
     "icon": {
       "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
       "description": "Icon placed at the start of the button. Required when isLabelHidden is true."
@@ -142,7 +151,14 @@
     "staticColor": {
       "type": "string",
       "description": "Static color for use on colored backgrounds.",
-      "values": [{ "value": "white" }, { "value": "black" }]
+      "values": [
+        {
+          "value": "white"
+        },
+        {
+          "value": "black"
+        }
+      ]
     }
   },
   "slots": [
@@ -151,23 +167,43 @@
       "description": "Text label of the button.",
       "required": false
     },
-    { "name": "icon", "description": "Icon placed at the start of the button." }
+    {
+      "name": "icon",
+      "description": "Icon placed at the start of the button."
+    }
   ],
   "anatomy": [
-    { "name": "icon", "description": "Leading icon." },
-    { "name": "label", "description": "Button text.", "required": true }
+    {
+      "name": "icon",
+      "description": "Leading icon."
+    },
+    {
+      "name": "label",
+      "description": "Button text.",
+      "required": true
+    }
   ],
   "states": [
-    { "name": "hover", "trigger": "interaction", "precedence": 50 },
+    {
+      "name": "hover",
+      "trigger": "interaction",
+      "precedence": 50
+    },
     {
       "name": "focus",
       "trigger": "interaction",
       "precedence": 60,
       "layered": true
     },
-    { "name": "disabled", "trigger": "prop", "precedence": 100 }
+    {
+      "name": "disabled",
+      "trigger": "prop",
+      "precedence": 100
+    }
   ],
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "tokenBindings": [
     {
       "token": "corner-radius-button-small",
@@ -188,8 +224,16 @@
     "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/calendar.json

@@ -9,6 +9,13 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/calendar/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Calendar",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,28 +23,87 @@
     },
     {
       "type": "guideline",
-      "content": "Unavailable dates.\n\nWhen a day or several days are unavailable within the calendar popover, each day should display a strikethrough to help the user understand that they cannot select it. Disabled days use a distinct gray style to clearly differentiate them from unavailable days. When the calendar prevents selection of past dates, this visual treatment helps users distinguish disabled days from those marked as unavailable."
+      "content": "Calendars display the days of a selected month and highlight the current day. They support navigating to past or future months and selecting a specific date."
     },
     {
       "type": "guideline",
-      "content": "Why unavailable and disabled days are necessary.\n\nIn a date selection system, users often need to distinguish between dates that cannot be selected and dates that are simply inactive. Supporting both states improves clarity and prevents errors. Here's an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental. Unavailable dates: Days when the rental is already booked or blocked by the owner. These appear with a strikethrough, indicating they cannot be selected. Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive. Guests see unavailable dates marked clearly so they don't attempt to select them. Hosts or admins can view past dates as disabled and also mark future dates as unavailable when needed. By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection."
+      "content": "An array of days that are displayed in the current calendar view. This includes:"
     },
     {
       "type": "guideline",
-      "content": "Range fill color.\n\nThe range fill shows which days fall between two selected dates. If the range spans more than the three-month calendar view, it ends on the last visible day but continues as users navigate with the calendar chevrons. A dashed stroke outlines the fill to improve visibility on bright screens and for users with vision impairments."
+      "content": "The maximum amount of months displayed in the calendar popover is three."
     },
     {
-      "type": "do-dont",
-      "content": "Do not change the styling of unavailable days",
-      "dont": "The strikethrough styling intentionally accommodates internationalization."
+      "type": "guideline",
+      "content": "The minimum amount of months displayed in the calendar popover is one."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover may display an error as error text when a user attempts to provide an input that violates the defined constraints of the date selection. For example, when the user selects dates that fall outside allowable limits, or conflict with contextual restrictions."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover is disabled. For example, a month within a three-month range is disabled."
+    },
+    {
+      "type": "guideline",
+      "content": "The types of selection available for the calendar."
+    },
+    {
+      "type": "guideline",
+      "content": "The current year or month displayed in the calendar popover."
+    },
+    {
+      "type": "guideline",
+      "content": "When a day or several days are unavailable within the calendar popover, each day should display a strikethrough to help the user understand that they cannot select it."
+    },
+    {
+      "type": "guideline",
+      "content": "Disabled days use a distinct gray style to clearly differentiate them from unavailable days. When the calendar prevents selection of past dates, this visual treatment helps users distinguish disabled days from those marked as unavailable."
+    },
+    {
+      "type": "guideline",
+      "content": "In a date selection system, users often need to distinguish between dates that cannot be selected and dates that are simply inactive. Supporting both states improves clarity and prevents errors."
+    },
+    {
+      "type": "guideline",
+      "content": "Here’s an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental."
+    },
+    {
+      "type": "guideline",
+      "content": "Unavailable dates: Days when the rental is already booked or blocked by the owner. These appear with a strikethrough, indicating they cannot be selected."
+    },
+    {
+      "type": "guideline",
+      "content": "Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive."
+    },
+    {
+      "type": "guideline",
+      "content": "Guests see unavailable dates marked clearly so they don’t attempt to select them. Hosts or admins can view past dates as disabled and also mark future dates as unavailable when needed."
+    },
+    {
+      "type": "guideline",
+      "content": "By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection."
+    },
+    {
+      "type": "guideline",
+      "content": "The range fill shows which days fall between two selected dates. If the range spans more than the three-month calendar view, it ends on the last visible day but continues as users navigate with the calendar chevrons. A dashed stroke outlines the fill to improve visibility on bright screens and for users with vision impairments."
+    },
+    {
+      "type": "guideline",
+      "content": "The strikethrough styling intentionally accommodates internationalization."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover supports a disabled state but not a read-only state. Dates or months may be temporarily disabled based on context (for example, if a user must complete a task before selecting a date). In these cases, help text can explain why certain dates are unavailable."
     },
     {
       "type": "guideline",
-      "content": "Calendar popover states.\n\nThe calendar popover supports a disabled state but not a read-only state. Dates or months may be temporarily disabled based on context (for example, if a user must complete a task before selecting a date). In these cases, help text can explain why certain dates are unavailable. If a date picker is truly read-only, users shouldn't be able to open the calendar popover at all, since they can't interact with it."
+      "content": "If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it."
     },
     {
       "type": "guideline",
-      "content": "Optional time fields.\n\nThe calendar popover can also include time-specific fields, allowing users to specify start and end times."
+      "content": "The calendar popover can also include time-specific fields, allowing users to specify start and end times."
     }
   ],
   "options": {

package/components/card.json

@@ -17,6 +17,19 @@
       "description": "Preview area or thumbnail within the card."
     }
   ],
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Card",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "platform": "web",
+      "componentName": "Card",
+      "importPath": "@adobe/spectrum-wc/components/card",
+      "notes": "Spectrum 2 web component custom element: swc-card."
+    }
+  ],
   "states": [{ "name": "default" }],
   "lifecycle": { "introduced": "1.0.0-draft" }
 }