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

package/components/link.json

@@ -16,112 +16,80 @@
     },
     {
       "type": "guideline",
-      "content": "Links provide navigation to a different location. They can appear within a paragraph or as standalone text."
+      "content": "Use links in body copy.\n\nLinks are for usage in body copy and are not appropriate in titles. Consider using a different component if you're looking for a larger or more prominent call to action, such as a button."
     },
     {
       "type": "guideline",
-      "content": "Use the static color option when a link needs to be placed on top of a color background or visual. Static color links are available in black or white, regardless of color theme. They can also be placed on top of a custom background that isn’t part of a Spectrum color theme."
+      "content": "Support screen readers.\n\nBe mindful of link placement and language, and create experiences that are inclusive of users navigating with screen readers. Screen readers pull a list of links — only the link text, and not including other surrounding language — to determine the content of the page. People using screen readers may tab between links without getting the text in between, so very generic link wording like \"learn more\" or \"click here\" doesn't communicate any context from elsewhere in the experience. Identify the target of each link directly in the link text to communicate context and set clear expectations about where the link will go."
     },
     {
       "type": "guideline",
-      "content": "Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of color theme. Make sure that the background and the link color meet the minimum color contrast ratio."
+      "content": "When to use quiet links.\n\nQuiet links are less accessible, so don't use them for links that are critical to an experience. Quiet links are commonly used in website footers, where there are several lists of links that are shortcuts to other pages."
     },
     {
       "type": "guideline",
-      "content": "All links can have a quiet style, without an underline. This style should only be used when the placement and context of the link is explicit enough that a visible underline isn’t necessary."
+      "content": "Standalone links are not full sentences, and do not have punctuation at the end. Treat these like calls-to-action by writing them as short verb phrases. Since standalone links are at the end of a sentence or paragraph, they're often perceived by users as optional or supplementary to surrounding content."
     },
     {
       "type": "guideline",
-      "content": "The variant property defines the visual style of a link and includes two options: primary and secondary."
+      "content": "Links within sentences.\n\nLinks within — or as — sentences are written just like they're part of a paragraph. Make sure you include enough context in the link text to communicate the value and expectation of the landing experience. This approach can draw a user's focus to the linked text, such as for need-to-know updates or high-signal information. If the link leads to more content, it can be helpful to write it as a descriptive noun (e.g., \"survey feedback\"). If the link launches a task or action, start it with a verb (e.g., \"Share your feedback\"). Keep in mind that it's easier to localize links that are entire sentences, rather than sentence fragments. This is because, depending on which part of a sentence is included as a link, the word and link order may be re-arranged when translated."
     },
     {
       "type": "guideline",
-      "content": "The primary variant is the default style and displays the link in Spectrum blue. It is intended to draw attention to the link and is suitable when the blue color complements the surrounding content without being overwhelming."
+      "content": "Avoid generic language.\n\nAvoid overly generic link language like \"learn more,\" \"click here,\" \"more information,\" or \"continue reading.\" It's more accessible and inclusive to write link text as unique descriptions of the navigational target or function. Links need to be descriptive enough that they make sense without any other context. Generic links don't make sense out of context, and don't communicate where they go or what happens if a user interacts with them. Unique link language is essential for screen reader and magnification users who may not have the supplementary language around a link, or may not follow the content order of an experience. Try to avoid using a series of generic, standalone links that say \"learn more\" at the end of multiple sentences or paragraphs as a truncation strategy."
     },
     {
       "type": "guideline",
-      "content": "The secondary variant uses the same gray color as the surrounding paragraph text. Its subdued appearance is ideal for scenarios where multiple links are present in a block of text and the primary variant would be too visually dominant."
+      "content": "Write specific and descriptive link text.\n\nLinks act as wayfinding tools that offer contextual clues about how to navigate an experience. Write link text so that, even if someone were not able to view any surrounding context, they could still understand a link's purpose and what they should expect by interacting with it. Try to front load the link with the most important word(s)."
     },
     {
       "type": "guideline",
-      "content": "Links are for usage in body copy and are not appropriate in titles. Consider using a different component if you're looking for a larger or more prominent call to action, such as a button."
+      "content": "Be conscious about repetition.\n\nDon't use the same link text to link to different information in the same view. If link text needs to be duplicated within a single page or view, find ways to make each link unique, such as using accessibility labels or other text alternatives. It's OK to incorporate multiple links into the same sentence as long as the links are contextual and relevant. Do not overload sentences and pages with links purely for SEO purposes."
     },
     {
       "type": "guideline",
-      "content": "Be mindful of link placement and language, and create experiences that are inclusive of users navigating with screen readers. Screen readers pull a list of links — only the link text, and not including other surrounding language — to determine the content of the page."
+      "content": "Create intuitive landing experiences.\n\nDon't place a generic \"Learn more\" link in design specs without thinking through what happens when a user interacts with that link. The landing experience needs to work in partnership with how the link text is written. Identify exactly where that link will go or what it will do, then ensure the link text reflects that. Use anchor links whenever possible to ensure that users can quickly find the most helpful next steps after interacting with a link. Collaborate with help content writers or customer service representatives to determine the most natural and intuitive content to supplement your experience."
     },
     {
       "type": "guideline",
-      "content": "People using screen readers may tab between links without getting the text in between, so very generic link wording like “learn more” or “click here” doesn’t communicate any context from elsewhere in the experience. Identify the target of each link directly in the link text to communicate context and set clear expectations about where the link will go."
+      "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the link component.EnterExecutes the link and moves the focus to the link target."
     },
     {
       "type": "guideline",
-      "content": "Quiet links are less accessible, so don't use them for links that are critical to an experience. Quiet links are commonly used in website footers, where there are several lists of links that are shortcuts to other pages."
+      "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for interactive components like links."
+    },
+    {
+      "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 Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAALinks should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey that text is a link. Links are paired with an additional visual indicator, such as an underline, so the link purpose is communicated without relying on color alone.Text contrast 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.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 link states has 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."
     }
   ],
   "options": {
     "variant": {
       "type": "string",
       "default": "primary",
-      "values": [
-        {
-          "value": "primary"
-        },
-        {
-          "value": "secondary"
-        }
-      ]
-    },
-    "isQuiet": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "primary" }, { "value": "secondary" }]
     },
+    "isQuiet": { "type": "boolean", "default": false },
     "staticColor": {
       "type": "string",
       "description": "Static color must not be set for the default version of this component.",
-      "values": [
-        {
-          "value": "white"
-        },
-        {
-          "value": "black"
-        }
-      ]
+      "values": [{ "value": "white" }, { "value": "black" }]
     }
   },
   "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": "link",
     "intents": ["navigate"],
     "focusable": true,
     "keyboardIntents": ["activate"],
     "wcag": [
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      },
-      {
-        "criterion": "4.1.2",
-        "level": "A",
-        "title": "Name, Role, Value"
-      }
+      { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
+      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
     ]
   }
 }

package/components/list-view.json

@@ -16,67 +16,31 @@
     },
     {
       "type": "guideline",
-      "content": "List views display content in a structured, scrollable list. They support sorting, organizing, and selecting multiple items at once."
+      "content": "Navigation.\n\nIn the highlight selection style for touch interactions, tapping anywhere on the item will navigate to its contents. For mouse-based interactions, double-clicking anywhere on the item or single-clicking the navigation icon will do the same. In the checkbox selection style, clicking or tapping the label area or navigation icon of a list view item will navigate to its contents."
     },
     {
       "type": "guideline",
-      "content": "A list view is a versatile component and can contain many items depending on the use case. These items can be icons, thumbnails, avatars, checkboxes, drag handles, action buttons, and more."
+      "content": "Selection.\n\nSingle-clicking or tapping anywhere on a list view item will select the item, except the label in checkbox selection style. For checkbox selection style, clicking the label will navigate to the item."
     },
     {
       "type": "guideline",
-      "content": "By default a list view is not quiet. If true, the list view uses a quiet visual style meaning there is no background or borders to the component."
+      "content": "Touch navigation and selection.\n\nIn touch experiences, the list view default is navigation only with the highlight selection style. Users enter a selection mode by a touch and hold gesture on any list view item. Selection mode in touch uses the checkbox selection style and suppresses navigation. Users can exit selection mode by pressing the Escape key or deselecting all items."
     },
     {
       "type": "guideline",
-      "content": "The selection mode defines how many items can be selected at once. A list view can use single selection, multiple selection, or none."
+      "content": "Drag and drop.\n\nList view items can be dragged and dropped to reorder or restructure the list. Multiple items can be dragged at a time and shifted from one level of hierarchy to another. List views can also accept dropped items from outside the component, to modify the list. Keyboard-based drag and drop When using this option for a list view, the drag icon receives keyboard focus in order to allow for a keyboard-based drag and drop interaction. Touch-based drag and drop The drag and drop interaction is initiated by a touch and hold gesture, followed by drag gesture. If a user performs a touch and hold gesture without dragging, the list view enters a selection mode."
     },
     {
       "type": "guideline",
-      "content": "In the highlight selection style for touch interactions, tapping anywhere on the item will navigate to its contents. For mouse-based interactions, double-clicking anywhere on the item or single-clicking the navigation icon will do the same."
+      "content": "Text overflow.\n\nA list view item's label or description will truncate if the text is longer than the available horizontal space. Display the full label or description text in a tooltip on hover and focus states."
     },
     {
       "type": "guideline",
-      "content": "In the checkbox selection style, clicking or tapping the label area or navigation icon of a list view item will navigate to its contents."
+      "content": "Actions overflow.\n\nWhen more than two actions are available for a list view item, the actions are nested within an action menu."
     },
     {
       "type": "guideline",
-      "content": "Single-clicking or tapping anywhere on a list view item will select the item, except the label in checkbox selection style. For checkbox selection style, clicking the label will navigate to the item."
-    },
-    {
-      "type": "guideline",
-      "content": "In touch experiences, the list view default is navigation only with the highlight selection style. Users enter a selection mode by a touch and hold gesture on any list view item."
-    },
-    {
-      "type": "guideline",
-      "content": "Selection mode in touch uses the checkbox selection style and suppresses navigation. Users can exit selection mode by pressing the Escape key or deselecting all items."
-    },
-    {
-      "type": "guideline",
-      "content": "List view items can be dragged and dropped to reorder or restructure the list."
-    },
-    {
-      "type": "guideline",
-      "content": "Multiple items can be dragged at a time and shifted from one level of hierarchy to another."
-    },
-    {
-      "type": "guideline",
-      "content": "List views can also accept dropped items from outside the component, to modify the list."
-    },
-    {
-      "type": "guideline",
-      "content": "A list view item's label or description will truncate if the text is longer than the available horizontal space. Display the full label or description text in a tooltip on hover and focus states."
-    },
-    {
-      "type": "guideline",
-      "content": "When more than two actions are available for a list view item, the actions are nested within an action menu."
-    },
-    {
-      "type": "guideline",
-      "content": "List views work best for flat collections of items that share the same hierarchy level."
-    },
-    {
-      "type": "guideline",
-      "content": "Tree views are ideal for displaying nested or hierarchical relationships."
+      "content": "When to use a List view vs. Tree view.\n\nList views work best for flat collections of items that share the same hierarchy level. Tree views are ideal for displaying nested or hierarchical relationships."
     }
   ],
   "options": {
@@ -85,15 +49,9 @@
       "default": "single",
       "description": "Defines how many items can be selected at once.",
       "values": [
-        {
-          "value": "none"
-        },
-        {
-          "value": "single"
-        },
-        {
-          "value": "multiple"
-        }
+        { "value": "none" },
+        { "value": "single" },
+        { "value": "multiple" }
       ]
     },
     "isQuiet": {
@@ -152,10 +110,7 @@
             "default": "none",
             "description": "Defines the border radius of the list view item."
           },
-          "isEmphasized": {
-            "type": "boolean",
-            "default": false
-          },
+          "isEmphasized": { "type": "boolean", "default": false },
           "state": {
             "type": "string",
             "enum": ["default", "hover", "dragged"],
@@ -185,10 +140,7 @@
       "name": "checkbox",
       "description": "Checkbox control for a list view item in checkbox selection style."
     },
-    {
-      "name": "icon",
-      "description": "Leading icon of a list view item."
-    },
+    { "name": "icon", "description": "Leading icon of a list view item." },
     {
       "name": "thumbnail",
       "description": "Thumbnail image of a list view item."
@@ -210,24 +162,14 @@
       "description": "Icon indicating a list view item navigates to a new context."
     }
   ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "intents": ["select", "navigate"],
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate", "select-all"],
     "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" }
     ]
   }
 }