adobe · castastrophe · Apr 15, 2025 · Apr 22, 2025
diff --git a/.changeset/pre.json b/.changeset/pre.json
@@ -88,7 +88,6 @@
     "@spectrum-css/typography": "8.0.1",
     "@spectrum-css/underlay": "6.0.1",
     "@spectrum-css/well": "7.0.1",
-    "@spectrum-tools/postcss-rgb-mapping": "1.0.0",
     "@spectrum-tools/stylelint-no-missing-var": "2.0.1",
     "@spectrum-tools/stylelint-no-unknown-custom-properties": "2.0.2",
     "@spectrum-tools/stylelint-no-unused-custom-properties": "2.0.3",

diff --git a/.eslintrc b/.eslintrc
@@ -19,6 +19,7 @@
 		"semi": ["warn", "always"],
 		"space-before-blocks": ["warn", "always"]
 	},
+	"ignorePatterns": ["!.storybook"],
 	"overrides": [
 		{
 			"files": ["*.json"],

diff --git a/.github/QUICK-START.md b/.github/QUICK-START.md
@@ -10,61 +10,88 @@ Install the components you want along with their dependencies. Here's an example
 yarn add -DW @spectrum-css/tokens @spectrum-css/typography @spectrum-css/page @spectrum-css/icon @spectrum-css/button
 ```
 
-Spectrum CSS components utilize custom properties in order to change themes and scales. For these to apply, a couple of classes need to be added to the document’s `<html>` tag based on the [visual language](https://github.com/adobe/spectrum-css?tab=readme-ov-file#visual-language), [scale](https://github.com/adobe/spectrum-css?tab=readme-ov-file#scales), and [theme](https://github.com/adobe/spectrum-css?tab=readme-ov-file#themes-colorstops) you wish to use. For example, the following code snippet will display styling for the default Spectrum visual language using medium scale and light color theme:
+Spectrum CSS components utilize custom properties in order to express our design language through a set of core tokens. We leverage the `@adobe/spectrum-tokens` data as a source of this design data and convert it into a set of CSS custom properties. This allows us to use the tokens in our components and to create a consistent design language across all of our components.
+
+Some of these tokens have different values depending on the visual language or scale being used. The default values for all tokens are set to the default values for the light theme and medium scale.
+
+To force the dark theme, you can add `color-scheme: dark` to your container element. Doing this will force the dark value to be used for all tokens that have one. This can be done at any level of the DOM and by leveraging the cascade, the color schemes can be nested or changed at any level. For example, if you want to force the dark theme for a specific component, you can add `color-scheme: dark` to that component's container element.
 
 ```html
-<html class="spectrum spectrum--medium spectrum--light"></html>
+<style>
+  :root {
+    /* Allow user preference to control the color scheme at first */
+    color-scheme: light dark;
+  }
+</style>
+<div class="container" style="color-scheme: dark">
+  <p>A dark themed container</p>
+  <div class="container" style="color-scheme: light">
+    <p>A light themed container</p>
+  </div>
+</div>
+```
+
+The design language also includes a set of token values that represent different device sizes. At the moment, these values are only defined as "medium" and "large", with "medium" as the default which maps generally to a desktop or laptop screen. The "large" value is intended for smaller devices, such as phones and tablets. The default value for all tokens is set to the default value for the medium scale. To force the large scale, you can update the cascading layers inheritance:
+
+```css
+@layers defaults, medium;
+
+@media screen and (min-width: 768px) {
+  @layers defaults, large;
+}
 ```
 
+What's happening here is that the `defaults` layer is being overridden by the `large` layer when the screen size is greater than 768px. This means that all tokens that have a value for the `large` scale will be used instead of the default value. The most useful feature of this approach is that each application can make their own decision about which scale to leverage and at what screen size. This allows for a lot of flexibility in how the design language is applied to different applications.
+
 Use the `index.css` files in your project to include component and global styles ([background theme/colorstop](https://github.com/adobe/spectrum-css?tab=readme-ov-file#themes-colorstops), [platform scaling](https://github.com/adobe/spectrum-css?tab=readme-ov-file#scales), etc.) for the component. If you don't need all of the global styles, peek at the docs for [including assets](https://github.com/adobe/spectrum-css?tab=readme-ov-file#including-assets)). Use this file by including the stylesheet (plus stylesheets for dependencies) in the `<head>` tag:
 
 ```html
 <head>
-	<!-- Include global tokens depedency first -->
-	<link
-		rel="stylesheet"
-		href="node_modules/@spectrum-css/tokens/dist/index.css"
-	/>
-
-	<!-- Include index.css for the components you're using -->
-	<link
-		rel="stylesheet"
-		href="node_modules/@spectrum-css/button/dist/index.css"
-	/>
+  <!-- Include global tokens depedency first -->
+  <link
+    rel="stylesheet"
+    href="node_modules/@spectrum-css/tokens/dist/index.css"
+  />
+
+  <!-- Include index.css for the components you're using -->
+  <link
+    rel="stylesheet"
+    href="node_modules/@spectrum-css/button/dist/index.css"
+  />
 </head>
 ```
 
 Inside the `<body>` tag, add the markup for your component (Spectrum button in our example). The example also includes the CSS class names `spectrum-Button--fill` and `spectrum-Button--accent`, to use the accent variant:
 
 ```html
 <button
-	class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM"
+  class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM"
 >
-	<span class="spectrum-Button-label">Button</span>
+  <span class="spectrum-Button-label">Button</span>
 </button>
 ```
 
 To put it all together, your final html file will look like this:
 
 ```html
 <html class="spectrum spectrum--light spectrum--medium">
-	<head>
-		<link
-			rel="stylesheet"
-			href="node_modules/@spectrum-css/tokens/dist/index.css"
-		/>
-		<link
-			rel="stylesheet"
-			href="node_modules/@spectrum-css/button/dist/index.css"
-		/>
-	</head>
-	<body>
-		<button
-			class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM"
-		>
-			<span class="spectrum-Button-label">Button</span>
-		</button>
-	</body>
+  <head>
+    <link
+      rel="stylesheet"
+      href="node_modules/@spectrum-css/tokens/dist/index.css"
+    />
+    <link
+      rel="stylesheet"
+      href="node_modules/@spectrum-css/button/dist/index.css"
+    />
+  </head>
+  <body>
+    <button
+      class="spectrum-Button spectrum-Button--fill spectrum-Button--accent spectrum-Button--sizeM"
+    >
+      <span class="spectrum-Button-label">Button</span>
+    </button>
+  </body>
 </html>
 ```
 

diff --git a/.storybook/assets/base.css b/.storybook/assets/base.css
@@ -1,5 +1,3 @@
-/* stylelint-disable selector-class-pattern -- Targeting pre-defined Storybook classes */
-
 /*!
  * Copyright 2024 Adobe. All rights reserved.
  *
@@ -13,33 +11,42 @@
  * governing permissions and limitations under the License.
  */
 
-body {
+:root {
 	--spectrum-font-family: var(--spectrum-sans-font-family-stack);
 	--spectrum-font-style: var(--spectrum-default-font-style);
 	--spectrum-font-size: var(--spectrum-font-size-100);
 
+	/* Gradient that changes with the color theme. */
+	--spectrum-examples-gradient: linear-gradient(45deg, var(--spectrum-magenta-1500), var(--spectrum-blue-1500));
+
+	/* Gradients that do not change with the color theme, for use in static color backgrounds. */
+	--spectrum-examples-gradient-static-black: linear-gradient(45deg, rgb(255 241 246), rgb(238 245 255));
+	--spectrum-examples-gradient-static-white: linear-gradient(45deg, rgb(64 0 22), rgb(14 24 67));
+
+	color-scheme: light dark;
+}
+
+body {
 	margin: 0;
 
 	font-family: var(--spectrum-font-family);
 	font-size: var(--spectrum-font-size);
 	font-style: var(--spectrum-font-style);
-
-	color: var(--spectrum-neutral-content-color-default, rgb(34, 34, 34));
-	background-color: var(--spectrum-background-base-color, rgb(230, 230, 230));
 }
 
-.spectrum {
-	color: var(--spectrum-neutral-content-color-default);
-	background-color: var(--spectrum-background-base-color);
-	-webkit-tap-highlight-color: rgba(0, 0, 0, 0%);
+body,
+.docs-story {
+	color: var(--spectrum-neutral-content-color-default, rgb(34, 34, 34));
+	background: var(--spectrum-background-base-color, rgb(230, 230, 230));
+	-webkit-tap-highlight-color: rgb(0, 0, 0, 0%);
 }
 
-.spectrum .spectrum-examples-static-black {
-	background: var(--spectrum-examples-gradient-static-black);
+.spectrum-examples-static-black {
+	background: var(--spectrum-examples-gradient-static-black) !important;
 }
 
-.spectrum .spectrum-examples-static-white {
-	background: var(--spectrum-examples-gradient-static-white);
+.spectrum-examples-static-white {
+	background: var(--spectrum-examples-gradient-static-white) !important;
 }
 
 /* Hide the SVG elements that only include references */
@@ -61,7 +68,7 @@ svg:has(symbol):not(:has(use)) {
 	line-height: normal;
 	letter-spacing: normal;
 	text-transform: none;
-	border-block-end: 1px solid hsla(203deg, 50%, 30%, 15%);
+	border-block-end: 1px solid hsl(203deg, 50%, 30%, 15%);
 }
 
 /* Force the modal wrapper to be contained by the frame not the viewport */
@@ -76,5 +83,3 @@ svg:has(symbol):not(:has(use)) {
 	story view), due to Storybook's inline style that sets overflow: auto */
 	overflow: visible !important;
 }
-
-/* stylelint-enable selector-class-pattern */
diff --git a/.storybook/decorators/context.js b/.storybook/decorators/context.js
@@ -47,9 +47,6 @@ export const withContextWrapper = makeDecorator({
 			// Start by attaching the appropriate tokens to the container
 			toggleStyles(document.body, "tokens", tokens, true);
 
-			// add the default classes to the body to ensure labels, headings, and borders are styled correctly
-			document.body.classList.add("spectrum", "spectrum--light", "spectrum--medium");
-
 			for (const container of fetchContainers(id, isDocs, isTesting)) {
 				// Check if the container is a testing wrapper to prevent applying colors around the testing grid
 				const isTestingWrapper = isTesting ? container.matches("body:has([data-testing-preview]),[data-testing-preview]") : false;
@@ -71,9 +68,6 @@ export const withContextWrapper = makeDecorator({
 				// If we can't determine the static key, we can't use the static color
 				if (!staticKey) hasStaticElement = false;
 
-				// Every container gets the spectrum class
-				container.classList.toggle("spectrum", true);
-
 				// Let the static color override the color if it's set
 				if (!isTestingWrapper && hasStaticElement && staticColorSettings[staticKey]?.color) {
 					color = staticColorSettings[staticKey].color;
@@ -85,13 +79,8 @@ export const withContextWrapper = makeDecorator({
 					color = "light";
 				}
 
-				for (let c of ["light", "dark"]) {
-					container.classList.toggle(`spectrum--${c}`, c === color);
-				}
-
-				for (const s of ["medium", "large"]) {
-					container.classList.toggle(`spectrum--${s}`, s === scale);
-				}
+				container.style.setProperty("color-scheme", color);
+				container.classList.toggle("spectrum--large", scale === "large");
 
 				if (!isTestingWrapper) {
 					if (hasStaticElement && staticKey && staticColorSettings[staticKey]) {

diff --git a/.storybook/decorators/icon-sprites.js b/.storybook/decorators/icon-sprites.js
@@ -10,10 +10,6 @@ export const withIconSpriteSheet = makeDecorator({
 	name: "withIconSpriteSheet",
 	parameterName: "spritesheet",
 	wrapper: (StoryFn, context) => {
-		const {
-			loaded = {},
-		} = context;
-
 		useEffect(() => {
 			// Inject the sprite sheets into the document
 			let sprite = document.getElementById("spritesheets");

diff --git a/.storybook/decorators/utilities.js b/.storybook/decorators/utilities.js
@@ -116,7 +116,7 @@ export const Container = ({
 	if (withBorder) {
 		borderStyles["padding-inline"] = "24px";
 		borderStyles["padding-block"] = "24px";
-		borderStyles["border"] = "1px solid rgba(var(--spectrum-gray-600-rgb), 20%)";
+		borderStyles["border"] = "1px solid color-mix(in srgb, var(--spectrum-gray-600) 20%, transparent)";
 		borderStyles["border-radius"] = "4px";
 		gap = 80;
 	}
@@ -158,6 +158,7 @@ export const Container = ({
 					"row-gap": "24px",
 					"align-items": heading && level > 1 ? "flex-start" : undefined,
 					"justify-content": direction === "column" ? "center" : "flex-start",
+					"background": level === 1 && !isDocs ? "var(--spectrum-background-base-color)" : undefined,
 					...borderStyles,
 					...wrapperStyles,
 				})}

diff --git a/.storybook/foundations/corner-rounding/action-button-corner-rounding.stories.js b/.storybook/foundations/corner-rounding/action-button-corner-rounding.stories.js
@@ -14,7 +14,7 @@ export default {
 			handles: ["click .spectrum-ActionButton:not([disabled])"],
 		},
 	},
-	tags: ['!dev'],
+	tags: ["!dev"],
 };
 
 const ActionButton = (args, context) => html`

diff --git a/.storybook/foundations/corner-rounding/checkbox-corner-rounding.stories.js b/.storybook/foundations/corner-rounding/checkbox-corner-rounding.stories.js
@@ -12,10 +12,10 @@ export default {
 	},
 	parameters: {
 		actions: {
-			handles: ['click input[type="checkbox"]'],
+			handles: ["click input[type=\"checkbox\"]"],
 		},
 	},
-	tags: ['!dev'],
+	tags: ["!dev"],
 };
 
 const Checkbox = (args = {}, context = {}) => html`
@@ -82,7 +82,7 @@ const CheckboxTable = (args, context) => {
 			</tbody>
 		</table>
 	`;
-}
+};
 
 export const CheckboxExamples = CheckboxTable.bind({});
 CheckboxExamples.args = {};
diff --git a/.storybook/foundations/drop-shadow/drop-shadow.stories.js b/.storybook/foundations/drop-shadow/drop-shadow.stories.js
@@ -1,5 +1,7 @@
 import { html } from "lit";
 import { classMap } from "lit/directives/class-map.js";
+import { styleMap } from "lit/directives/style-map.js";
+
 import "./index.css";
 
 export default {
@@ -28,17 +30,15 @@ const DropShadowSwatch = ({
 
 const DropShadowBackground = (
 	{
-		rootClass = "spectrum-Foundations-Example-swatch-container",
 		color,
 		...args
 	},
 	context,
 ) => html`
 	<div
-		class=${classMap({
-			[rootClass]: true,
-			"spectrum--light": color === "light",
-			"spectrum--dark": color === "dark",
+		class="spectrum-Foundations-Example-swatch-container"
+		style=${styleMap({
+			"color-scheme": color,
 		})}
 	>
 		${DropShadowSwatch(args, context)}