@adobe/spectrum-design-data 0.4.0 → 0.7.0

package/components/color-area.json

@@ -9,130 +9,104 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/color-area/"
   },
-  "options": {
-    "background": {
-      "type": "string",
-      "description": "This will vary depending on implementation."
-    },
-    "x-value": {
-      "type": "number",
-      "description": "Number (from x-minValue to x-maxValue)"
-    },
-    "x-minValue": {
-      "type": "number",
-      "default": 0
-    },
-    "x-maxValue": {
-      "type": "number",
-      "default": 100
-    },
-    "y-value": {
-      "type": "number",
-      "description": "Number (from y-minValue to y-maxValue)"
-    },
-    "y-minValue": {
-      "type": "number",
-      "default": 0
-    },
-    "y-maxValue": {
-      "type": "number",
-      "default": 100
-    },
-    "step": {
-      "type": "number",
-      "default": 1
-    },
-    "width": {
-      "type": "number",
-      "default": 192,
-      "description": "units: px"
-    },
-    "height": {
-      "type": "number",
-      "default": 192,
-      "description": "units: px"
-    },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "states": [
+  "documentBlocks": [
     {
-      "name": "hover",
-      "trigger": "interaction"
+      "type": "purpose",
+      "content": "A color area allows users to visually select two properties of a color simultaneously. It's commonly used together with a color slider or color wheel."
     },
     {
-      "name": "down",
-      "trigger": "interaction"
+      "type": "guideline",
+      "content": "A color area enables visual selection of two color properties at once. It's often paired with a color slider or color wheel."
     },
     {
-      "name": "keyboard-focus",
-      "trigger": "interaction"
-    }
-  ],
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
+      "type": "guideline",
+      "content": "A color area in a disabled state shows that an input exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that the area may become available later."
+    },
     {
-      "token": "color-area-width",
-      "context": "Size"
+      "type": "guideline",
+      "content": "A color area’s height and width can be customized appropriately for its context."
     },
     {
-      "token": "color-area-minimum-width",
-      "context": "Size"
+      "type": "guideline",
+      "content": "The step refers to the increment by which these values increase or decrease. A step value of 1 (default) allows a user to only select whole numbers within the min and max range."
     },
     {
-      "token": "color-area-height",
-      "context": "Size"
+      "type": "guideline",
+      "content": "The x and y values are the numbers selected within the color area’s horizontal and vertical axes, respectively."
     },
     {
-      "token": "color-area-minimum-height",
-      "context": "Size"
+      "type": "guideline",
+      "content": "The x/y min and max values also can be customized appropriately for what the color area is being used for. By default, the min value starts at 0 and max value is set to 100."
     },
     {
-      "token": "color-area-border-width",
-      "context": "Color area border"
+      "type": "guideline",
+      "content": "A color area can be navigated using a keyboard. The keyboard focus state enlarges the handle to become twice as large."
     },
     {
-      "token": "color-area-border-rounding",
-      "context": "Color area border"
+      "type": "guideline",
+      "content": "The color area’s handle can slide all the way over the edge of the area. It always displays the selected color inside the handle and never gets cut off by the border or any container."
     },
     {
-      "token": "color-area-border-color",
-      "context": "Color area border"
+      "type": "guideline",
+      "content": "Minimum sizing ensures that the component remains clear, usable, and visually consistent, even in flexible or responsive layouts."
     },
     {
-      "token": "color-area-border-opacity",
-      "context": "Color area border"
+      "type": "guideline",
+      "content": "When using color areas, it’s important to clearly display the color selection in real time. This can be in a color swatch, directly on the canvas, or both."
     },
     {
-      "token": "disabled-background-color",
-      "context": "Disabled"
+      "type": "guideline",
+      "content": "The color loupe component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type."
     }
   ],
+  "options": {
+    "background": {
+      "type": "string",
+      "description": "This will vary depending on implementation."
+    },
+    "x-value": {
+      "type": "number",
+      "description": "Number (from x-minValue to x-maxValue)"
+    },
+    "x-minValue": { "type": "number", "default": 0 },
+    "x-maxValue": { "type": "number", "default": 100 },
+    "y-value": {
+      "type": "number",
+      "description": "Number (from y-minValue to y-maxValue)"
+    },
+    "y-minValue": { "type": "number", "default": 0 },
+    "y-maxValue": { "type": "number", "default": 100 },
+    "step": { "type": "number", "default": 1 },
+    "width": { "type": "number", "default": 192, "description": "units: px" },
+    "height": { "type": "number", "default": 192, "description": "units: px" },
+    "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": "color-area-width", "context": "Size" },
+    { "token": "color-area-minimum-width", "context": "Size" },
+    { "token": "color-area-height", "context": "Size" },
+    { "token": "color-area-minimum-height", "context": "Size" },
+    { "token": "color-area-border-width", "context": "Color area border" },
+    { "token": "color-area-border-rounding", "context": "Color area border" },
+    { "token": "color-area-border-color", "context": "Color area border" },
+    { "token": "color-area-border-opacity", "context": "Color area border" },
+    { "token": "disabled-background-color", "context": "Disabled" }
+  ],
   "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/color-handle.json

@@ -9,103 +9,63 @@
     "category": "inputs",
     "documentationUrl": "https://spectrum.adobe.com/page/color-handle/"
   },
+  "documentBlocks": [
+    {
+      "type": "purpose",
+      "content": "Color handles select or adjust a color value along a track or wheel. The outer border is not included in the handle's size."
+    },
+    {
+      "type": "guideline",
+      "content": "Handle behavior.\n\nIn the color area and color slider, the handle can slide all the way to the edge of the component. It always displays the selected color inside the handle and never gets cut off by the border or any container."
+    },
+    {
+      "type": "guideline",
+      "content": "Transparent colors.\n\nWhen using transparent colors, the handle displays an opacity checkerboard background to clearly show the level of transparency."
+    },
+    {
+      "type": "guideline",
+      "content": "Keyboard focus.\n\nThe keyboard focus state enlarges the handle to become twice as large."
+    }
+  ],
   "options": {
     "channel": {
       "type": "string",
       "default": "hue",
       "description": "Which channel of the color this handle controls. Use 'alpha' for opacity.",
       "values": [
-        {
-          "value": "hue"
-        },
-        {
-          "value": "saturation"
-        },
-        {
-          "value": "lightness"
-        },
-        {
-          "value": "red"
-        },
-        {
-          "value": "green"
-        },
-        {
-          "value": "blue"
-        },
-        {
-          "value": "alpha"
-        }
+        { "value": "hue" },
+        { "value": "saturation" },
+        { "value": "lightness" },
+        { "value": "red" },
+        { "value": "green" },
+        { "value": "blue" },
+        { "value": "alpha" }
       ]
     },
-    "isDisabled": {
-      "type": "boolean",
-      "default": false
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
+    "isDisabled": { "type": "boolean", "default": false }
   },
+  "lifecycle": { "introduced": "1.0.0-draft" },
   "tokenBindings": [
-    {
-      "token": "color-handle-size",
-      "context": "Size (keyboard focus)"
-    },
+    { "token": "color-handle-size", "context": "Size (keyboard focus)" },
     {
       "token": "color-handle-size-key-focus",
       "context": "Size (keyboard focus)"
     },
-    {
-      "token": "color-handle-border-width",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-inner-border-width",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-outer-border-width",
-      "context": "Border"
-    },
-    {
-      "token": "white",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-inner-border-color",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-inner-border-opacity",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-outer-border-color",
-      "context": "Border"
-    },
-    {
-      "token": "color-handle-outer-border-opacity",
-      "context": "Border"
-    },
-    {
-      "token": "disabled-content-color",
-      "context": "Border (disabled)"
-    },
-    {
-      "token": "disabled-background-color",
-      "context": "Border (disabled)"
-    }
+    { "token": "color-handle-border-width", "context": "Border" },
+    { "token": "color-handle-inner-border-width", "context": "Border" },
+    { "token": "color-handle-outer-border-width", "context": "Border" },
+    { "token": "white", "context": "Border" },
+    { "token": "color-handle-inner-border-color", "context": "Border" },
+    { "token": "color-handle-inner-border-opacity", "context": "Border" },
+    { "token": "color-handle-outer-border-color", "context": "Border" },
+    { "token": "color-handle-outer-border-opacity", "context": "Border" },
+    { "token": "disabled-content-color", "context": "Border (disabled)" },
+    { "token": "disabled-background-color", "context": "Border (disabled)" }
   ],
   "accessibility": {
     "intents": ["choose"],
     "focusable": true,
     "keyboardIntents": ["increment", "decrement"],
-    "wcag": [
-      {
-        "criterion": "2.1.1",
-        "level": "A",
-        "title": "Keyboard"
-      }
-    ]
+    "wcag": [{ "criterion": "2.1.1", "level": "A", "title": "Keyboard" }]
   }
 }

package/components/color-loupe.json

@@ -9,69 +9,52 @@
     "category": "feedback",
     "documentationUrl": "https://spectrum.adobe.com/page/color-loupe/"
   },
-  "options": {
-    "value": {
-      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/hex-color.json"
-    }
-  },
-  "lifecycle": {
-    "introduced": "1.0.0-draft"
-  },
-  "tokenBindings": [
-    {
-      "token": "color-loupe-height",
-      "context": "Size"
-    },
-    {
-      "token": "color-loupe-width",
-      "context": "Size"
-    },
-    {
-      "token": "color-loupe-outer-border-width",
-      "context": "Border"
-    },
-    {
-      "token": "color-loupe-inner-border-width",
-      "context": "Border"
-    },
-    {
-      "token": "color-loupe-bottom-to-color-handle",
-      "context": "Spacing"
-    },
-    {
-      "token": "drop-shadow-elevated-x",
-      "context": "Shadows"
-    },
-    {
-      "token": "drop-shadow-elevated-y",
-      "context": "Shadows"
-    },
+  "documentBlocks": [
     {
-      "token": "drop-shadow-elevated-blur",
-      "context": "Shadows"
+      "type": "purpose",
+      "content": "A color loupe shows the output color that would otherwise be covered by a cursor, stylus, or finger during color selection."
     },
     {
-      "token": "color-loupe-outer-border",
-      "context": "Border"
+      "type": "guideline",
+      "content": "Color loupe.\n\nThe loupe is a floating element positioned above the handle. It provides a preview that reflects the color currently sampled by its parent color component and disappears when the interaction ends."
     },
     {
-      "token": "drop-shadow-x",
-      "context": "S1 Shadows"
+      "type": "guideline",
+      "content": "Transparent colors.\n\nWhen using transparent colors, the loupe displays an opacity checkerboard background to clearly show the level of transparency."
     },
     {
-      "token": "color-loupe-drop-shadow-y",
-      "context": "S1 Shadows"
+      "type": "guideline",
+      "content": "Keyboard focus.\n\nThe loupe is a visual-only element and should not receive focus since it does not provide interactive functionality."
     },
     {
-      "token": "color-loupe-drop-shadow-blur",
-      "context": "S1 Shadows"
+      "type": "guideline",
+      "content": "Display combined values.\n\nColor selection usually happens using a variety of input methods (color area, color slider, color wheel). The color loupe should display the final output color: the combined values from multiple color inputs.\n\nThe number of input methods is determined by the color space (or \"mode\"), for example:\n\n* 2 controls: HSL using color wheel (hue) and color area (saturation and lightness)\n* 3 controls: RGB using unique color sliders for Red, Green, and Blue\n* 4 controls: RGBa using unique color sliders for Red, Green, Blue, and Alpha"
     },
     {
-      "token": "color-loupe-drop-shadow-color",
-      "context": "S1 Shadows"
+      "type": "guideline",
+      "content": "Color loupe on down/touch state.\n\nThe color loupe component can be used above the handle to show the selected color that would otherwise be covered by a cursor, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type."
     }
   ],
-  "accessibility": {
-    "focusable": false
-  }
+  "options": {
+    "value": {
+      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/hex-color.json"
+    }
+  },
+  "lifecycle": { "introduced": "1.0.0-draft" },
+  "tokenBindings": [
+    { "token": "color-loupe-height", "context": "Size" },
+    { "token": "color-loupe-width", "context": "Size" },
+    { "token": "color-loupe-outer-border-width", "context": "Border" },
+    { "token": "color-loupe-inner-border-width", "context": "Border" },
+    { "token": "color-loupe-bottom-to-color-handle", "context": "Spacing" },
+    { "token": "drop-shadow-elevated-x", "context": "Shadows" },
+    { "token": "drop-shadow-elevated-y", "context": "Shadows" },
+    { "token": "drop-shadow-elevated-blur", "context": "Shadows" },
+    { "token": "color-loupe-outer-border", "context": "Border" },
+    { "token": "drop-shadow-x", "context": "S1 Shadows" },
+    { "token": "color-loupe-drop-shadow-y", "context": "S1 Shadows" },
+    { "token": "color-loupe-drop-shadow-blur", "context": "S1 Shadows" },
+    { "token": "color-loupe-drop-shadow-color", "context": "S1 Shadows" }
+  ],
+  "accessibility": { "focusable": false }
 }