From 99554f9064299ac656f6c4e9171c5c928ff43de2 Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Tue, 13 Feb 2024 14:38:03 -0500
Subject: [PATCH 1/9] feat(downstate): docs + implementation for example
 components

---
 .storybook/foundations/down-state.mdx       | 24 +++++++++++++++++++++
 .storybook/main.js                          |  1 +
 .storybook/preview.js                       |  2 +-
 components/button/index.css                 |  5 +++++
 components/button/stories/button.stories.js | 13 +++++++++--
 components/checkbox/index.css               |  7 +++++-
 6 files changed, 48 insertions(+), 4 deletions(-)
 create mode 100644 .storybook/foundations/down-state.mdx

diff --git a/.storybook/foundations/down-state.mdx b/.storybook/foundations/down-state.mdx
new file mode 100644
index 0000000000..ca6ba8b3c2
--- /dev/null
+++ b/.storybook/foundations/down-state.mdx
@@ -0,0 +1,24 @@
+import { Meta, Story } from '@storybook/blocks';
+import * as ButtonStories from '../../components/button/stories/button.stories.js';
+import * as CheckboxStories from '../../components/checkbox/stories/checkbox.stories.js';
+
+<Meta title="Foundations/Down state" />
+
+<h1>Down state</h1>
+
+Down state is a Spectrum 2 (S2) feature that creates the illusion of components being pressed-in when active. This functionality is already included in S2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element:
+
+  - If the interactable element has a width of 24px or less, we use the minimum perspective token:
+    ```
+    transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+    ```
+  - If the interactable element has a width that is greater than 24px, we use the max formula:
+    ```
+    transform:
+      perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)))
+      translateZ(var(--spectrum-component-size-difference-down));
+    ```
+    - Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.
+
+<Story of={CheckboxStories.Default} />
+<Story of={ButtonStories.DownStateDocs} />
diff --git a/.storybook/main.js b/.storybook/main.js
index 48f390a027..1f4bea7e20 100644
--- a/.storybook/main.js
+++ b/.storybook/main.js
@@ -11,6 +11,7 @@ module.exports = {
 	stories: [
 		"../components/*/stories/*.stories.js",
 		"./guides/*.mdx",
+		"./foundations/*.mdx",
 		"./deprecated/*/*.stories.js",
 	],
 	rootDir: "../",
diff --git a/.storybook/preview.js b/.storybook/preview.js
index bfa19b5420..ad4f5fc741 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -205,7 +205,7 @@ export const parameters = {
 	options: {
 		storySort: {
 			method: "alphabetical",
-			order: ['Guides', ['Contributing', '*', 'Adobe Code of Conduct', 'Changelog'], 'Components', '*'],
+			order: ['Guides', ['Contributing', '*', 'Adobe Code of Conduct', 'Changelog'], 'Foundations', 'Components', '*'],
 			includeNames: true,
 		},
 	},
diff --git a/components/button/index.css b/components/button/index.css
index 8ca9498d74..b9b70e5b18 100644
--- a/components/button/index.css
+++ b/components/button/index.css
@@ -147,6 +147,11 @@ governing permissions and limitations under the License.
     box-shadow: none;
   }
 
+  &:active {
+    /* stylelint-disable-next-line spectrum-tools/no-unknown-custom-properties */
+    transform: perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down))) translateZ(var(--spectrum-component-size-difference-down));
+  }
+
   .spectrum-Icon {
     /* Any block-size difference between the intended workflow icon size and actual icon used.
        Helps support any existing use of smaller UI icons instead of intended Workflow icons. */
diff --git a/components/button/stories/button.stories.js b/components/button/stories/button.stories.js
index a5d5dcd4c4..f0c1921173 100644
--- a/components/button/stories/button.stories.js
+++ b/components/button/stories/button.stories.js
@@ -100,7 +100,7 @@ export default {
 		    name: "Layout",
 		    description: "How the buttons align in the preview (Storybook only).",
 		    type: { name: "string" },
-			table: { 
+			table: {
 			    type: { summary: "string" },
 			    category: "Advanced"
 			},
@@ -349,4 +349,13 @@ Wrapping.args = {
 	showIconOnlyButton: false,
 	variant: "accent",
 	label: "An example of text overflow behavior within the button component. When the button text is too long for the horizontal space available, it wraps to form another line.",
-};
\ No newline at end of file
+};
+
+export const DownStateDocs = CustomButton.bind({});
+DownStateDocs.args = {
+	variant: "accent",
+	customStyles: {
+		"--spectrum-downstate-width": "72px",
+		"--spectrum-downstate-height": "32px"
+	}
+}
diff --git a/components/checkbox/index.css b/components/checkbox/index.css
index 31f68c6380..0d588dd50a 100644
--- a/components/checkbox/index.css
+++ b/components/checkbox/index.css
@@ -137,6 +137,10 @@ governing permissions and limitations under the License.
   }
 
   &:active {
+    .spectrum-Checkbox-box {
+      transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+    }
+
     .spectrum-Checkbox-box::before {
       border-color: var(--highcontrast-checkbox-highlight-color-down, var(--mod-checkbox-control-color-down, var(--spectrum-checkbox-control-color-down)));
     }
@@ -372,6 +376,7 @@ governing permissions and limitations under the License.
     }
   }
 }
+
 /* stylelint-enable max-nesting-depth */
 
 .spectrum-Checkbox-label {
@@ -571,7 +576,7 @@ governing permissions and limitations under the License.
       outline-style: auto;
       outline-offset: var(--highcontrast-checkbox-focus-indicator-gap, var(--mod-checkbox-focus-indicator-gap, var(--spectrum-checkbox-focus-indicator-gap)));
       /* stylelint-disable-next-line declaration-block-no-redundant-longhand-properties */
-      outline-width: var(--mod-focus-indicator-thickness, var(--spectrum-focus-indicator-thickness)); 
+      outline-width: var(--mod-focus-indicator-thickness, var(--spectrum-focus-indicator-thickness));
 
       &::after {
         box-shadow:

From 7c7a321c3c993462d1c13977ece831af3a1fbaee Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Tue, 12 Mar 2024 17:49:43 -0400
Subject: [PATCH 2/9] docs: update mdx

---
 .storybook/foundations/down-state.mdx | 39 ++++++++++++++++++---------
 1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/.storybook/foundations/down-state.mdx b/.storybook/foundations/down-state.mdx
index ca6ba8b3c2..9dd390fb84 100644
--- a/.storybook/foundations/down-state.mdx
+++ b/.storybook/foundations/down-state.mdx
@@ -6,19 +6,32 @@ import * as CheckboxStories from '../../components/checkbox/stories/checkbox.sto
 
 <h1>Down state</h1>
 
-Down state is a Spectrum 2 (S2) feature that creates the illusion of components being pressed-in when active. This functionality is already included in S2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element:
-
-  - If the interactable element has a width of 24px or less, we use the minimum perspective token:
-    ```
-    transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
-    ```
-  - If the interactable element has a width that is greater than 24px, we use the max formula:
-    ```
-    transform:
-      perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)))
-      translateZ(var(--spectrum-component-size-difference-down));
-    ```
-    - Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.
+Down state is a Spectrum 2 feature that creates the illusion of components being pressed-in when active. This functionality is already included in Spectrum 2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element, as shown in the examples below.
+
+Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.
+
+<h2>Examples</h2>
+
+<h3>Minimum perspective</h3>
+The checkbox component is an example of an element that has a width of 24px or less.
 
 <Story of={CheckboxStories.Default} />
+
+In this case, we use the minimum perspective token:
+```
+transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+```
+
+<h3>Calculated perspective</h3>
+The button component is an example of an element that usually has a width greater than 24px.
+
 <Story of={ButtonStories.DownStateDocs} />
+
+In this case, we use a max formula to calculate the perspective based on component width and height (this helps us account for components that may be very wide):
+```
+transform:
+  perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)))
+  translateZ(var(--spectrum-component-size-difference-down));
+```
+
+*Note that this case requires the consumer to define an implementation to dynamically set the values of the `--spectrum-downstate-width` and `--spectrum-downstate-height` tokens based on the component's width and height.*

From aa9ecc0a3c445ee7f4a47c93b421e8273bbe9ad7 Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Wed, 13 Mar 2024 11:38:34 -0400
Subject: [PATCH 3/9] docs: reorg, stories live within foundations

---
 .../down-state/button-down-state.stories.js   | 32 +++++++++++++++++++
 .../down-state/checkbox-down-state.stories.js | 27 ++++++++++++++++
 .../{ => down-state}/down-state.mdx           |  8 ++---
 .storybook/main.js                            |  3 +-
 .storybook/manager.js                         |  7 +++-
 5 files changed, 71 insertions(+), 6 deletions(-)
 create mode 100644 .storybook/foundations/down-state/button-down-state.stories.js
 create mode 100644 .storybook/foundations/down-state/checkbox-down-state.stories.js
 rename .storybook/foundations/{ => down-state}/down-state.mdx (87%)

diff --git a/.storybook/foundations/down-state/button-down-state.stories.js b/.storybook/foundations/down-state/button-down-state.stories.js
new file mode 100644
index 0000000000..e938e302aa
--- /dev/null
+++ b/.storybook/foundations/down-state/button-down-state.stories.js
@@ -0,0 +1,32 @@
+import { Template } from "../../../components/button/stories/template";
+
+export default {
+	title: "Foundations/Down state",
+	description:
+		"Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.",
+	component: "Button",
+	args: {
+		rootClass: "spectrum-Button",
+	},
+	parameters: {
+		actions: {
+			handles: ['click .spectrum-Button'],
+		},
+		status: {
+			type: process.env.MIGRATED_PACKAGES.includes("button")
+				? "migrated"
+				: undefined,
+		},
+	},
+	tags: ['foundation'],
+};
+
+export const ButtonDownState = Template.bind({});
+ButtonDownState.args = {
+	label: "Edit",
+	variant: "accent",
+	customStyles: {
+		"--spectrum-downstate-width": "72px",
+		"--spectrum-downstate-height": "32px"
+	}
+};
diff --git a/.storybook/foundations/down-state/checkbox-down-state.stories.js b/.storybook/foundations/down-state/checkbox-down-state.stories.js
new file mode 100644
index 0000000000..889c4fe4ce
--- /dev/null
+++ b/.storybook/foundations/down-state/checkbox-down-state.stories.js
@@ -0,0 +1,27 @@
+import { Template } from "../../../components/checkbox/stories/template";
+
+export default {
+	title: "Foundations/Down state",
+	description:
+		"Checkboxes allow users to select multiple items from a list of individual items, or mark one individual item as selected.",
+	component: "Checkbox",
+	args: {
+		rootClass: "spectrum-Checkbox",
+	},
+	parameters: {
+		actions: {
+			handles: ['click input[type="checkbox"]'],
+		},
+		status: {
+			type: process.env.MIGRATED_PACKAGES.includes("checkbox")
+				? "migrated"
+				: undefined,
+		},
+	},
+	tags: ['foundation'],
+};
+
+export const CheckboxDownState = Template.bind({});
+CheckboxDownState.args = {
+	label: "Checkbox",
+};
diff --git a/.storybook/foundations/down-state.mdx b/.storybook/foundations/down-state/down-state.mdx
similarity index 87%
rename from .storybook/foundations/down-state.mdx
rename to .storybook/foundations/down-state/down-state.mdx
index 9dd390fb84..129ee68f4c 100644
--- a/.storybook/foundations/down-state.mdx
+++ b/.storybook/foundations/down-state/down-state.mdx
@@ -1,6 +1,6 @@
 import { Meta, Story } from '@storybook/blocks';
-import * as ButtonStories from '../../components/button/stories/button.stories.js';
-import * as CheckboxStories from '../../components/checkbox/stories/checkbox.stories.js';
+import * as Checkbox from './checkbox-down-state.stories.js';
+import * as Button from './button-down-state.stories.js';
 
 <Meta title="Foundations/Down state" />
 
@@ -15,7 +15,7 @@ Note that in this case, users are required to develop an implementation to deter
 <h3>Minimum perspective</h3>
 The checkbox component is an example of an element that has a width of 24px or less.
 
-<Story of={CheckboxStories.Default} />
+<Story of={Checkbox.CheckboxDownState} />
 
 In this case, we use the minimum perspective token:
 ```
@@ -25,7 +25,7 @@ transform: perspective(var(--spectrum-component-size-minimum-perspective-down))
 <h3>Calculated perspective</h3>
 The button component is an example of an element that usually has a width greater than 24px.
 
-<Story of={ButtonStories.DownStateDocs} />
+<Story of={Button.ButtonDownState} />
 
 In this case, we use a max formula to calculate the perspective based on component width and height (this helps us account for components that may be very wide):
 ```
diff --git a/.storybook/main.js b/.storybook/main.js
index 1f4bea7e20..966a6005fa 100644
--- a/.storybook/main.js
+++ b/.storybook/main.js
@@ -11,7 +11,8 @@ module.exports = {
 	stories: [
 		"../components/*/stories/*.stories.js",
 		"./guides/*.mdx",
-		"./foundations/*.mdx",
+		"./foundations/*/*.mdx",
+		"./foundations/*/*.stories.js",
 		"./deprecated/*/*.stories.js",
 	],
 	rootDir: "../",
diff --git a/.storybook/manager.js b/.storybook/manager.js
index 654fba3bd9..1618a74f84 100644
--- a/.storybook/manager.js
+++ b/.storybook/manager.js
@@ -7,8 +7,8 @@ import logo from "./assets/logo.svg";
 import pkg from "./package.json";
 
 // Load global styles
-import "@spectrum-css/vars/css/globals/index.css";
 import "@spectrum-css/vars/css/components/index.css";
+import "@spectrum-css/vars/css/globals/index.css";
 
 import "@spectrum-css/vars/css/scales/spectrum-medium.css";
 import "@spectrum-css/vars/css/themes/spectrum-light.css";
@@ -53,5 +53,10 @@ addons.setConfig({
 	}),
 	sidebar: {
 		showRoots: false,
+		filters: {
+			patterns: (item) => {
+				return !item.tags.includes('foundation');
+			}
+		}
 	},
 });

From 30eebf348feceb4666f3a1f2cb5b953c9e41da3c Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Wed, 13 Mar 2024 13:51:06 -0400
Subject: [PATCH 4/9] docs: decorator for down state dimension tokens

---
 .storybook/decorators/index.js                |  1 +
 .../withDownStateDimensionCapture.js          | 19 +++++++++++++++++++
 components/button/stories/button.stories.js   | 11 ++---------
 3 files changed, 22 insertions(+), 9 deletions(-)
 create mode 100644 .storybook/decorators/withDownStateDimensionCapture.js

diff --git a/.storybook/decorators/index.js b/.storybook/decorators/index.js
index 91f45ced79..ba1900993c 100644
--- a/.storybook/decorators/index.js
+++ b/.storybook/decorators/index.js
@@ -2,6 +2,7 @@ import { makeDecorator, useEffect } from "@storybook/preview-api";
 import { html } from "lit";
 
 export { withContextWrapper } from "./contextsWrapper.js";
+export { withDownStateDimensionCapture } from "./withDownStateDimensionCapture.js";
 export { withTestingPreviewWrapper } from "./withTestingPreviewWrapper.js";
 
 /**
diff --git a/.storybook/decorators/withDownStateDimensionCapture.js b/.storybook/decorators/withDownStateDimensionCapture.js
new file mode 100644
index 0000000000..616852d34c
--- /dev/null
+++ b/.storybook/decorators/withDownStateDimensionCapture.js
@@ -0,0 +1,19 @@
+export const withDownStateDimensionCapture = (selector) => (Story, context) => {
+  const captureDownStateDimensions = () => {
+    const components = document.querySelectorAll(selector);
+    components.forEach((component) => {
+      const { width, height } = component.getBoundingClientRect();
+      component.style.setProperty('--spectrum-downstate-width', `${width}px`);
+      component.style.setProperty('--spectrum-downstate-height', `${height}px`);
+    });
+  };
+
+  document.addEventListener("DOMContentLoaded", () => {
+    // Wait to make sure the story is fully rendered (otherwise width/height can be wrong)
+    setTimeout(() => {
+        captureDownStateDimensions();
+    }, 100);
+  });
+
+  return Story(context);
+};
diff --git a/components/button/stories/button.stories.js b/components/button/stories/button.stories.js
index f0c1921173..4c6b990f9a 100644
--- a/components/button/stories/button.stories.js
+++ b/components/button/stories/button.stories.js
@@ -2,6 +2,7 @@ import { html } from "lit";
 import { ifDefined } from "lit/directives/if-defined.js";
 import { styleMap } from "lit/directives/style-map.js";
 import { when } from "lit/directives/when.js";
+import { withDownStateDimensionCapture } from "../../../.storybook/decorators";
 
 import { default as IconStories } from "@spectrum-css/icon/stories/icon.stories.js";
 import { Template as Typography } from "@spectrum-css/typography/stories/template.js";
@@ -12,6 +13,7 @@ export default {
 	description:
 		"Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.",
 	component: "Button",
+	decorators: [withDownStateDimensionCapture('.spectrum-Button:not(:disabled)')],
 	argTypes: {
 		size: {
 			name: "Size",
@@ -350,12 +352,3 @@ Wrapping.args = {
 	variant: "accent",
 	label: "An example of text overflow behavior within the button component. When the button text is too long for the horizontal space available, it wraps to form another line.",
 };
-
-export const DownStateDocs = CustomButton.bind({});
-DownStateDocs.args = {
-	variant: "accent",
-	customStyles: {
-		"--spectrum-downstate-width": "72px",
-		"--spectrum-downstate-height": "32px"
-	}
-}

From 993a550463bd2e5edac83d923e17df2821641579 Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Wed, 13 Mar 2024 14:23:26 -0400
Subject: [PATCH 5/9] docs: fix mdx hierarchy console error

---
 .storybook/foundations/down-state/down-state.mdx | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/.storybook/foundations/down-state/down-state.mdx b/.storybook/foundations/down-state/down-state.mdx
index 129ee68f4c..d7f419e9ab 100644
--- a/.storybook/foundations/down-state/down-state.mdx
+++ b/.storybook/foundations/down-state/down-state.mdx
@@ -8,30 +8,32 @@ import * as Button from './button-down-state.stories.js';
 
 Down state is a Spectrum 2 feature that creates the illusion of components being pressed-in when active. This functionality is already included in Spectrum 2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element, as shown in the examples below.
 
-Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.
-
 <h2>Examples</h2>
 
 <h3>Minimum perspective</h3>
-The checkbox component is an example of an element that has a width of 24px or less.
+
+The checkbox component is an example of an element that has a width of 24px or less by default.
 
 <Story of={Checkbox.CheckboxDownState} />
 
 In this case, we use the minimum perspective token:
+
 ```
 transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
 ```
 
 <h3>Calculated perspective</h3>
-The button component is an example of an element that usually has a width greater than 24px.
+
+The button component is an example of an element that usually has a width greater than 24px by default.
 
 <Story of={Button.ButtonDownState} />
 
 In this case, we use a max formula to calculate the perspective based on component width and height (this helps us account for components that may be very wide):
+
 ```
 transform:
   perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)))
   translateZ(var(--spectrum-component-size-difference-down));
 ```
 
-*Note that this case requires the consumer to define an implementation to dynamically set the values of the `--spectrum-downstate-width` and `--spectrum-downstate-height` tokens based on the component's width and height.*
+*Note that in this case, users are required to develop an implementation to determine the width and height of the component. Assign these values to the `--spectrum-downstate-width` and `--spectrum-downstate-height` custom properties in a `style` attribute on the HTML element to expose them for use in the CSS.*

From 9db3bf52b5c2b3164736b401c06be70fa1455c0d Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Wed, 13 Mar 2024 14:27:54 -0400
Subject: [PATCH 6/9] fix: small iconOnly button gets min perspective

---
 components/button/index.css | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/components/button/index.css b/components/button/index.css
index b9b70e5b18..cb59d7b40a 100644
--- a/components/button/index.css
+++ b/components/button/index.css
@@ -24,6 +24,9 @@ governing permissions and limitations under the License.
   --spectrum-button-focus-ring-thickness: var(--spectrum-focus-indicator-thickness);
   --spectrum-button-focus-indicator-color: var(--spectrum-focus-indicator-color);
   --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-50);
+
+  /* stylelint-disable-next-line spectrum-tools/no-unknown-custom-properties */
+  --spectrum-downstate-perspective: max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down));
 }
 
 .spectrum-Button--sizeS {
@@ -42,6 +45,10 @@ governing permissions and limitations under the License.
   --spectrum-button-bottom-to-text: var(--spectrum-button-bottom-to-text-small);
   --spectrum-button-top-to-icon: var(--spectrum-component-top-to-workflow-icon-75);
   --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-75);
+
+  &.spectrum-Button--iconOnly {
+    --spectrum-downstate-perspective: var(--spectrum-component-size-minimum-perspective-down);
+  }
 }
 
 .spectrum-Button--sizeM {
@@ -148,21 +155,20 @@ governing permissions and limitations under the License.
   }
 
   &:active {
-    /* stylelint-disable-next-line spectrum-tools/no-unknown-custom-properties */
-    transform: perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down))) translateZ(var(--spectrum-component-size-difference-down));
+    transform: perspective(var(--spectrum-downstate-perspective)) translateZ(var(--spectrum-component-size-difference-down));
   }
 
   .spectrum-Icon {
     /* Any block-size difference between the intended workflow icon size and actual icon used.
        Helps support any existing use of smaller UI icons instead of intended Workflow icons. */
     --_icon-size-difference: max(0px,
-      var(--spectrum-button-intended-icon-size) - 
+      var(--spectrum-button-intended-icon-size) -
       var(--spectrum-icon-block-size, var(--spectrum-button-intended-icon-size))
     );
 
     margin-block-start: var(--mod-button-icon-margin-block-start,
       max(0px,
-        var(--mod-button-top-to-icon, var(--spectrum-button-top-to-icon)) - 
+        var(--mod-button-top-to-icon, var(--spectrum-button-top-to-icon)) -
         var(--mod-button-border-width, var(--spectrum-button-border-width)) +
         (var(--_icon-size-difference, 0px) / 2)
       )

From 54d5c7e0640b7e879c32f72b0299ef3d6d328465 Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Fri, 15 Mar 2024 14:19:40 -0400
Subject: [PATCH 7/9] docs: use markdown, update language

---
 .../foundations/down-state/down-state.mdx     | 21 ++++++++++++-------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/.storybook/foundations/down-state/down-state.mdx b/.storybook/foundations/down-state/down-state.mdx
index d7f419e9ab..f07e65d2f8 100644
--- a/.storybook/foundations/down-state/down-state.mdx
+++ b/.storybook/foundations/down-state/down-state.mdx
@@ -4,27 +4,29 @@ import * as Button from './button-down-state.stories.js';
 
 <Meta title="Foundations/Down state" />
 
-<h1>Down state</h1>
+# Down state
 
 Down state is a Spectrum 2 feature that creates the illusion of components being pressed-in when active. This functionality is already included in Spectrum 2 components that require down state in this project. It is implemented with a CSS transform. The implementation depends on the size of the interactable element, as shown in the examples below.
 
-<h2>Examples</h2>
+## Examples
 
-<h3>Minimum perspective</h3>
+### Minimum perspective
 
-The checkbox component is an example of an element that has a width of 24px or less by default.
+For elements that have a width of 24px or less, the minimum perspective token is used to apply the down state. One example of a component that uses this token is the checkbox:
 
 <Story of={Checkbox.CheckboxDownState} />
 
 In this case, we use the minimum perspective token:
 
 ```
-transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+transform:
+  perspective(var(--spectrum-component-size-minimum-perspective-down))
+  translateZ(var(--spectrum-component-size-difference-down));
 ```
 
-<h3>Calculated perspective</h3>
+### Calculated perspective
 
-The button component is an example of an element that usually has a width greater than 24px by default.
+For elements that have a width of greater than 24px, we need to use the component's width and height to apply the down state. One example of a component that uses this logic is the button:
 
 <Story of={Button.ButtonDownState} />
 
@@ -32,7 +34,10 @@ In this case, we use a max formula to calculate the perspective based on compone
 
 ```
 transform:
-  perspective(max(var(--spectrum-downstate-height), var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)))
+  perspective(max(
+    var(--spectrum-downstate-height),
+    var(--spectrum-downstate-width) * var(--spectrum-component-size-width-ratio-down)
+  ))
   translateZ(var(--spectrum-component-size-difference-down));
 ```
 

From 68c3002b9a6ee92e252a0b485302a0fc114c0e39 Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Fri, 15 Mar 2024 14:25:36 -0400
Subject: [PATCH 8/9] fix: disabled, readonly checkbox doesnt have down state

---
 components/checkbox/index.css | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/components/checkbox/index.css b/components/checkbox/index.css
index 0d588dd50a..a61fd135bc 100644
--- a/components/checkbox/index.css
+++ b/components/checkbox/index.css
@@ -137,10 +137,6 @@ governing permissions and limitations under the License.
   }
 
   &:active {
-    .spectrum-Checkbox-box {
-      transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
-    }
-
     .spectrum-Checkbox-box::before {
       border-color: var(--highcontrast-checkbox-highlight-color-down, var(--mod-checkbox-control-color-down, var(--spectrum-checkbox-control-color-down)));
     }
@@ -154,6 +150,12 @@ governing permissions and limitations under the License.
     }
   }
 
+  &:not(.is-readOnly):active {
+    .spectrum-Checkbox-input:not(:disabled) + .spectrum-Checkbox-box {
+      transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
+    }
+  }
+
   /* Selected Invalid */
   &.is-invalid {
     .spectrum-Checkbox-input:checked + .spectrum-Checkbox-box,

From a4490cb197a1c29a8638e04fb5b100d8d156f95f Mon Sep 17 00:00:00 2001
From: Melissa Thompson <mthompson@heysparkbox.com>
Date: Tue, 19 Mar 2024 09:56:11 -0400
Subject: [PATCH 9/9] chore(button,checkbox): update package versions

---
 components/button/package.json   | 2 +-
 components/checkbox/package.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/button/package.json b/components/button/package.json
index cd71429f97..b94d454358 100644
--- a/components/button/package.json
+++ b/components/button/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-css/button",
-  "version": "12.0.3-next.0",
+  "version": "14.0.0-next.2",
   "description": "The Spectrum CSS button component",
   "license": "Apache-2.0",
   "author": "Adobe",
diff --git a/components/checkbox/package.json b/components/checkbox/package.json
index 8a9eae6eea..350b9220ca 100644
--- a/components/checkbox/package.json
+++ b/components/checkbox/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-css/checkbox",
-  "version": "8.1.6-next.0",
+  "version": "14.0.0-next.2",
   "description": "The Spectrum CSS checkbox component",
   "license": "Apache-2.0",
   "author": "Adobe",