@adobe/spectrum-design-data 0.3.0 → 0.6.0

package/components/switch.json

@@ -9,135 +9,118 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/switch/"
   },
-  "options": {
-    "label": {
-      "type": "string"
-    },
-    "isSelected": {
-      "type": "boolean",
-      "default": false
-    },
-    "size": {
-      "type": "string",
-      "default": "m",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        },
-        {
-          "value": "xl"
-        }
-      ]
-    },
-    "isEmphasized": {
-      "type": "boolean",
-      "default": false
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "isReadOnly": {
-      "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": [
+  "documentBlocks": [
     {
-      "token": "component-height-75",
-      "context": "Minimum height"
+      "type": "purpose",
+      "content": "Switches allow users to turn an individual option on or off. They are usually used to activate or deactivate a specific setting."
     },
     {
-      "token": "component-height-100",
-      "context": "Minimum height"
+      "type": "guideline",
+      "content": "Switches toggle an individual option on or off. They're typically used to activate or deactivate a specific setting."
     },
     {
-      "token": "component-height-200",
-      "context": "Minimum height"
+      "type": "guideline",
+      "content": "Switch should always have a label for accessibility and clear comprehension. When the label is not defined, a switch becomes standalone. Standalone switches should only be used when their connection to other components is clear and they give sufficient context — for example, in application panels."
     },
     {
-      "token": "component-height-300",
-      "context": "Minimum height"
+      "type": "guideline",
+      "content": "Switches can either be selected or not selected. They cannot be in an indeterminate state (unlike checkboxes). When a switch represents multiple values that are not identical, the switch should appear as not selected."
     },
     {
-      "token": "corner-radius-full",
-      "context": "Rounding"
+      "type": "guideline",
+      "content": "Switch 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."
     },
     {
-      "token": "switch-control-width-small",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "By default, switches are not emphasized (gray). This version is optimal for when the switch 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": "switch-control-width-medium",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "The emphasized (blue) version provides a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a switch needs to be noticed."
     },
     {
-      "token": "switch-control-width-large",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "A switch in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later."
     },
     {
-      "token": "switch-control-width-extra-large",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "Switches have a read-only option for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed."
     },
     {
-      "token": "switch-control-height-small",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "A switch can be navigated using a keyboard. The keyboard focus state takes the switch’s visual hover state and adds a blue ring to the switch in focus."
     },
     {
-      "token": "switch-control-height-medium",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "When the label is too long for the horizontal space available, it wraps to form another line."
     },
     {
-      "token": "switch-control-height-large",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "Emphasized switches are optimal for forms, settings, and other scenarios where the switches need to be noticed. Not emphasized switches are optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
     },
     {
-      "token": "switch-control-height-extra-large",
-      "context": "Track (size)"
+      "type": "guideline",
+      "content": "Standalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options."
     },
     {
-      "token": "border-width-200",
-      "context": "Track (border)"
+      "type": "guideline",
+      "content": "Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list). Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode)."
     },
     {
-      "token": "switch-handle-size-small",
-      "context": "Handle (size)"
+      "type": "guideline",
+      "content": "When a switch represents multiple values that are not identical, the switch should appear as not selected. Any subsequent click or tap should select the switch, and update all values to be selected. Another click or tap after that should deselect the switch, and update all values to be not selected."
     },
     {
-      "token": "switch-handle-size-medium",
-      "context": "Handle (size)"
+      "type": "guideline",
+      "content": "Switches can only be on or off. Indeterminate switches don’t exist in accessibility APIs, so it’s not possible to make an indeterminate switch accessible. If you need to show a partial state, use a checkbox instead of a switch."
     },
     {
-      "token": "switch-handle-size-large",
-      "context": "Handle (size)"
-    },
-    {
-      "token": "switch-handle-size-extra-large",
-      "context": "Handle (size)"
+      "type": "guideline",
+      "content": "When a parent switch represents a group of switches, it should be turned off unless all of the switches are on (turning the parent switch on turns all of the switches on)."
+    }
+  ],
+  "options": {
+    "label": { "type": "string" },
+    "isSelected": { "type": "boolean", "default": false },
+    "size": {
+      "type": "string",
+      "default": "m",
+      "values": [
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
+      ]
     },
+    "isEmphasized": { "type": "boolean", "default": false },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isReadOnly": { "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": "component-height-75", "context": "Minimum height" },
+    { "token": "component-height-100", "context": "Minimum height" },
+    { "token": "component-height-200", "context": "Minimum height" },
+    { "token": "component-height-300", "context": "Minimum height" },
+    { "token": "corner-radius-full", "context": "Rounding" },
+    { "token": "switch-control-width-small", "context": "Track (size)" },
+    { "token": "switch-control-width-medium", "context": "Track (size)" },
+    { "token": "switch-control-width-large", "context": "Track (size)" },
+    { "token": "switch-control-width-extra-large", "context": "Track (size)" },
+    { "token": "switch-control-height-small", "context": "Track (size)" },
+    { "token": "switch-control-height-medium", "context": "Track (size)" },
+    { "token": "switch-control-height-large", "context": "Track (size)" },
+    { "token": "switch-control-height-extra-large", "context": "Track (size)" },
+    { "token": "border-width-200", "context": "Track (border)" },
+    { "token": "switch-handle-size-small", "context": "Handle (size)" },
+    { "token": "switch-handle-size-medium", "context": "Handle (size)" },
+    { "token": "switch-handle-size-large", "context": "Handle (size)" },
+    { "token": "switch-handle-size-extra-large", "context": "Handle (size)" },
     {
       "token": "switch-handle-selected-size-small",
       "context": "Handle (size)"
@@ -154,22 +137,10 @@
       "token": "switch-handle-selected-size-extra-large",
       "context": "Handle (size)"
     },
-    {
-      "token": "text-to-control-75",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-100",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-200",
-      "context": "Spacing (control to label)"
-    },
-    {
-      "token": "text-to-control-300",
-      "context": "Spacing (control to label)"
-    },
+    { "token": "text-to-control-75", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-100", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-200", "context": "Spacing (control to label)" },
+    { "token": "text-to-control-300", "context": "Spacing (control to label)" },
     {
       "token": "switch-top-to-control-small",
       "context": "Spacing (top edge to control)"
@@ -218,14 +189,8 @@
       "token": "component-bottom-to-text-300",
       "context": "Spacing (top/bottom edge to label)"
     },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus indicator"
-    },
+    { "token": "focus-indicator-thickness", "context": "Focus indicator" },
+    { "token": "focus-indicator-gap", "context": "Focus indicator" },
     {
       "token": "component-size-difference-down",
       "context": "Component size (down)"
@@ -238,58 +203,19 @@
       "token": "component-size-minimum-perspective-down",
       "context": "Component size (down)"
     },
-    {
-      "token": "font-size-75",
-      "context": "Font size"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Font size"
-    },
-    {
-      "token": "font-size-200",
-      "context": "Font size"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Font size"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Font size"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Font size"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Font size"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Font size"
-    },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-hover",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-down",
-      "context": "Label"
-    },
-    {
-      "token": "neutral-content-color-key-focus",
-      "context": "Label"
-    },
-    {
-      "token": "gray-25",
-      "context": "Control"
-    },
+    { "token": "font-size-75", "context": "Font size" },
+    { "token": "font-size-100", "context": "Font size" },
+    { "token": "font-size-200", "context": "Font size" },
+    { "token": "font-size-300", "context": "Font size" },
+    { "token": "default-font-family", "context": "Font size" },
+    { "token": "regular-font-weight", "context": "Font size" },
+    { "token": "line-height-100", "context": "Font size" },
+    { "token": "cjk-line-height-100", "context": "Font size" },
+    { "token": "neutral-content-color-default", "context": "Label" },
+    { "token": "neutral-content-color-hover", "context": "Label" },
+    { "token": "neutral-content-color-down", "context": "Label" },
+    { "token": "neutral-content-color-key-focus", "context": "Label" },
+    { "token": "gray-25", "context": "Control" },
     {
       "token": "accent-content-color-default",
       "context": "Control (selected, emphasized)"
@@ -306,14 +232,8 @@
       "token": "accent-content-color-key-focus",
       "context": "Control (selected, emphasized)"
     },
-    {
-      "token": "disabled-content-color",
-      "context": "Label (disabled)"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus indicator"
-    }
+    { "token": "disabled-content-color", "context": "Label (disabled)" },
+    { "token": "focus-indicator-color", "context": "Focus indicator" }
   ],
   "accessibility": {
     "role": "switch",
@@ -321,16 +241,8 @@
     "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/table.json

@@ -9,22 +9,85 @@
     "category": "data-visualization",
     "documentationUrl": "https://spectrum.adobe.com/page/table/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Tables display information in rows and columns, allowing users to compare and scan structured data."
+    },
+    {
+      "type": "guideline",
+      "content": "Tables organize and display structured information in rows and columns. They support scanning, sorting, comparing, and interacting with large amounts of data. Use when multiple data points need to be reviewed or acted on in one place."
+    },
+    {
+      "type": "guideline",
+      "content": "Tables come in three sizes: small, medium, and large. Size affects the overall scale, including font size and spacing. Medium is the default. Use large for high-visibility tables or when readability is critical. Use small in constrained spaces or when the table is secondary to other content."
+    },
+    { "type": "guideline", "content": "If true, the table header is hidden." },
+    {
+      "type": "guideline",
+      "content": "Configuration for the table header row."
+    },
+    {
+      "type": "guideline",
+      "content": "Tables come in three densities: compact, regular, and spacious. Density controls vertical spacing while keeping font sizes consistent—compact rows have tighter padding, spacious rows have more breathing room. Regular is the default for most use cases. Use compact when fitting more data in a limited viewport is critical (e.g., dashboards, data-heavy admin panels). Use spacious when scannability and visual comfort are priorities (e.g., transaction histories, settings tables with minimal data)."
+    },
+    {
+      "type": "guideline",
+      "content": "Use a standard table when a table is the main focus of an experience. Quiet tables are for when a table is meant to be supplementary, subtle, or lightweight."
+    },
+    { "type": "guideline", "content": "If true, table columns can be sorted." },
+    {
+      "type": "guideline",
+      "content": "An array of column definitions for the table."
+    },
+    { "type": "guideline", "content": "An array of row data for the table." },
+    {
+      "type": "guideline",
+      "content": "Column dividers help organize table content and aid users in parsing related data. You can apply dividers selectively to group related columns—for example, separating user information from action columns, or grouping metadata fields together. Use dividers sparingly to avoid visual clutter."
+    },
+    {
+      "type": "guideline",
+      "content": "All tables have a hover state regardless of if actions or selections can be made. This aids the user in viewing content in a single row."
+    },
+    {
+      "type": "guideline",
+      "content": "Similar to a paragraph of text, textual data should be start-aligned within a table (left-aligned in LTR languages, right-aligned in RTL languages). Never use center alignment."
+    },
+    {
+      "type": "guideline",
+      "content": "Numerical data should generally be right-aligned for ease of scanning and comparing. This alignment typically does NOT reverse in RTL languages because:"
+    },
+    {
+      "type": "guideline",
+      "content": "Exception: Use start-alignment (left in LTR, right in RTL) when numbers are arbitrary identifiers, known as \"nominal numbers,\" which can't be compared or combined arithmetically (e.g., ZIP codes, IP addresses, phone numbers). These behave like text."
+    },
+    {
+      "type": "guideline",
+      "content": "Column headers follow the alignment of their data."
+    },
+    {
+      "type": "guideline",
+      "content": "All content should be centered vertically within the row to offer the right visual balance."
+    },
+    {
+      "type": "guideline",
+      "content": "Tables use row dividers, hover states, and selection highlighting to help users track data. Zebra striping adds visual noise without improving usability."
+    },
+    {
+      "type": "guideline",
+      "content": "Column dividers are optional decorations that can help organize table content and create groups of data. Only use these when necessary, and don't add them to every column."
+    },
+    {
+      "type": "guideline",
+      "content": "When there are gaps in the data, use an en dash (–) to represent null or not applicable (N/A) values."
+    }
+  ],
   "options": {
     "size": {
       "type": "string",
       "default": "m",
       "description": "Controls the density of table rows.",
-      "values": [
-        {
-          "value": "s"
-        },
-        {
-          "value": "m"
-        },
-        {
-          "value": "l"
-        }
-      ]
+      "values": [{ "value": "s" }, { "value": "m" }, { "value": "l" }]
     },
     "hideHeader": {
       "type": "boolean",
@@ -53,15 +116,9 @@
       "type": "string",
       "default": "regular",
       "values": [
-        {
-          "value": "compact"
-        },
-        {
-          "value": "regular"
-        },
-        {
-          "value": "spacious"
-        }
+        { "value": "compact" },
+        { "value": "regular" },
+        { "value": "spacious" }
       ]
     },
     "isQuiet": {
@@ -136,22 +193,14 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "chevron-100",
-      "context": "Header icons"
-    },
+    { "token": "chevron-100", "context": "Header icons" },
     {
       "token": "corner-radius-medium-size-extra-small",
       "context": "Note: desktop 6px, mobile 6px;"
     },
-    {
-      "token": "component-height-100",
-      "context": "Column header row height"
-    },
+    { "token": "component-height-100", "context": "Column header row height" },
     {
       "token": "table-column-header-row-top-to-text-medium",
       "context": "Spacing (column header row top/bottom to text)"
@@ -244,22 +293,13 @@
       "token": "accent-content-color-selected",
       "context": "Selection indicator"
     },
-    {
-      "token": "border-width-100",
-      "context": "Note: 1px;"
-    },
+    { "token": "border-width-100", "context": "Note: 1px;" },
     {
       "token": "corner-radius-small-default",
       "context": "Focus indicator (cell)"
     },
-    {
-      "token": "side-focus-indicator",
-      "context": "Focus indicator (row)"
-    },
-    {
-      "token": "body-color",
-      "context": "Column header and row (text)"
-    },
+    { "token": "side-focus-indicator", "context": "Focus indicator (row)" },
+    { "token": "body-color", "context": "Column header and row (text)" },
     {
       "token": "neutral-subdued-content-color-default",
       "context": "Row: not selected"
@@ -304,18 +344,9 @@
       "token": "gray-75",
       "context": "Column header and row (background, border and divider)"
     },
-    {
-      "token": "gray-200",
-      "context": "Summary row (background)"
-    },
-    {
-      "token": "gray-100",
-      "context": "Row (disabled)"
-    },
-    {
-      "token": "gray-400",
-      "context": "Row (disabled)"
-    },
+    { "token": "gray-200", "context": "Summary row (background)" },
+    { "token": "gray-100", "context": "Row (disabled)" },
+    { "token": "gray-400", "context": "Row (disabled)" },
     {
       "token": "stack-item-background-color-hover",
       "context": "Row (not selected, hover)"
@@ -348,38 +379,14 @@
       "token": "table-selected-row-background-opacity-highlight-hover",
       "context": "Selected row background (highlight selection, hover)"
     },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus indicator (cell)"
-    },
-    {
-      "token": "default-font-family",
-      "context": "Column header and row"
-    },
-    {
-      "token": "bold-font-weight",
-      "context": "Column header and row"
-    },
-    {
-      "token": "default-font-style",
-      "context": "Column header and row"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Column header and row"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Column header and row"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Column header and row"
-    },
-    {
-      "token": "regular-font-weight",
-      "context": "Column header and row"
-    },
+    { "token": "focus-indicator-color", "context": "Focus indicator (cell)" },
+    { "token": "default-font-family", "context": "Column header and row" },
+    { "token": "bold-font-weight", "context": "Column header and row" },
+    { "token": "default-font-style", "context": "Column header and row" },
+    { "token": "font-size-100", "context": "Column header and row" },
+    { "token": "line-height-100", "context": "Column header and row" },
+    { "token": "cjk-line-height-100", "context": "Column header and row" },
+    { "token": "regular-font-weight", "context": "Column header and row" },
     {
       "token": "table-row-hover-color;",
       "context": "S1 Row (not selected, hover)"
@@ -415,21 +422,9 @@
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate", "select-all"],
     "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" }
     ]
   }
 }