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

package/components/slider.json

@@ -9,6 +9,13 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/slider/"
   },
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Slider",
+      "package": "@react-spectrum/s2"
+    }
+  ],
   "documentBlocks": [
     {
       "type": "purpose",
@@ -16,77 +23,130 @@
     },
     {
       "type": "guideline",
-      "content": "Keyboard focus.\n\nA slider can be navigated using a keyboard. The keyboard focus state takes the slider's visual hover state and adds a blue ring to the slider handle in focus."
+      "content": "Sliders select a value along a continuous range. They’re ideal when upper and lower limits are fixed. Use when approximate or fast selection is more important than precision."
+    },
+    {
+      "type": "guideline",
+      "content": "Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long text, localization, and responsive layouts. Side labels are most useful when vertical space is limited."
+    },
+    {
+      "type": "guideline",
+      "content": "The value is the number selected within the slider’s range, from the min value to max value."
+    },
+    {
+      "type": "guideline",
+      "content": "The min and max values can also be customized appropriately for whatever the slider is showing. By default, the min value starts at 0 and the max value is set to 100."
+    },
+    {
+      "type": "guideline",
+      "content": "More information about a design scenario, to use this option in the component."
+    },
+    {
+      "type": "guideline",
+      "content": "The step is the increment by which these values increase or decrease. A step value of 1 (the default) lets a user only select whole numbers within the min and max range."
+    },
+    {
+      "type": "guideline",
+      "content": "Sometimes a value needs to be formatted for localization or for clearer communication such as currencies or percentages. Formatting can involve rounding, mathematical transformations, number formatting, or displaying a prefix or suffix, such as “+/-” or “px.”"
+    },
+    {
+      "type": "guideline",
+      "content": "Sliders use a linear progression scale by default which means that value is directly correlated to the position of the handle along the track. In some cases, sliders can use a logarithmic (log) progression scale, which is helpful when users need finer control over small values."
+    },
+    {
+      "type": "guideline",
+      "content": "The width of a slider can be customized appropriately for its context."
     },
     {
       "type": "guideline",
-      "content": "Value placement.\n\nThe value follows the placement of the label: on top when the label is on top, and on the side when the label is on the side. The exception to this rule is when the value is editable in a text field, either standard or quiet style. In that case, the editable input is always placed on the side and should include an ARIA label for accessibility, using either aria-labelledby or aria-label."
+      "content": "The track of the slider can have a fill. By default, the fill originates from the left side of the track."
     },
     {
       "type": "guideline",
-      "content": "Mixed value.\n\nA slider representing multiple non-identical values appears as indeterminate, with an en dash (–) in place of the value. The handle position corresponds to the first selected value."
+      "content": "If the value represents an offset, the fill start can be set to represent the point of origin. This allows the slider fill to start from inside the track."
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the label is too long for the available horizontal space, it wraps to form another line."
+      "content": "A gradient can be added to the track of any slider to give more meaning to the range of values. Tracks with a gradient can also have a fill. A gradient track should not be used for choosing a precise color; use a color slider, color area, or color wheel instead."
     },
     {
       "type": "guideline",
-      "content": "Double-click to reset.\n\nAfter a slider has been adjusted, it can be reset to the default value by double-clicking the handle."
+      "content": "In situations where users should be able to precisely input a value, the value can be editable within a text field."
     },
     {
       "type": "guideline",
-      "content": "Include a label.\n\nEvery slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case."
+      "content": "A disabled slider shows that an input exists but is not available in the current context. This helps maintain layout continuity and signals that the slider may become available later."
     },
     {
       "type": "guideline",
-      "content": "Review label-less designs.\n\nIn rare cases where context is sufficient and a label could be absent, make sure to have the design reviewed and approved by an accessibility expert. These sliders must still include an ARIA label in HTML, using either aria-label or aria-labelledby depending on context."
+      "content": "A slider can be navigated using a keyboard. The keyboard focus state takes the slider’s visual hover state and adds a blue ring to the slider handle in focus."
     },
     {
       "type": "guideline",
-      "content": "Allow a hot text option when needed.\n\nIn addition to dragging the handle, sliders can offer other ways to change the value, known as \"hot text.\" Users can click the value text and drag up or down, or scroll up or down while hovering over the value text."
+      "content": "A slider representing multiple non-identical values appears as indeterminate, with an en dash (–) in place of the value. The handle position corresponds to the first selected value."
     },
     {
       "type": "guideline",
-      "content": "Show value units to help provide context.\n\nSlider values can include a unit when it adds context, such as \"%\" or \"px.\" When the value is shown within a text field, the unit disappears on focus."
+      "content": "When the label is too long for the available horizontal space, it wraps to form another line."
     },
     {
       "type": "guideline",
-      "content": "Prefix positive/negative values.\n\nIf the value ranges from negative to positive, prefix the value with a plus (+) or minus (-) sign. When the sign is shown within a text field, it remains visible on focus. When the sign is shown outside the text field, there should be a space between the sign and the numerical value for readability."
+      "content": "After a slider has been adjusted, it can be reset to the default value by double-clicking the handle."
     },
     {
       "type": "guideline",
-      "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the slider is mirrored. The label is right-aligned, the value is left-aligned, and the fill progresses from right to left. Keep in mind that the placement of the percent sign differs depending on the locale."
+      "content": "Every slider should have a label. A slider without a label is ambiguous and not accessible. Write the label in sentence case."
     },
     {
       "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": "In addition to dragging the handle, sliders can offer other ways to change the value, known as “hot text.” Users can click the value text and drag up or down, or scroll up or down while hovering over the value text."
     },
     {
       "type": "guideline",
-      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
+      "content": "Slider values can include a unit when it adds context, such as “%” or “px.” When the value is shown within a text field, the unit disappears on focus."
     },
     {
       "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": "If the value ranges from negative to positive, prefix the value with a plus (+) or minus (-) sign. When the sign is shown within a text field, it remains visible on focus. When the sign is shown outside the text field, there should be a space between the sign and the numerical value for readability."
     }
   ],
   "options": {
-    "label": { "type": "string" },
+    "label": {
+      "type": "string"
+    },
     "labelPosition": {
       "type": "string",
       "default": "top",
-      "values": [{ "value": "top" }, { "value": "side" }]
+      "values": [
+        {
+          "value": "top"
+        },
+        {
+          "value": "side"
+        }
+      ]
+    },
+    "value": {
+      "type": "number",
+      "description": "from minValue to maxValue"
+    },
+    "minValue": {
+      "type": "number",
+      "default": 0
+    },
+    "maxValue": {
+      "type": "number",
+      "default": 100
     },
-    "value": { "type": "number", "description": "from minValue to maxValue" },
-    "minValue": { "type": "number", "default": 0 },
-    "maxValue": { "type": "number", "default": 100 },
     "isRange": {
       "type": "boolean",
       "default": false,
       "description": "If true, the slider will allow selection of a range of values by displaying two handles."
     },
-    "step": { "type": "number", "default": 1 },
+    "step": {
+      "type": "number",
+      "default": 1
+    },
     "valueFormat": {
       "type": "string",
       "description": "This will vary depending on implementation."
@@ -94,36 +154,92 @@
     "progressionScale": {
       "type": "string",
       "default": "linear",
-      "values": [{ "value": "linear" }, { "value": "log" }]
-    },
-    "width": { "type": "number" },
-    "hasFill": { "type": "boolean", "default": false },
-    "fillStart": { "type": "number", "default": 0 },
-    "hasGradient": { "type": "boolean", "default": false },
-    "isEditable": { "type": "boolean", "default": false },
-    "isDisabled": { "type": "boolean", "default": false }
+      "values": [
+        {
+          "value": "linear"
+        },
+        {
+          "value": "log"
+        }
+      ]
+    },
+    "width": {
+      "type": "number"
+    },
+    "hasFill": {
+      "type": "boolean",
+      "default": false
+    },
+    "fillStart": {
+      "type": "number",
+      "default": 0
+    },
+    "hasGradient": {
+      "type": "boolean",
+      "default": false
+    },
+    "isEditable": {
+      "type": "boolean",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    }
   },
   "anatomy": [
-    { "name": "text-field", "description": "Editable numeric value field." },
-    { "name": "handle" },
-    { "name": "track" },
-    { "name": "control" }
+    {
+      "name": "text-field",
+      "description": "Editable numeric value field."
+    },
+    {
+      "name": "handle"
+    },
+    {
+      "name": "track"
+    },
+    {
+      "name": "control"
+    }
   ],
   "states": [
-    { "name": "hover", "trigger": "interaction" },
-    { "name": "down", "trigger": "interaction" },
-    { "name": "keyboard-focus", "trigger": "interaction" }
+    {
+      "name": "hover",
+      "trigger": "interaction"
+    },
+    {
+      "name": "down",
+      "trigger": "interaction"
+    },
+    {
+      "name": "keyboard-focus",
+      "trigger": "interaction"
+    }
   ],
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  },
   "accessibility": {
     "role": "slider",
     "intents": ["choose"],
     "focusable": true,
     "keyboardIntents": ["increment", "decrement"],
     "wcag": [
-      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
-      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
-      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+      {
+        "criterion": "1.3.1",
+        "level": "A",
+        "title": "Info and Relationships"
+      },
+      {
+        "criterion": "2.1.1",
+        "level": "A",
+        "title": "Keyboard"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }

package/components/standard-dialog.json

@@ -16,33 +16,80 @@
     },
     {
       "type": "guideline",
-      "content": "Placement.\n\nStandard dialogs appear in the center of the screen."
+      "content": "Standard dialogs are containers that appear over the interface to present contextual information, tasks, or workflows. They’re centered on the screen and used for moderately complex actions that require focused attention. Interactions outside the dialog are blocked until it's dismissed or completed."
     },
     {
       "type": "guideline",
-      "content": "Text overflow.\n\nWhen the title and description text are too long for the available horizontal space, they wrap to form another line."
+      "content": "By default, an alert dialog that includes a button to cancel or go back will be labeled “Cancel.”"
     },
     {
       "type": "guideline",
-      "content": "Button group overflow.\n\nStandard 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."
+      "content": "Standard 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": "Dismissible or not?\n\nWhether a dialog is dismissible is controlled by the hideCloseButton prop. A dialog with a close button can be dismissed by clicking the button or the background overlay. Avoid using a dismissible dialog when the user needs to confirm an action or make a decision. Instead, use a dismissible dialog for information that is optional or nice to know—content that can be quickly dismissed without requiring user action."
+      "content": "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": "do-dont",
-      "content": "Don't include buttons when dismissible",
-      "dont": "A dismissible dialog should not include buttons in the footer. Instead, the dialog is dismissed by clicking the close button or the background overlay."
+      "type": "guideline",
+      "content": "The presence of a close button determines whether a dialog is dismissible."
+    },
+    {
+      "type": "guideline",
+      "content": "In both cases, pressing the Escape key should close the dialog and return the page to its previous state. This action should behave the same as clicking a close or cancel button."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard dialogs are available in three widths:"
+    },
+    {
+      "type": "guideline",
+      "content": "Dialogs automatically scale down to 90% of the screen width on smaller viewports. Height is flexible and adjusts to fit the content."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard dialogs can include a full-bleed cover image at the top. Dialogs with a cover image should not be dismissible and rely on buttons in the footer area to close the dialog."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard dialogs can include an optional description. Use the description to briefly provide additional context or information that helps users make an informed decision based on the available actions."
+    },
+    {
+      "type": "guideline",
+      "content": "All standard dialogs must include a title. The title appears at the top of the dialog and should briefly describe the expected outcome if the user proceeds with the primary action. If a cover image is shown, the title will appear below it."
+    },
+    {
+      "type": "guideline",
+      "content": "Standard dialogs appear in the center of the screen."
+    },
+    {
+      "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": "Standard 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": "Avoid using a dismissible dialog when the user needs to confirm an action or make a decision. Instead, use a dismissible dialog for information that is optional or nice to know—content that can be quickly dismissed without requiring user action."
     },
     {
       "type": "guideline",
-      "content": "Use similar language for dialog titles and actions.\n\nMost dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is \"Delete conversation,\" the primary action button label should be \"Delete."
+      "content": "A dismissible dialog should not include buttons in the footer. Instead, the dialog is dismissed by clicking the close button or the background overlay."
+    },
+    {
+      "type": "guideline",
+      "content": "Most dialog titles should communicate the primary action of the dialog. When possible, the button label should use the same language as the action mentioned in the title. For example, if the title is “Delete conversation,” the primary action button label should be “Delete.”"
     }
   ],
   "options": {
-    "title": { "type": "string" },
-    "description": { "type": "string" },
+    "title": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
     "hideImage": {
       "type": "boolean",
       "default": false,
@@ -51,14 +98,29 @@
     "size": {
       "type": "string",
       "default": "m",
-      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        }
+      ]
+    },
+    "hideCloseButton": {
+      "type": "boolean",
+      "default": false
     },
-    "hideCloseButton": { "type": "boolean", "default": false },
     "footerContent": {
       "type": "string",
       "description": "Optional footer content to display in the dialog footer like a checkbox."
     },
-    "primaryActionLabel": { "type": "string" },
+    "primaryActionLabel": {
+      "type": "string"
+    },
     "secondaryActionLabel": {
       "type": "string",
       "description": "If undefined, this button does not appear."
@@ -69,15 +131,25 @@
       "description": "If undefined, this button does not appear."
     }
   },
-  "lifecycle": { "introduced": "1.0.0-draft" },
+  "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" }
+      {
+        "criterion": "2.4.3",
+        "level": "A",
+        "title": "Focus Order"
+      },
+      {
+        "criterion": "4.1.2",
+        "level": "A",
+        "title": "Name, Role, Value"
+      }
     ]
   }
 }