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

package/components/menu.json

@@ -9,6 +9,13 @@
     "category": "actions",
     "documentationUrl": "https://spectrum.adobe.com/page/menu/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Menu",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,110 +23,202 @@
     },
     {
       "type": "guideline",
-      "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."
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
+    },
+    {
+      "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."
+    },
+    {
+      "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."
+    },
+    {
+      "type": "guideline",
+      "content": "Avoid cluttering items with repetitive details or promotional content."
     },
     {
       "type": "guideline",
-      "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."
+      "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)."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "A menu item must include a label that clearly communicates the action or option it represents."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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": "Section dividers.\n\nDividers appear between sections when two or more sections are used within the same menu."
+      "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": "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."
+      "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": "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."
+      "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": "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."
+      "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": "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."
+      "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": "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."
+      "content": "Dividers appear between sections when two or more sections are used within the same menu."
     },
     {
       "type": "guideline",
-      "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."
+      "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": "Keyboard interactions.\n\nKey Interaction Enter or SpaceOpens 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 ArrowIn submenu hierarchies: opens child submenu or returns to parent menu item (direction follows hierarchy and orientation).Home / EndMoves focus to first/last item in current menu level.Printable character keysMoves 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.EscCloses current submenu/menu and returns focus to parent item or menu trigger.Tab / Shift + TabExits menu, closes open menus, and moves focus to next/previous focusable element."
+      "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": "Cursor guidelines.\n\nCursor Description PointerUse the pointer cursor for all interactive components in every state."
+      "content": "Following Adobe’s UX writing style, write menu items in sentence case unless they contain words that are branded terms."
     },
     {
       "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 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, AAAMenus 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 AAThe visual presentation of text has a contrast ratio of at least 4.5:1.Resize text 1.4.4 AAMenus 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 illustrations and component 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 RequirementCriterionLevel 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": "Don’t end a menu command with an ellipsis (…) unless it requires additional input to complete the action, typically in a dialog."
     }
   ],
   "options": {
     "container": {
       "type": "string",
-      "values": [{ "value": "popover" }, { "value": "tray" }]
+      "values": [
+        {
+          "value": "popover"
+        },
+        {
+          "value": "tray"
+        }
+      ]
+    },
+    "label": {
+      "type": "string"
     },
-    "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" }]
+      "values": [
+        {
+          "value": "checkbox"
+        },
+        {
+          "value": "switch"
+        }
+      ]
     },
-    "sectionHeader": { "type": "string" },
-    "isCollapsible": { "type": "boolean", "default": false },
-    "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.",
@@ -135,13 +234,22 @@
         "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."
@@ -150,7 +258,10 @@
       "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."
@@ -161,21 +272,46 @@
     }
   ],
   "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,6 +9,19 @@
     "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",
@@ -16,35 +29,39 @@
     },
     {
       "type": "guideline",
-      "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."
+      "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."
+    },
+    {
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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."
     },
     {
       "type": "guideline",
-      "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."
+      "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”)."
     },
     {
       "type": "guideline",
-      "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."
+      "content": "Meter has four variants: informative, positive, notice, and negative."
     },
     {
       "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."
+      "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."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
+      "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."
     },
     {
       "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."
+      "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."
     }
   ],
   "options": {
@@ -52,35 +69,72 @@
       "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" }
+    "value": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "helpText": {
+      "type": "string"
+    }
+  },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
   },
-  "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"
+      }
     ]
   }
 }