@adobe/spectrum-design-data 3.3.0 → 3.4.0

package/components/menu.json

@@ -9,13 +9,6 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/menu/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "Menu",
-      "package": "@react-spectrum/s2"
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -23,202 +16,117 @@
     },
     {
       "type": "guideline",
-      "content": "A disabled menu item indicates that an option exists but isn’t available in the current context. This helps preserve layout consistency and signals that the action might be available later."
-    },
-    {
-      "type": "guideline",
-      "content": "An unavailable menu item signals that an option exists but isn’t accessible in the current scenario. This helps ensure the label remains visible and provides context about why the option is unavailable, or directions for how to make it available."
+      "content": "Drill-in chevron.\n\nWhen a menu item includes a submenu, a drill-in chevron appears at the end of the item to indicate that additional options are available."
     },
     {
       "type": "guideline",
-      "content": "Displays submenus in a collapsed, nested format within the parent menu container. Works with both popover and tray styles. When using a tray, set a fixed height to avoid disorienting shifts when items expand or collapse."
+      "content": "Link-out icon.\n\nWhen a menu item leads to a different context, such as a new page or dialog, a link-out icon appears at the end of the item to indicate that the user will navigate away from the current view."
     },
     {
       "type": "guideline",
-      "content": "Use a section header when a menu section requires a label or descriptor. Section headers are helpful when two or more sections differ in function or context, making it easier for users to understand the structure."
+      "content": "Popover submenus.\n\nWhen a menu is displayed within popovers, a submenu will appear adjacent to the parent menu item in a separate popover. The submenu popover is aligned with an offset to horizontally overlap the parent menu and vertically align the first submenu item with the parent menu item. When a menu is shown in a popover, any submenu appears in a separate popover next to the parent item. The submenu popover is positioned to overlap the parent menu horizontally, with vertical alignment that matches the first submenu item to its parent."
     },
     {
       "type": "guideline",
-      "content": "When the selection option is enabled, the selection can be displayed using checkmarks, checkboxes or switches. Switches are more commonly used on mobile."
+      "content": "Tray submenus.\n\nWhen a menu is shown in a tray, selecting a parent item with a submenu replaces the tray's content with the submenu. A back button labeled with the parent item's title appears at the top of the tray to let users return to the previous menu level."
     },
     {
       "type": "guideline",
-      "content": "A menu section has the options of single selection, multiple selection, or having no selection. By default, menu items have no selection, and perform an action on press."
+      "content": "Keyboard focus.\n\nA menu item can be navigated using a keyboard. The keyboard focus state takes the menu item's visual hover state and adds a focus ring around the item."
     },
     {
       "type": "guideline",
-      "content": "For single selection menu sections, menu items show a single checkmark to indicate the selected item. Multiple selection menu sections can display checkboxes or switches beside each menu item."
+      "content": "Text overflow.\n\nWhen a menu item's label or description are too long for the available horizontal space, they wrap to form another line."
     },
     {
       "type": "guideline",
-      "content": "Menus come in four different sizes: small, medium, large, and extra-large. Medium is the default and most commonly used. Menu sizes should correspond to the size of the menu trigger component (like an action button), and any embedded components (like switches) should follow suit."
+      "content": "Section dividers.\n\nDividers appear between sections when two or more sections are used within the same menu."
     },
     {
       "type": "guideline",
-      "content": "Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
+      "content": "Windows high contrast mode.\n\nIn Windows high contrast mode, menu items should display with default text color. Selected items should have the background and text colors defined for selected text."
     },
     {
       "type": "guideline",
-      "content": "A menu item can display a related value in the value area. Examples of values include the selected option from a submenu, a keyboard shortcut for the action, or other content that clarifies the menu item."
+      "content": "Use consistent sizing.\n\nMenus should be sized according to the component being used as the menu trigger. All submenus within the menu should also be using the same size as the menu trigger."
     },
     {
       "type": "guideline",
-      "content": "Menu items can include description text to provide extra clarity beyond the label. Descriptions help users understand the action and make informed choices."
+      "content": "Use sentence case for menu items.\n\nFollowing Adobe's UX writing style, write menu items in sentence case unless they contain words that are branded terms."
     },
     {
       "type": "guideline",
-      "content": "Avoid cluttering items with repetitive details or promotional content."
+      "content": "Ellipses in menu commands.\n\nDon't end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog."
     },
     {
       "type": "guideline",
-      "content": "Menu items can include icons, but only when they add meaningful context — not just for decoration. Use icons when they have a strong, recognizable association with the label (like tool switching in a toolbar)."
+      "content": "Using descriptions in menu items.\n\nOnly use descriptions in menu items when the information will help a user to decide which action to take from the menu. Don't overload menu items with repetitive information or with promotional calls-to-action."
     },
     {
       "type": "guideline",
-      "content": "A menu item must include a label that clearly communicates the action or option it represents."
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the entire menu is mirrored horizontally, including the direction of the drill-in chevron and popover placement for submenus."
     },
     {
       "type": "guideline",
-      "content": "On desktop, menus are shown in a popover by default. On mobile, popovers can be used when appropriate. Submenus cascade in a separate popover by default."
+      "content": "Keyboard interactions.\n\nKey Interaction Enter or Space Opens menu and moves focus to first item. Down Arrow (on trigger) Opens menu and moves focus to first item. Up Arrow (on trigger, optional) Opens menu and moves focus to last item. Up Arrow / Down Arrow (in menu) Moves focus to previous/next item at the current menu level (wrapping behavior may be implementation-defined). Right Arrow / Left Arrow In submenu hierarchies: opens child submenu or returns to parent menu item (direction follows hierarchy and orientation). Home / End Moves focus to first/last item in current menu level. Printable character keys Moves focus to the next item whose label begins with typed character(s) (typeahead). Enter or Space (on item) Activates item. For checkbox/radio/switch items, may toggle state and optionally keep menu open based on selection behavior. Esc Closes current submenu/menu and returns focus to parent item or menu trigger. Tab / Shift + Tab Exits menu, closes open menus, and moves focus to next/previous focusable element."
     },
     {
       "type": "guideline",
-      "content": "When a menu item includes a submenu, a drill-in chevron appears at the end of the item to indicate that additional options are available."
+      "content": "Cursor guidelines.\n\nCursor Description Pointer Use the pointer cursor for all interactive components in every state."
     },
     {
       "type": "guideline",
-      "content": "When a menu item leads to a different context, such as a new page or dialog, a link-out icon appears at the end of the item to indicate that the user will navigate away from the current view."
-    },
-    {
-      "type": "guideline",
-      "content": "When a menu is displayed within popovers, a submenu will appear adjacent to the parent menu item in a separate popover. The submenu popover is aligned with an offset to horizontally overlap the parent menu and vertically align the first submenu item with the parent menu item."
-    },
-    {
-      "type": "guideline",
-      "content": "When a menu is shown in a popover, any submenu appears in a separate popover next to the parent item. The submenu popover is positioned to overlap the parent menu horizontally, with vertical alignment that matches the first submenu item to its parent."
-    },
-    {
-      "type": "guideline",
-      "content": "When a menu is shown in a tray, selecting a parent item with a submenu replaces the tray’s content with the submenu. A back button labeled with the parent item’s title appears at the top of the tray to let users return to the previous menu level."
-    },
-    {
-      "type": "guideline",
-      "content": "A menu item can be navigated using a keyboard. The keyboard focus state takes the menu item’s visual hover state and adds a focus ring around the item."
-    },
-    {
-      "type": "guideline",
-      "content": "When a menu item’s label or description are too long for the available horizontal space, they wrap to form another line."
-    },
-    {
-      "type": "guideline",
-      "content": "Dividers appear between sections when two or more sections are used within the same menu."
-    },
-    {
-      "type": "guideline",
-      "content": "In Windows high contrast mode, menu items should display with default text color. Selected items should have the background and text colors defined for selected text."
-    },
-    {
-      "type": "guideline",
-      "content": "Menus should be sized according to the component being used as the menu trigger. All submenus within the menu should also be using the same size as the menu trigger."
-    },
-    {
-      "type": "guideline",
-      "content": "Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms."
-    },
+      "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 A Non-text elements, such as icons used in menu items, must provide a text alternative that communicates the item's purpose. All menu items, especially icon-only items, 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, AAA Menus must be understandable to assistive technologies, such as screen readers. Use proper semantic HTML or the appropriate ARIA roles to ensure accessibility. Text contrast 1.4.3 AA The visual presentation of text has a contrast ratio of at least 4.5:1. Resize text 1.4.4 AA Menus should be built in such a way that they can be resized without assistive technology up to 200%. Visual presentation 1.4.8 AAA The 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 AA The visual presentation of illustrations and component states have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line 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, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
+    }
+  ],
+  "implementations": [
     {
-      "type": "guideline",
-      "content": "Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog."
+      "platform": "web",
+      "componentName": "Menu",
+      "package": "@react-spectrum/s2"
     }
   ],
   "options": {
     "container": {
       "type": "string",
-      "values": [
-        {
-          "value": "popover"
-        },
-        {
-          "value": "tray"
-        }
-      ]
-    },
-    "label": {
-      "type": "string"
+      "values": [{ "value": "popover" }, { "value": "tray" }]
     },
+    "label": { "type": "string" },
     "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."
     },
-    "description": {
-      "type": "string"
-    },
-    "value": {
-      "type": "string"
-    },
+    "description": { "type": "string" },
+    "value": { "type": "string" },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
     "selectionMode": {
       "type": "string",
       "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "multiple"
-        },
-        {
-          "value": "no selection"
-        }
+        { "value": "single" },
+        { "value": "multiple" },
+        { "value": "no selection" }
       ]
     },
     "selectionStyle": {
       "type": "string",
-      "values": [
-        {
-          "value": "checkbox"
-        },
-        {
-          "value": "switch"
-        }
-      ]
-    },
-    "sectionHeader": {
-      "type": "string"
-    },
-    "isCollapsible": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "checkbox" }, { "value": "switch" }]
     },
-    "isUnavailable": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
+    "sectionHeader": { "type": "string" },
+    "isCollapsible": { "type": "boolean", "default": false },
+    "isUnavailable": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
   },
   "anatomy": [
-    {
-      "name": "item-label",
-      "description": "Label text of a menu item."
-    },
+    { "name": "item-label", "description": "Label text of a menu item." },
     {
       "name": "menu-item",
       "description": "A single row within the menu.",
@@ -234,22 +142,13 @@
         "link-out-icon"
       ]
     },
-    {
-      "name": "icon",
-      "description": "Leading icon of a menu item."
-    },
-    {
-      "name": "label",
-      "description": "Primary label text of a menu item."
-    },
+    { "name": "icon", "description": "Leading icon of a menu item." },
+    { "name": "label", "description": "Primary label text of a menu item." },
     {
       "name": "description",
       "description": "Secondary descriptive text of a menu item."
     },
-    {
-      "name": "value",
-      "description": "Current value display of a menu item."
-    },
+    { "name": "value", "description": "Current value display of a menu item." },
     {
       "name": "switch",
       "description": "Switch control for a menu item with switch selection style."
@@ -258,10 +157,7 @@
       "name": "checkbox",
       "description": "Checkbox control for a menu item with checkbox selection style."
     },
-    {
-      "name": "thumbnail",
-      "description": "Thumbnail image of a menu item."
-    },
+    { "name": "thumbnail", "description": "Thumbnail image of a menu item." },
     {
       "name": "drill-in-chevron",
       "description": "Chevron indicating a menu item opens a sub-menu."
@@ -272,46 +168,21 @@
     }
   ],
   "states": [
-    {
-      "name": "hover",
-      "trigger": "interaction"
-    },
-    {
-      "name": "down",
-      "trigger": "interaction"
-    },
-    {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    },
-    {
-      "name": "default",
-      "trigger": "prop"
-    },
-    {
-      "name": "disabled",
-      "trigger": "prop"
-    }
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" },
+    { "name": "default", "trigger": "prop" },
+    { "name": "disabled", "trigger": "prop" }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "menu",
     "intents": ["select"],
     "focusable": false,
     "keyboardIntents": ["navigate-options", "activate", "dismiss"],
     "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/meter.json

@@ -9,19 +9,6 @@
     "category": "status",
     "documentationUrl": "https://spectrum.adobe.com/page/meter/"
   },
-  "implementations": [
-    {
-      "platform": "web",
-      "componentName": "Meter",
-      "package": "@react-spectrum/s2"
-    },
-    {
-      "platform": "web",
-      "componentName": "Meter",
-      "importPath": "@adobe/spectrum-wc/components/meter",
-      "notes": "Spectrum 2 web component custom element: swc-meter."
-    }
-  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -29,39 +16,48 @@
     },
     {
       "type": "guideline",
-      "content": "A meter can include help text below it to explain what the value means and how to reach the target. This text may include units, value ranges, thresholds like targets or warnings, and actions that affect the meter."
+      "content": "Text overflow.\n\nWhen the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates."
     },
     {
       "type": "guideline",
-      "content": "The value represents a user-driven quantity or achievement, such as tutorials completed or storage used. Unlike a progress bar, it reflects user actions, not system activity."
+      "content": "Progress bar vs. meter.\n\nA progress bar fills automatically as the system loads either determinately or indeterminately. A user's actions do not affect the progress bar; it just indicates how long they must wait for the process to finish. A meter indicates how much the user has completed or how far they are in a continuum."
     },
     {
       "type": "guideline",
-      "content": "Meters come in four different sizes: small, medium, large, and extra-large. By default, meters use medium size. Use the small size when there are multiple meters shown at the same time in a more confined space, such as in tables or cards."
+      "content": "Labels.\n\nUse the built-in style for showing a label associated with the meter. By default, the label is start-aligned and an optional value is end-aligned above the track. (In left-to-right languages, this means the label appears on the left and the value on the right; in right-to-left languages, this flips.) The label should be written in sentence case. When meters appear in a table, you may use the column header as the label. In this case, set labelPosition=\"side\" or use hideLabel if the column header fully describes what each meter represents."
     },
     {
       "type": "guideline",
-      "content": "Meters can include a value label to show details like “60%” or “2 of 8.” It should only appear if the main label is shown and is always placed above the track."
+      "content": "Representing semantic values.\n\nMeter variants can be used to represent semantic values by switching variants as the value changes, from positive, to notice, and then to negative. This kind of variant switching should be handled appropriately within the context of your product so that you're setting accurate expectations for your users about the semantic meaning."
     },
     {
       "type": "guideline",
-      "content": "Meters should always have a label placed above the track. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These meters without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
+      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the meter is mirrored. The label is right-aligned, the value is left-aligned, and the fill progresses from right to left. Beware that the placement of the percent sign differs depending on the locale."
     },
     {
       "type": "guideline",
-      "content": "Meter has four variants: informative, positive, notice, and negative."
+      "content": "Keyboard interactions.\n\nKey Interaction Tab Moves focus onto or off of the button. Space or Enter Executes 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": "When the label is too long for the available horizontal space, it wraps to form another line. The value is always shown in full and never wraps or truncates."
+      "content": "Cursor guidelines.\n\nCursor Usage Pointer Use the pointer cursor for all interactive components."
     },
     {
       "type": "guideline",
-      "content": "Use the built-in style for showing a label associated with the meter. By default, the label is start-aligned and an optional value is end-aligned above the track. (In left-to-right languages, this means the label appears on the left and the value on the right; in right-to-left languages, this flips.) The label should be written in sentence case."
+      "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 A Non‑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, AAA Buttons 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 A Color 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 AA Large 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 AA Buttons should be built in such a way that they can be resized without assistive technology up to 200%. Visual presentation 1.4.8 AAA The 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 AA The visual presentation of icons and various states have a contrast ratio of at least 3:1. Text spacing 1.4.12 AA Line 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, AAA All functionality of the component is operable through a keyboard without specific timing for keystrokes. Keyboard traps 2.1.2 A Focus 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, AAA There is no flashing content or unnecessary motion or animation in this component. Focus order 2.4.3 A Navigation sequences receive focus in an order that preserves meaning and operability. Focus visible 2.4.7 AA Keyboard states use an indicator that is visible with at least 3:1 contrast."
+    }
+  ],
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Meter",
+      "package": "@react-spectrum/s2"
     },
     {
-      "type": "guideline",
-      "content": "Meter variants can be used to represent semantic values by switching variants as the value changes, from positive, to notice, and then to negative. This kind of variant switching should be handled appropriately within the context of your product so that you’re setting accurate expectations for your users about the semantic meaning."
+      "platform": "web",
+      "componentName": "Meter",
+      "importPath": "@adobe/spectrum-wc/components/meter",
+      "notes": "Spectrum 2 web component custom element: swc-meter."
     }
   ],
   "options": {
@@ -69,72 +65,35 @@
       "type": "string",
       "default": "informative",
       "values": [
-        {
-          "value": "informative"
-        },
-        {
-          "value": "positive"
-        },
-        {
-          "value": "notice"
-        },
-        {
-          "value": "negative"
-        }
+        { "value": "informative" },
+        { "value": "positive" },
+        { "value": "notice" },
+        { "value": "negative" }
       ]
     },
-    "label": {
-      "type": "string"
-    },
-    "hideLabel": {
-      "type": "boolean",
-      "default": false
-    },
-    "valueLabel": {
-      "type": "string"
-    },
-    "width": {
-      "type": "number"
-    },
+    "label": { "type": "string" },
+    "hideLabel": { "type": "boolean", "default": false },
+    "valueLabel": { "type": "string" },
+    "width": { "type": "number" },
     "size": {
       "type": "string",
       "default": "m",
       "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
       ]
     },
-    "value": {
-      "type": "number",
-      "minimum": 0,
-      "maximum": 1
-    },
-    "helpText": {
-      "type": "string"
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "value": { "type": "number", "minimum": 0, "maximum": 1 },
+    "helpText": { "type": "string" }
   },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "role": "meter",
     "focusable": false,
     "wcag": [
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }