@adobe/spectrum-design-data 0.4.0 → 0.6.0

package/components/rating.json

@@ -9,82 +9,85 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/rating/"
   },
-  "options": {
-    "value": {
-      "type": "number",
-      "minimum": 0,
-      "maximum": 5,
-      "default": 0,
-      "multipleOf": 0.5,
-      "description": "From 0 to 5, can be a decimal to represent half stars"
-    },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "states": [
+  "documentBlocks": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "purpose",
+      "content": "The rating component lets users apply a rating to an item or experience, such as an image, a forum post, an item for sale in a marketplace, and more."
     },
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Ratings allow scoring of an item or experience based on quality or preference. Common examples include images, forum posts, or products."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
-    {
-      "token": "worfklow-icon-size-75",
-      "context": "Layout"
+      "type": "guideline",
+      "content": "A rating in a disabled state shows that the component exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later."
     },
     {
-      "token": "workflow-icon-size-100",
-      "context": "Layout"
+      "type": "guideline",
+      "content": "By default, ratings are not emphasized (dark gray). This version is optimal for when the rating is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content."
     },
     {
-      "token": "rating-width-small",
-      "context": "Width"
+      "type": "guideline",
+      "content": "The emphasized (blue) version provides a visual prominence that is optimal for forms, dialogs, and other situations where a rating needs to be noticed."
     },
     {
-      "token": "rating-width-medium",
-      "context": "Width"
+      "type": "guideline",
+      "content": "The value is the number of the rating selected, on a sentiment scale from 0 to 5 (0 being the lowest, 5 being the highest)."
     },
     {
-      "token": "rating-height-small",
-      "context": "Height"
+      "type": "guideline",
+      "content": "The rating component supports two main use cases: inputting and aggregating. Inputting allows users to select a rating, while aggregating displays the average rating, which may include fractional stars. Interactive ratings show only whole stars to avoid confusion during selection."
     },
     {
-      "token": "rating-height-medium",
-      "context": "Height"
+      "type": "guideline",
+      "content": "When a user interacts with a rating component that shows a previously entered value, a tooltip appears when they hover over a star. The language in the tooltip is phrased as a call-to-action to edit their rating. For example, “Edit 4 star rating”."
     },
     {
-      "token": "corner-radius-medium-size-small",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "A user’s previously entered rating can be cleared if they select the “highest” star (for example, clicking or tapping the fourth star from the left on a four-star rating). On keyboard focus, the left/down arrow keys will decrease the rating until the last star is removed. A tooltip appears on hover with alt text that describes the action, for example “Clear 4 star rating”."
     },
     {
-      "token": "corner-radius-medium-size-medium",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Rating can display approximate value or precise value depending on the needs of the product or service. For example, Amazon.com uses approximate rating, but Apple's App Store uses precise rating."
     },
     {
-      "token": "focus-indicator-thickness",
-      "context": "Focus ring"
+      "type": "guideline",
+      "content": "When representing multiple values (e.g., rating 2 photos at the same time), the rating is shown as empty if the ratings are not the same. This behavior is consistent with how a radio button group works, as well."
     },
     {
-      "token": "focus-indicator-grap",
-      "context": "Focus ring"
+      "type": "guideline",
+      "content": "Star ratings should always have 5 available stars. This shouldn’t be increased or decreased to fit various containers."
+    }
+  ],
+  "options": {
+    "value": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 5,
+      "default": 0,
+      "multipleOf": 0.5,
+      "description": "From 0 to 5, can be a decimal to represent half stars"
     },
+    "isEmphasized": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false }
+  },
+  "states": [
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "down", "trigger": "interaction" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "worfklow-icon-size-75", "context": "Layout" },
+    { "token": "workflow-icon-size-100", "context": "Layout" },
+    { "token": "rating-width-small", "context": "Width" },
+    { "token": "rating-width-medium", "context": "Width" },
+    { "token": "rating-height-small", "context": "Height" },
+    { "token": "rating-height-medium", "context": "Height" },
+    { "token": "corner-radius-medium-size-small", "context": "Rounding" },
+    { "token": "corner-radius-medium-size-medium", "context": "Rounding" },
+    { "token": "focus-indicator-thickness", "context": "Focus ring" },
+    { "token": "focus-indicator-grap", "context": "Focus ring" },
     {
       "token": "rating-top-to-content-area-small",
       "context": "Spacing (padding)"
@@ -109,38 +112,14 @@
       "token": "rating-edge-to-content-area-medium",
       "context": "Spacing (padding)"
     },
-    {
-      "token": "spacing-75",
-      "context": "Spacing"
-    },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Default"
-    },
-    {
-      "token": "accent-content-color-default",
-      "context": "Emphasized"
-    },
-    {
-      "token": "accent-content-color-hover",
-      "context": "Hover"
-    },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Hover"
-    },
-    {
-      "token": "neutral-content-color-down",
-      "context": "Down"
-    },
-    {
-      "token": "accent-content-color-down",
-      "context": "Down"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    }
+    { "token": "spacing-75", "context": "Spacing" },
+    { "token": "neutral-content-color-default", "context": "Default" },
+    { "token": "accent-content-color-default", "context": "Emphasized" },
+    { "token": "accent-content-color-hover", "context": "Hover" },
+    { "token": "neutral-content-color-hover", "context": "Hover" },
+    { "token": "neutral-content-color-down", "context": "Down" },
+    { "token": "accent-content-color-down", "context": "Down" },
+    { "token": "disabled-content-color", "context": "Disabled" }
   ],
   "accessibility": {
     "role": "slider",
@@ -148,21 +127,9 @@
     "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/search-field.json

@@ -9,136 +9,153 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/search-field/"
   },
-  "options": {
-    "label": {
-      "type": "string"
-    },
-    "hideLabel": {
-      "type": "boolean",
-      "default": false
-    },
-    "icon": {
-      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
-      "description": "Icon must be present if the label is not defined."
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "A search field is used for searching and filtering items."
     },
-    "value": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "Search fields enable finding or filtering items based on text input."
     },
-    "width": {
-      "type": "number"
+    {
+      "type": "guideline",
+      "content": "A search field should include a label and a search icon. In the default state before a search term is input, the label is in regular body text style to meet contrast ratios and to show that this is a field label, not placeholder text. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism)."
     },
-    "size": {
-      "type": "string",
-      "default": "m",
-      "pattern": "^(x?s|m|x{0,3}l)$",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
-      ]
+    {
+      "type": "guideline",
+      "content": "The value shows a user’s entered text in regular body text style."
     },
-    "helpText": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "The width of a search field can be customized appropriately for its context."
     },
-    "placeholder": {
-      "type": "string"
+    {
+      "type": "guideline",
+      "content": "Search fields 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."
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "states": [
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "A search field can have help text below the field to give extra context or instruction about what a user should input. The description communicates a hint or helpful information, such as a search’s scope."
     },
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "Placeholder text provides hints about expected input values."
     },
     {
-      "name": "focus-+-hover",
-      "trigger": "prop"
+      "type": "guideline",
+      "content": "A search field in a disabled state shows that a search option exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later."
     },
     {
-      "name": "focus-+-not-hover",
-      "trigger": "prop"
+      "type": "guideline",
+      "content": "The minimum width for a search field is 3× the height of the field, for both standard and quiet style. This minimum width guarantees that small search fields are readable and easy to target on touch devices."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
+      "type": "guideline",
+      "content": "When the entered text is too long for the available horizontal space in the field, the text truncates."
+    },
     {
-      "token": "in-field",
-      "context": "Components"
+      "type": "guideline",
+      "content": "When the help text is too long for the available horizontal space, it wraps to form another line."
     },
     {
-      "token": "search-field-minimum-width-multiplier",
-      "context": "Width (minimum)"
+      "type": "guideline",
+      "content": "A search field can be navigated using a keyboard. The keyboard focus state takes the field’s visual hover state and adds a blue ring to the field in focus."
     },
     {
-      "token": "field-width",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "The in-field button offers an option to clear any input search term."
     },
     {
-      "token": "component-height-75",
-      "context": "Height"
+      "type": "guideline",
+      "content": "If search results are being shown in a menu or popover, selecting this button will close the menu and clear the field. If a search term has been entered and the results have appeared, selecting this will only clear the field and not affect the list of results."
     },
     {
-      "token": "component-height-100",
-      "context": "Height"
+      "type": "guideline",
+      "content": "Search fields do not have an error state. Search functionality should anticipate spelling mistakes in search queries, and accommodate multiple spellings of words in search results — not treating any search term as an error."
     },
     {
-      "token": "component-height-200",
-      "context": "Height"
+      "type": "guideline",
+      "content": "Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear."
     },
     {
-      "token": "component-height-300",
-      "context": "Height"
+      "type": "guideline",
+      "content": "In a searching scenario, a user inputs a search term for a specific thing they’re looking for. In a filtering scenario, a user generally knows what they’re looking for, but may not have a specific thing in mind."
     },
     {
-      "token": "help-text-to-component",
-      "context": "Spacing (search field to help text)"
+      "type": "guideline",
+      "content": "The search field can be used for both of these contexts. For a search experience, use the search field as-is. For a filtering experience, add a filter icon next to the search field, where a user can narrow down their search results before (or instead of) searching using a specific term. Filters can appear below the search field as tags."
     },
     {
-      "token": "corner-radius-full",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Spectrum previously had a specific “search within” component that would allow a user to filter down a search field category before searching for a particular term. It was deprecated because it did not meet accessibility and localization requirements."
     },
     {
-      "token": "border-width-200",
-      "context": "Border"
+      "type": "guideline",
+      "content": "Any search field should include a label inside the field, in the default state. The default label text is Search, but this can be customized to be more specific for use cases like scoped search, wayfinding, or building context — acting like a prompt for a user to search more specifically."
     },
     {
-      "token": "workflow-icon-size-75",
-      "context": "Icon"
+      "type": "guideline",
+      "content": "Keep in mind that once a search term is entered the label text is no longer viewable. Use help text to show search formatting examples or give hints about what to input. It can be distracting or redundant if the search field label and its help text are both communicating the same thing, so write these thoughtfully."
     },
     {
-      "token": "workflow-icon-size-100",
-      "context": "Icon"
+      "type": "guideline",
+      "content": "The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
+    "hideLabel": { "type": "boolean", "default": false },
+    "icon": {
+      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
+      "description": "Icon must be present if the label is not defined."
     },
+    "value": { "type": "string" },
+    "width": { "type": "number" },
+    "size": {
+      "type": "string",
+      "default": "m",
+      "pattern": "^(x?s|m|x{0,3}l)$",
+      "values": [
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
+      ]
+    },
+    "helpText": { "type": "string" },
+    "placeholder": { "type": "string" },
+    "isDisabled": { "type": "boolean", "default": false }
+  },
+  "states": [
+    { "name": "down", "trigger": "interaction" },
+    { "name": "hover", "trigger": "interaction" },
+    { "name": "focus-+-hover", "trigger": "prop" },
+    { "name": "focus-+-not-hover", "trigger": "prop" },
+    { "name": "keyboard-focus", "trigger": "interaction" }
+  ],
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "in-field", "context": "Components" },
     {
-      "token": "workflow-icon-size-200",
-      "context": "Icon"
+      "token": "search-field-minimum-width-multiplier",
+      "context": "Width (minimum)"
     },
+    { "token": "field-width", "context": "Width (default)" },
+    { "token": "component-height-75", "context": "Height" },
+    { "token": "component-height-100", "context": "Height" },
+    { "token": "component-height-200", "context": "Height" },
+    { "token": "component-height-300", "context": "Height" },
     {
-      "token": "workflow-icon-size-300",
-      "context": "Icon"
+      "token": "help-text-to-component",
+      "context": "Spacing (search field to help text)"
     },
+    { "token": "corner-radius-full", "context": "Rounding" },
+    { "token": "border-width-200", "context": "Border" },
+    { "token": "workflow-icon-size-75", "context": "Icon" },
+    { "token": "workflow-icon-size-100", "context": "Icon" },
+    { "token": "workflow-icon-size-200", "context": "Icon" },
+    { "token": "workflow-icon-size-300", "context": "Icon" },
     {
       "token": "component-pill-edge-to-text-75",
       "context": "Spacing (start/end edge to text)"
@@ -171,22 +188,10 @@
       "token": "component-pill-edge-to-visual-300",
       "context": "Spacing (start/end edge to text)"
     },
-    {
-      "token": "text-to-visual-75",
-      "context": "Spacing (icon to text)"
-    },
-    {
-      "token": "text-to-visual-100",
-      "context": "Spacing (icon to text)"
-    },
-    {
-      "token": "text-to-visual-200",
-      "context": "Spacing (icon to text)"
-    },
-    {
-      "token": "text-to-visual-300",
-      "context": "Spacing (icon to text)"
-    },
+    { "token": "text-to-visual-75", "context": "Spacing (icon to text)" },
+    { "token": "text-to-visual-100", "context": "Spacing (icon to text)" },
+    { "token": "text-to-visual-200", "context": "Spacing (icon to text)" },
+    { "token": "text-to-visual-300", "context": "Spacing (icon to text)" },
     {
       "token": "component-top-to-workflow-icon-75",
       "context": "Spacing (top edge to icon)"
@@ -203,82 +208,25 @@
       "token": "component-top-to-workflow-icon-300",
       "context": "Spacing (top edge to icon)"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Label"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Label"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Label"
-    },
-    {
-      "token": "component-s-regular",
-      "context": "Label"
-    },
-    {
-      "token": "component-m-regular",
-      "context": "Label"
-    },
-    {
-      "token": "component-l-regular",
-      "context": "Label"
-    },
-    {
-      "token": "component-xl-regular",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-font-size-75",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-font-size-100",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-font-size-200",
-      "context": "Label"
-    },
-    {
-      "token": "line-height-font-size-300",
-      "context": "Label"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Label"
-    },
-    {
-      "token": "gray-25",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-300",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-400",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-900",
-      "context": "Background and border"
-    },
-    {
-      "token": "gray-800",
-      "context": "Background and border"
-    },
+    { "token": "focus-indicator-thickness", "context": "Focus indicator" },
+    { "token": "focus-indicator-gap", "context": "Focus indicator" },
+    { "token": "default-font-family", "context": "Label" },
+    { "token": "regular-font-weight", "context": "Label" },
+    { "token": "default-font-style", "context": "Label" },
+    { "token": "component-s-regular", "context": "Label" },
+    { "token": "component-m-regular", "context": "Label" },
+    { "token": "component-l-regular", "context": "Label" },
+    { "token": "component-xl-regular", "context": "Label" },
+    { "token": "line-height-font-size-75", "context": "Label" },
+    { "token": "line-height-font-size-100", "context": "Label" },
+    { "token": "line-height-font-size-200", "context": "Label" },
+    { "token": "line-height-font-size-300", "context": "Label" },
+    { "token": "cjk-line-height-100", "context": "Label" },
+    { "token": "gray-25", "context": "Background and border" },
+    { "token": "gray-300", "context": "Background and border" },
+    { "token": "gray-400", "context": "Background and border" },
+    { "token": "gray-900", "context": "Background and border" },
+    { "token": "gray-800", "context": "Background and border" },
     {
       "token": "neutral-content-color-default",
       "context": "Value, label and icon"
@@ -299,10 +247,7 @@
       "token": "neutral-content-color-key-focus",
       "context": "Value, label and icon"
     },
-    {
-      "token": "gray-600",
-      "context": "Value, label and icon"
-    },
+    { "token": "gray-600", "context": "Value, label and icon" },
     {
       "token": "disabled-content-color",
       "context": "Background and border (disabled)"
@@ -311,36 +256,21 @@
       "token": "disabled-border-color",
       "context": "Background and border (disabled)"
     },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    }
+    { "token": "focus-indicator-color", "context": "Focus ring" }
   ],
   "accessibility": {
     "role": "textbox",
     "intents": ["input"],
     "focusable": true,
     "wcag": [
-      {
-        "criterion": "1.3.1",
-        "level": "A",
-        "title": "Info and Relationships"
-      },
+      { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
       {
         "criterion": "1.3.5",
         "level": "AA",
         "title": "Identify Input Purpose"
       },
-      {
-        "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" }
     ]
   }
 }