@adobe/spectrum-design-data 0.3.0 → 0.6.0

package/components/calendar.json

@@ -9,6 +9,96 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/calendar/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Calendars display days, weeks, and months, allowing users to select dates or ranges."
+    },
+    {
+      "type": "guideline",
+      "content": "Calendars display the days of a selected month and highlight the current day. They support navigating to past or future months and selecting a specific date."
+    },
+    {
+      "type": "guideline",
+      "content": "An array of days that are displayed in the current calendar view. This includes:"
+    },
+    {
+      "type": "guideline",
+      "content": "The maximum amount of months displayed in the calendar popover is three."
+    },
+    {
+      "type": "guideline",
+      "content": "The minimum amount of months displayed in the calendar popover is one."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover may display an error as error text when a user attempts to provide an input that violates the defined constraints of the date selection. For example, when the user selects dates that fall outside allowable limits, or conflict with contextual restrictions."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover is disabled. For example, a month within a three-month range is disabled."
+    },
+    {
+      "type": "guideline",
+      "content": "The types of selection available for the calendar."
+    },
+    {
+      "type": "guideline",
+      "content": "The current year or month displayed in the calendar popover."
+    },
+    {
+      "type": "guideline",
+      "content": "When a day or several days are unavailable within the calendar popover, each day should display a strikethrough to help the user understand that they cannot select it."
+    },
+    {
+      "type": "guideline",
+      "content": "Disabled days use a distinct gray style to clearly differentiate them from unavailable days. When the calendar prevents selection of past dates, this visual treatment helps users distinguish disabled days from those marked as unavailable."
+    },
+    {
+      "type": "guideline",
+      "content": "In a date selection system, users often need to distinguish between dates that cannot be selected and dates that are simply inactive. Supporting both states improves clarity and prevents errors."
+    },
+    {
+      "type": "guideline",
+      "content": "Here’s an example scenario: A potential guest is browsing a calendar to book a stay at a vacation rental."
+    },
+    {
+      "type": "guideline",
+      "content": "Unavailable dates: Days when the rental is already booked or blocked by the owner. These appear with a strikethrough, indicating they cannot be selected."
+    },
+    {
+      "type": "guideline",
+      "content": "Disabled dates: Past dates that are no longer valid for booking. These appear visually distinct (gray style) to show they are inactive."
+    },
+    {
+      "type": "guideline",
+      "content": "Guests see unavailable dates marked clearly so they don’t attempt to select them. Hosts or admins can view past dates as disabled and also mark future dates as unavailable when needed."
+    },
+    {
+      "type": "guideline",
+      "content": "By supporting both behaviors, the system provides a clear, intuitive experience for different user roles and prevents confusion during date selection."
+    },
+    {
+      "type": "guideline",
+      "content": "The range fill shows which days fall between two selected dates. If the range spans more than the three-month calendar view, it ends on the last visible day but continues as users navigate with the calendar chevrons. A dashed stroke outlines the fill to improve visibility on bright screens and for users with vision impairments."
+    },
+    {
+      "type": "guideline",
+      "content": "The strikethrough styling intentionally accommodates internationalization."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover supports a disabled state but not a read-only state. Dates or months may be temporarily disabled based on context (for example, if a user must complete a task before selecting a date). In these cases, help text can explain why certain dates are unavailable."
+    },
+    {
+      "type": "guideline",
+      "content": "If a date picker is truly read-only, users shouldn’t be able to open the calendar popover at all, since they can’t interact with it."
+    },
+    {
+      "type": "guideline",
+      "content": "The calendar popover can also include time-specific fields, allowing users to specify start and end times."
+    }
+  ],
   "options": {
     "currentMonth": {
       "type": "number",
@@ -24,23 +114,10 @@
       "type": "string",
       "default": "single",
       "description": "Controls whether the calendar allows selecting a single date or a date range.",
-      "values": [
-        {
-          "value": "single"
-        },
-        {
-          "value": "range"
-        }
-      ]
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    },
-    "isError": {
-      "type": "boolean",
-      "default": false
+      "values": [{ "value": "single" }, { "value": "range" }]
     },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isError": { "type": "boolean", "default": false },
     "minValue": {
       "type": "string",
       "description": "The minimum allowed date that a user may select (ISO format string)."
@@ -105,29 +182,15 @@
       }
     }
   },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "accessibility": {
     "intents": ["input", "choose"],
     "focusable": true,
     "keyboardIntents": ["navigate-items", "activate"],
     "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/cards.json

@@ -9,105 +9,98 @@
     "category": "containers",
     "documentationUrl": "https://spectrum.adobe.com/page/cards/"
   },
-  "options": {
-    "variant": {
-      "type": "string",
-      "default": "asset",
-      "description": "Determines which card layout variant is used.",
-      "values": [
-        {
-          "value": "asset"
-        },
-        {
-          "value": "collection"
-        },
-        {
-          "value": "flex"
-        },
-        {
-          "value": "gallery"
-        },
-        {
-          "value": "horizontal"
-        },
-        {
-          "value": "product"
-        }
-      ]
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
-    {
-      "token": "card-minimum-width-extra-small",
-      "context": "Width (minimum)"
-    },
-    {
-      "token": "card-minimum-width-small",
-      "context": "Width (minimum)"
-    },
+  "documentBlocks": [
     {
-      "token": "card-minimum-width-medium",
-      "context": "Width (minimum)"
+      "type": "purpose",
+      "content": "Cards group related content into distinct layouts depending on context."
     },
     {
-      "token": "card-minimum-width-large",
-      "context": "Width (minimum)"
+      "type": "guideline",
+      "content": "Cards group related content and actions into flexible containers for browsing. They preview key information and reveal more detail on interaction."
     },
     {
-      "token": "card-minimum-width-extra-large",
-      "context": "Width (minimum)"
+      "type": "guideline",
+      "content": "Card preview areas have a maximum image height aspect ratio of 3:4, and a minimum height aspect ratio of of 4:1."
     },
     {
-      "token": "card-default-width-extra-small",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "If the card has a fixed height, such as in a tile grid, long titles will be truncated. Use short titles to avoid this. In layouts with variable height, like a waterfall grid, titles will wrap to fit."
     },
     {
-      "token": "card-default-width-small",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "Cards, by definition, should have some form of interaction such as viewing, editing, purchasing, etc. Some actions are exposed in buttons, and others simply occur by clicking the card."
     },
     {
-      "token": "card-default-width-medium",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "If a card only has an ability to be opened or viewed in more detail, do not include a button. Clicking anywhere on the card should perform that action."
     },
     {
-      "token": "card-default-width-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "If a card has other interactive elements such as a hidden actions menu or an avatar, but no buttons, the whole card (outside of those elements) should be clickable."
     },
     {
-      "token": "card-default-width-extra-large",
-      "context": "Width (default)"
+      "type": "guideline",
+      "content": "If there’s only one action (that’s not opening or viewing the card), use a button to communicate that action. If there are two or more available actions, and one of those actions is to open or view the card, use a button to communicate “View” or “Open,” instead of relying on clicking on the card."
     },
     {
-      "token": "card-maximum-width-extra-small",
-      "context": "Width (maximum)"
+      "type": "guideline",
+      "content": "If a standard card has a footer with a button, only the button is clickable. If a card has a preview, clicking the preview will open that card. When a preview is purely decorative, it is not clickable."
     },
     {
-      "token": "card-maximum-width-small",
-      "context": "Width (maximum)"
+      "type": "guideline",
+      "content": "When a group of cards are loading, they follow the ghost loading convention. There are 5 phases for ghost loading:"
     },
     {
-      "token": "card-maximum-width-medium",
-      "context": "Width (maximum)"
+      "type": "guideline",
+      "content": "Cards are meant to just show a taste of the available information. Don’t overload cards with more information than necessary."
     },
     {
-      "token": "card-maximum-width-large",
-      "context": "Width (maximum)"
+      "type": "guideline",
+      "content": "Only standard cards can have a footer, and buttons can only appear inside a footer."
     },
     {
-      "token": "card-maximum-width-extra-large",
-      "context": "Width (maximum)"
+      "type": "guideline",
+      "content": "Individual cards are not aligned to individual columns in the page's responsive column grid. Instead, groups of cards are aligned to the column grid in a layout region."
     },
     {
-      "token": "corner-radius-medium-default",
-      "context": "Rounding"
-    },
-    {
-      "token": "corner-radius-large-default",
-      "context": "Rounding"
-    },
+      "type": "guideline",
+      "content": "If the preview is a video clip or other moving item, do not automatically play the clip or motion. Save the movement for either when a user hovers on the card or when they click on a play button."
+    }
+  ],
+  "options": {
+    "variant": {
+      "type": "string",
+      "default": "asset",
+      "description": "Determines which card layout variant is used.",
+      "values": [
+        { "value": "asset" },
+        { "value": "collection" },
+        { "value": "flex" },
+        { "value": "gallery" },
+        { "value": "horizontal" },
+        { "value": "product" }
+      ]
+    }
+  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "card-minimum-width-extra-small", "context": "Width (minimum)" },
+    { "token": "card-minimum-width-small", "context": "Width (minimum)" },
+    { "token": "card-minimum-width-medium", "context": "Width (minimum)" },
+    { "token": "card-minimum-width-large", "context": "Width (minimum)" },
+    { "token": "card-minimum-width-extra-large", "context": "Width (minimum)" },
+    { "token": "card-default-width-extra-small", "context": "Width (default)" },
+    { "token": "card-default-width-small", "context": "Width (default)" },
+    { "token": "card-default-width-medium", "context": "Width (default)" },
+    { "token": "card-default-width-large", "context": "Width (default)" },
+    { "token": "card-default-width-extra-large", "context": "Width (default)" },
+    { "token": "card-maximum-width-extra-small", "context": "Width (maximum)" },
+    { "token": "card-maximum-width-small", "context": "Width (maximum)" },
+    { "token": "card-maximum-width-medium", "context": "Width (maximum)" },
+    { "token": "card-maximum-width-large", "context": "Width (maximum)" },
+    { "token": "card-maximum-width-extra-large", "context": "Width (maximum)" },
+    { "token": "corner-radius-medium-default", "context": "Rounding" },
+    { "token": "corner-radius-large-default", "context": "Rounding" },
     {
       "token": "card-edge-to-content-compact-extra-small",
       "context": "Spacing (top/side/bottom edge to content, extra small)"
@@ -168,74 +161,26 @@
       "token": "card-edge-to-content-spacious-extra-large",
       "context": "Spacing (top/side/bottom edge to content, extra large)"
     },
-    {
-      "token": "border-width-200",
-      "context": "Border"
-    },
-    {
-      "token": "focus-indicator-thickness",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "focus-indicator-gap",
-      "context": "Focus indicator"
-    },
-    {
-      "token": "background-layer-2-color",
-      "context": "Background"
-    },
-    {
-      "token": "background-layer-1-color",
-      "context": "Background"
-    },
-    {
-      "token": "card-background-well-color",
-      "context": "Well"
-    },
-    {
-      "token": "gray-100",
-      "context": "Border"
-    },
-    {
-      "token": "gray-200",
-      "context": "Border"
-    },
-    {
-      "token": "neutral-subdued-content-color-selected",
-      "context": "Border"
-    },
-    {
-      "token": "focus-indicator-color",
-      "context": "Focus ring"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "opacity-disabled",
-      "context": "Disabled"
-    },
-    {
-      "token": "card-background-color-loading",
-      "context": "Loading"
-    },
+    { "token": "border-width-200", "context": "Border" },
+    { "token": "focus-indicator-thickness", "context": "Focus indicator" },
+    { "token": "focus-indicator-gap", "context": "Focus indicator" },
+    { "token": "background-layer-2-color", "context": "Background" },
+    { "token": "background-layer-1-color", "context": "Background" },
+    { "token": "card-background-well-color", "context": "Well" },
+    { "token": "gray-100", "context": "Border" },
+    { "token": "gray-200", "context": "Border" },
+    { "token": "neutral-subdued-content-color-selected", "context": "Border" },
+    { "token": "focus-indicator-color", "context": "Focus ring" },
+    { "token": "disabled-background-color", "context": "Disabled" },
+    { "token": "opacity-disabled", "context": "Disabled" },
+    { "token": "card-background-color-loading", "context": "Loading" },
     {
       "token": "card-minimum-height-extra-small",
       "context": "Height (minimum)"
     },
-    {
-      "token": "card-minimum-height-small",
-      "context": "Height (minimum)"
-    },
-    {
-      "token": "card-minimum-height-medium",
-      "context": "Height (minimum)"
-    },
-    {
-      "token": "card-minimum-height-large",
-      "context": "Height (minimum)"
-    },
+    { "token": "card-minimum-height-small", "context": "Height (minimum)" },
+    { "token": "card-minimum-height-medium", "context": "Height (minimum)" },
+    { "token": "card-minimum-height-large", "context": "Height (minimum)" },
     {
       "token": "card-minimum-height-extra-large",
       "context": "Height (minimum)"
@@ -284,78 +229,24 @@
       "token": "card-header-to-description",
       "context": "Spacing (header to description)"
     },
-    {
-      "token": "border-width-400",
-      "context": "Border"
-    },
-    {
-      "token": "title-color",
-      "context": "Value"
-    },
-    {
-      "token": "body-color",
-      "context": "Value"
-    },
-    {
-      "token": "neutral-content-color-default",
-      "context": "Value"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Disabled"
-    },
-    {
-      "token": "title-sans-serif-font-family",
-      "context": "Title"
-    },
-    {
-      "token": "title-sans-serif-font-weight",
-      "context": "Title"
-    },
-    {
-      "token": "title-serif-font-style",
-      "context": "Title"
-    },
-    {
-      "token": "font-size-50",
-      "context": "Title"
-    },
-    {
-      "token": "font-size-75",
-      "context": "Title"
-    },
-    {
-      "token": "font-size-100",
-      "context": "Title"
-    },
-    {
-      "token": "font-size-200",
-      "context": "Title"
-    },
-    {
-      "token": "font-size-300",
-      "context": "Title"
-    },
-    {
-      "token": "line-height-100",
-      "context": "Title"
-    },
-    {
-      "token": "cjk-line-height-100",
-      "context": "Title"
-    },
-    {
-      "token": "body-sans-serif-font-family",
-      "context": "Body"
-    },
-    {
-      "token": "body-sans-serif-font-weight",
-      "context": "Body"
-    },
-    {
-      "token": "body-serif-font-style",
-      "context": "Body"
-    },
+    { "token": "border-width-400", "context": "Border" },
+    { "token": "title-color", "context": "Value" },
+    { "token": "body-color", "context": "Value" },
+    { "token": "neutral-content-color-default", "context": "Value" },
+    { "token": "disabled-content-color", "context": "Disabled" },
+    { "token": "title-sans-serif-font-family", "context": "Title" },
+    { "token": "title-sans-serif-font-weight", "context": "Title" },
+    { "token": "title-serif-font-style", "context": "Title" },
+    { "token": "font-size-50", "context": "Title" },
+    { "token": "font-size-75", "context": "Title" },
+    { "token": "font-size-100", "context": "Title" },
+    { "token": "font-size-200", "context": "Title" },
+    { "token": "font-size-300", "context": "Title" },
+    { "token": "line-height-100", "context": "Title" },
+    { "token": "cjk-line-height-100", "context": "Title" },
+    { "token": "body-sans-serif-font-family", "context": "Body" },
+    { "token": "body-sans-serif-font-weight", "context": "Body" },
+    { "token": "body-serif-font-style", "context": "Body" },
     {
       "token": "collection-card-minimum-height-extra-small",
       "context": "Height (minimum), default variant"
@@ -396,14 +287,8 @@
       "token": "collection-card-hero-minimum-height-extra-large",
       "context": "Height (minimum), hero image variant"
     },
-    {
-      "token": "spacing-100",
-      "context": "Spacing (header to footer)"
-    },
-    {
-      "token": "card-header-to-footer",
-      "context": "Spacing (text to visual)"
-    },
+    { "token": "spacing-100", "context": "Spacing (header to footer)" },
+    { "token": "card-header-to-footer", "context": "Spacing (text to visual)" },
     {
       "token": "card-edge-to-content-compact-extra-medium",
       "context": "Spacing (top/side/bottom edge to content, medium)"
@@ -460,30 +345,12 @@
       "token": "card-description-to-footer",
       "context": "Spacing (description to footer)"
     },
-    {
-      "token": "thumbnail-size-100",
-      "context": "Components"
-    },
-    {
-      "token": "thumbnail-size-300",
-      "context": "Components"
-    },
-    {
-      "token": "thumbnail-size-500",
-      "context": "Components"
-    },
-    {
-      "token": "thumbnail-size-700",
-      "context": "Components"
-    },
-    {
-      "token": "thumbnail-size-900",
-      "context": "Components"
-    },
-    {
-      "token": "thumbnail-size-1000",
-      "context": "Components"
-    },
+    { "token": "thumbnail-size-100", "context": "Components" },
+    { "token": "thumbnail-size-300", "context": "Components" },
+    { "token": "thumbnail-size-500", "context": "Components" },
+    { "token": "thumbnail-size-700", "context": "Components" },
+    { "token": "thumbnail-size-900", "context": "Components" },
+    { "token": "thumbnail-size-1000", "context": "Components" },
     {
       "token": "card-horizontal-edge-to-content-compact",
       "context": "Spacing (top/side/bottom edge to content)"
@@ -526,16 +393,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" }
     ]
   }
 }