docs(dropshadow): add stories and docs for dropshadow (#2674)

.storybook/foundations/drop-shadow/drop-shadow.mdx

@@ -0,0 +1,86 @@
+import { Meta, Title, Story, Description } from '@storybook/blocks';
+import * as DropShadowStories from './drop-shadow.stories.js';
+
+
+<Meta of={DropShadowStories} />
+
+<Title />
+<Description of={DropShadowStories} />
+
+Drop shadow tokens may be used for box shadows or drop shadows in CSS. Using `box-shadow` is often preferable to using `filter: drop-shadow()`, but in situations where the shadow must be applied to the alpha channel of the content rather than the border box, or if `box-shadow` is already being used for a different purpose, such as a focus outline, `filter: drop-shadow()` may be used. Note that in cases where `filter: drop-shadow()` is used, the shadow may be more blurred than the design spec due to a difference in how the blur parameter is calculated, and an adjustment by half may be needed.
+
+The opacity values in dark shadow colors are 3x the light values.
+
+These single-layer shadows are an interim solution for shadows until complex tokens (additional design data for the Spectrum Tokens system) are available to support multi-layer shadows.
+
+## Emphasized Default
+This shadow is used to provide emphasis to containers within a page.
+
+### `box-shadow`
+<Story of={DropShadowStories.BoxShadowEmphasizedDefault} />
+```
+box-shadow:
+  var(--spectrum-drop-shadow-emphasized-default-x)
+  var(--spectrum-drop-shadow-emphasized-default-y)
+  var(--spectrum-drop-shadow-emphasized-default-blur)
+  var(--spectrum-drop-shadow-emphasized-default-color);
+```
+
+### `filter: drop-shadow()`
+<Story of={DropShadowStories.DropShadowEmphasizedDefault} />
+```
+filter: drop-shadow(
+  var(--spectrum-drop-shadow-emphasized-default-x)
+  var(--spectrum-drop-shadow-emphasized-default-y)
+  calc(var(--spectrum-drop-shadow-emphasized-default-blur) / 2)
+  var(--spectrum-drop-shadow-emphasized-default-color)
+);
+```
+
+## Emphasized Hover
+If the whole container is interactive, such as in a select box, the shadow becomes elevated on hover.
+
+### `box-shadow`
+<Story of={DropShadowStories.BoxShadowEmphasizedHover} />
+```
+box-shadow:
+  var(--spectrum-drop-shadow-emphasized-hover-x)
+  var(--spectrum-drop-shadow-emphasized-hover-y)
+  var(--spectrum-drop-shadow-emphasized-hover-blur)
+  var(--spectrum-drop-shadow-emphasized-hover-color);
+```
+
+### `filter: drop-shadow()`
+<Story of={DropShadowStories.DropShadowEmphasizedHover} />
+```
+filter: drop-shadow(
+  var(--spectrum-drop-shadow-emphasized-hover-x)
+  var(--spectrum-drop-shadow-emphasized-hover-y)
+  calc(var(--spectrum-drop-shadow-emphasized-hover-blur) / 2)
+  var(--spectrum-drop-shadow-emphasized-hover-color)
+);
+```
+
+## Elevated
+Elevated shadows can be used on containers that appear on top of content, such as menus, coach marks, popovers, and floating bar panels.
+
+### `box-shadow`
+<Story of={DropShadowStories.BoxShadowElevated} />
+```
+box-shadow:
+  var(--spectrum-drop-shadow-elevated-x)
+  var(--spectrum-drop-shadow-elevated-y)
+  var(--spectrum-drop-shadow-elevated-blur)
+  var(--spectrum-drop-shadow-elevated-color);
+```
+
+### `filter: drop-shadow()`
+<Story of={DropShadowStories.DropShadowElevated} />
+```
+filter: drop-shadow(
+  var(--spectrum-drop-shadow-elevated-x)
+  var(--spectrum-drop-shadow-elevated-y)
+  calc(var(--spectrum-drop-shadow-elevated-blur) / 2)
+  var(--spectrum-drop-shadow-elevated-color)
+);
+```

.storybook/foundations/drop-shadow/drop-shadow.stories.js

@@ -0,0 +1,74 @@
+import { html } from "lit";
+import { classMap } from "lit/directives/class-map.js";
+import "./index.css";
+
+export default {
+  title: "Foundations/Drop shadow",
+  description: "Drop shadows draw attention and give the appearance of depth. By default, this style is used to show elevation, when content appears on top of other content.",
+  component: "Drop shadow",
+  tags: ['foundation'],
+}
+
+const DropShadowSwatch = ({rootClass = "spectrum-Foundations-Example-DropShadow-swatch", variant, ...args}) => {
+  const { isDropShadow } = args;
+  return html`
+  <div class=${classMap({
+    [rootClass]: true,
+    [`${rootClass}--${variant}-drop-shadow`]: typeof variant !== undefined && !!isDropShadow,
+    [`${rootClass}--${variant}-box-shadow`]: typeof variant !== undefined && !isDropShadow,
+  })}></div>
+`;}
+
+const DropShadowBackground = ({rootClass = "spectrum-Foundations-Example-swatch-container", color, ...args}) => html`
+    <div class=${classMap({
+      [rootClass]: true,
+      "spectrum--light": color === "light",
+      "spectrum--dark": color === "dark",
+    })}>
+      ${DropShadowSwatch(args)}
+    </div>
+  `;
+
+const DropShadowVariant = ({...args}) => html`
+  <div class="spectrum-Foundations-Example-variant-container">
+    ${DropShadowBackground({...args, color: "light"})}
+    ${DropShadowBackground({...args, color: "dark"})}
+  </div>
+`;
+
+
+export const DropShadowEmphasizedDefault = DropShadowVariant.bind({});
+DropShadowEmphasizedDefault.args = {
+  variant: "emphasized-default",
+  isDropShadow: true,
+};
+
+export const DropShadowEmphasizedHover = DropShadowVariant.bind({});
+DropShadowEmphasizedHover.args = {
+  variant: "emphasized-hover",
+  isDropShadow: true,
+};
+
+export const DropShadowElevated = DropShadowVariant.bind({});
+DropShadowElevated.args = {
+  variant: "elevated",
+  isDropShadow: true,
+};
+
+export const BoxShadowEmphasizedDefault = DropShadowVariant.bind({});
+BoxShadowEmphasizedDefault.args = {
+  variant: "emphasized-default",
+  isDropShadow: false,
+};
+
+export const BoxShadowEmphasizedHover = DropShadowVariant.bind({});
+BoxShadowEmphasizedHover.args = {
+  variant: "emphasized-hover",
+  isDropShadow: false,
+};
+
+export const BoxShadowElevated = DropShadowVariant.bind({});
+BoxShadowElevated.args = {
+  variant: "elevated",
+  isDropShadow: false,
+};

.storybook/foundations/drop-shadow/index.css

@@ -0,0 +1,115 @@
+/*!
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/* stylelint-disable spectrum-tools/no-unknown-custom-properties */
+
+.spectrum-Foundations-Example-DropShadow-swatch {
+  block-size: 150px;
+  inline-size: 150px;
+  background-color: var(--spectrum-gray-25);
+  border-radius: var(--spectrum-corner-radius-large-default);
+  border: transparent;
+}
+
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch {
+  background-color: var(--spectrum-gray-75); /* matches dark mode design spec rgb(34, 34, 34) */
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow {
+  box-shadow:
+    var(--spectrum-drop-shadow-emphasized-default-x)
+    var(--spectrum-drop-shadow-emphasized-default-y)
+    var(--spectrum-drop-shadow-emphasized-default-blur)
+    var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color));
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow {
+  filter: drop-shadow(
+    var(--spectrum-drop-shadow-emphasized-default-x)
+    var(--spectrum-drop-shadow-emphasized-default-y)
+    calc(var(--spectrum-drop-shadow-emphasized-default-blur) / 2) /* adjust blur by half of box-shadow */
+    var(--mod-drop-shadow-emphasized-default-color, var(--spectrum-drop-shadow-emphasized-default-color))
+  );
+}
+
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-box-shadow,
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-default-drop-shadow {
+/* adjustment because color tokens do not work properly on foundations pages */
+  --mod-drop-shadow-emphasized-default-color: var(--spectrum-drop-shadow-color-100);
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow {
+  box-shadow:
+    var(--spectrum-drop-shadow-emphasized-hover-x)
+    var(--spectrum-drop-shadow-emphasized-hover-y)
+    var(--spectrum-drop-shadow-emphasized-hover-blur)
+    var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color));
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow {
+  filter: drop-shadow(
+    var(--spectrum-drop-shadow-emphasized-hover-x)
+    var(--spectrum-drop-shadow-emphasized-hover-y)
+    calc(var(--spectrum-drop-shadow-emphasized-hover-blur) / 2) /* adjust blur by half of box-shadow */
+    var(--mod-drop-shadow-emphasized-hover-color, var(--spectrum-drop-shadow-emphasized-hover-color))
+  );
+}
+
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-drop-shadow,
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--emphasized-hover-box-shadow {
+/* adjustment because color tokens do not work properly on foundations pages */
+  --mod-drop-shadow-emphasized-hover-color: var(--spectrum-drop-shadow-color-200);
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow {
+  box-shadow:
+    var(--spectrum-drop-shadow-elevated-x)
+    var(--spectrum-drop-shadow-elevated-y)
+    var(--spectrum-drop-shadow-elevated-blur)
+    var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color));
+}
+
+.spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow {
+  filter: drop-shadow(
+    var(--spectrum-drop-shadow-elevated-x)
+    var(--spectrum-drop-shadow-elevated-y)
+    calc(var(--spectrum-drop-shadow-elevated-blur) / 2) /* adjust blur by half of box-shadow */
+    var(--mod-drop-shadow-elevated-color, var(--spectrum-drop-shadow-elevated-color))
+  );
+}
+
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--elevated-drop-shadow,
+.spectrum--light .spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow,
+.spectrum--dark .spectrum-Foundations-Example-DropShadow-swatch--elevated-box-shadow {
+/* adjustment because color tokens do not work properly on foundations pages */
+  --mod-drop-shadow-elevated-color: var(--spectrum-drop-shadow-color-200);
+}
+
+.spectrum-Foundations-Example-swatch-container {
+  background-color: var(--spectrum-gray-25);
+  block-size: 200px;
+  inline-size: 300px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.spectrum-Foundations-Example-variant-container {
+  background-color: var(--spectrum-gray-25);
+  display: flex;
+  flex-direction: row;
+}