feat!: spectrum 2 foundations release

Breaking change: Migration of tokens to S2 foundations

---
Co-authored-by: Patrick Fulton <[email protected]>
Co-authored-by: Cory Dransfeldt <[email protected]>
Co-authored-by: Aziz Ramos <[email protected]>
Co-authored-by: Josh Winn <[email protected]>
Co-authored-by: Rise Erpelding <[email protected]>
Co-authored-by: Marissa Huysentruyt <[email protected]>
Co-authored-by: Rajdeep Chandra <[email protected]>
Co-authored-by: TarunAdobe <[email protected]>
Co-authored-by: Dragan Eror <[email protected]>

.changeset/metal-walls-scream.md

@@ -0,0 +1,19 @@
+---
+"@spectrum-css/preview": major
+---
+
+## Breaking change
+
+This update removes the previously deprecated component documentation for **cyclebutton**, **quickaction**, **searchwithin**, and **splitbutton**.
+
+To support the Spectrum 2 (S2) Foundations release, Storybook has been updated to toggle token packages to connect the following labels with their appropriate data sources:
+
+- **Spectrum 1**: Flagged as the "legacy" context, this version is no longer the default for the component contexts. When selected, Storybook will load the `@spectrum-css/tokens` at release `v14.6.0` and attach the `.spectrum--legacy` class to the container.
+- **Spectrum 2**: The new default context, this version represents the "S2 Foundations" release which serves as a bridge between S1 and S2. Components in this context are not fully S2 and will not exactly match specifications but they do reflect a significant move toward the S2 designs. For full details, see the token and component-level changelogs.
+- **Express**: This now deprecated context is still rendered in Storybook by leveraging the `@spectrum-css/tokens` at release `v14.6.0`. Please note that Express and S1 will be removed in the next major release.
+
+This release also includes:
+
+- New migration documentation for S1 -> S2 updates
+- Fix for the duplicate line numbers in the code preview plugin
+- Updated styles to integrate Spectrum styling into the Storybook UI

.changeset/wise-otters-burn.md

@@ -0,0 +1,110 @@
+---
+"@spectrum-css/floatingactionbutton": major
+"@spectrum-css/opacitycheckerboard": major
+"@spectrum-css/illustratedmessage": major
+"@spectrum-css/coachindicator": major
+"@spectrum-css/contextualhelp": major
+"@spectrum-css/progresscircle": major
+"@spectrum-css/dropindicator": major
+"@spectrum-css/infieldbutton": major
+"@spectrum-css/actionbutton": major
+"@spectrum-css/pickerbutton": major
+"@spectrum-css/actiongroup": major
+"@spectrum-css/alertbanner": major
+"@spectrum-css/alertdialog": major
+"@spectrum-css/buttongroup": major
+"@spectrum-css/clearbutton": major
+"@spectrum-css/closebutton": major
+"@spectrum-css/colorhandle": major
+"@spectrum-css/colorslider": major
+"@spectrum-css/inlinealert": major
+"@spectrum-css/logicbutton": major
+"@spectrum-css/progressbar": major
+"@spectrum-css/statuslight": major
+"@spectrum-css/swatchgroup": major
+"@spectrum-css/actionmenu": major
+"@spectrum-css/breadcrumb": major
+"@spectrum-css/colorloupe": major
+"@spectrum-css/colorwheel": major
+"@spectrum-css/datepicker": major
+"@spectrum-css/fieldgroup": major
+"@spectrum-css/fieldlabel": major
+"@spectrum-css/pagination": major
+"@spectrum-css/typography": major
+"@spectrum-css/accordion": major
+"@spectrum-css/actionbar": major
+"@spectrum-css/assetcard": major
+"@spectrum-css/assetlist": major
+"@spectrum-css/coachmark": major
+"@spectrum-css/colorarea": major
+"@spectrum-css/splitview": major
+"@spectrum-css/textfield": major
+"@spectrum-css/thumbnail": major
+"@spectrum-css/calendar": major
+"@spectrum-css/checkbox": major
+"@spectrum-css/combobox": major
+"@spectrum-css/dropzone": major
+"@spectrum-css/helptext": major
+"@spectrum-css/steplist": major
+"@spectrum-css/taggroup": major
+"@spectrum-css/treeview": major
+"@spectrum-css/underlay": major
+"@spectrum-css/commons": major
+"@spectrum-css/divider": major
+"@spectrum-css/popover": major
+"@spectrum-css/sidenav": major
+"@spectrum-css/stepper": major
+"@spectrum-css/tooltip": major
+"@spectrum-css/avatar": major
+"@spectrum-css/button": major
+"@spectrum-css/dialog": major
+"@spectrum-css/miller": major
+"@spectrum-css/picker": major
+"@spectrum-css/rating": major
+"@spectrum-css/search": major
+"@spectrum-css/slider": major
+"@spectrum-css/swatch": major
+"@spectrum-css/switch": major
+"@spectrum-css/asset": major
+"@spectrum-css/badge": major
+"@spectrum-css/meter": major
+"@spectrum-css/modal": major
+"@spectrum-css/radio": major
+"@spectrum-css/table": major
+"@spectrum-css/toast": major
+"@spectrum-css/card": major
+"@spectrum-css/dial": major
+"@spectrum-css/form": major
+"@spectrum-css/icon": major
+"@spectrum-css/link": major
+"@spectrum-css/menu": major
+"@spectrum-css/page": major
+"@spectrum-css/tabs": major
+"@spectrum-css/tray": major
+"@spectrum-css/well": major
+"@spectrum-css/tag": major
+---
+
+## Breaking change
+
+This major update creates a bridge between the Spectrum 1 (S1) and Spectrum 2 (S2) designs, dubbed "Spectrum 2 Foundations". These do _NOT_ reflect a fully migrated S2 component. This approach allows consumers to swap the appearance of their components between S1, Express, and S2 by leveraging a "system" layer that remaps the necessary component-level tokens to the appropriate token dataset.
+
+For these components to appear S2, you must load the assets with the `@spectrum-css/tokens` at `v16` or higher.
+
+For S1 or Express, load assets with the `@spectrum-css/tokens` at `v14.x` or `v15.x`.
+
+If you are looking to implement a fully S2 design, please explore the `next` tag releases instead of using this foundations release. **This release is used in Spectrum Web Components 1.x**.
+
+### Deprecations
+
+The `metadata` folder containing the `mods.md` and `metadata.json` assets has been removed from source. To find information about the components including what selectors, modifiers, and passthroughs are used, please see the `dist/metadata.json` asset shipped with every component containing CSS.
+
+The `index-vars.css` asset has been removed in this release as it was previously deprecated and is no longer maintained. Please use the `index.css` or `index-base.css`
+
+### File usage
+
+If you are rendering components and need **only** the S2 Foundations styles, you can make use of the `index.css` asset which contains all the base styles plus the system mappings for S2 Foundations.
+
+If you are using this version to publish **only** an S1 or Express component, you can use the `index-base.css` plus the desired `themes/(spectrum|express).css` file.
+
+To render a component that can be easily swapped between the S2 Foundations, S1, or Express contexts, load `index-base.css` with the `index-theme.css` file and leverage the appropriate context classes (`.spectrum--legacy` for S1 and `.spectrum--express` for Express).

.gitignore

@@ -1,8 +1,6 @@
 dist
-!tokens/dist/index.css
-!tokens/dist/css/*.css
-!tokens/dist/css/express/*.css
-!tokens/dist/css/spectrum/*.css
+!dist/metadata.json
+!tokens/dist/**
 
 # Not committing the map assets, these are dev-only
 *.map

.storybook/assets/base.css

@@ -30,10 +30,15 @@ body {
 
 .spectrum {
 	color: var(--spectrum-neutral-content-color-default);
-	background-color: var(--spectrum-background-layer-1-color);
+	background-color: var(--spectrum-background-base-color);
 	-webkit-tap-highlight-color: rgba(0, 0, 0, 0%);
 }
 
+.spectrum.spectrum--legacy {
+	color: var(--spectrum-neutral-content-color-default);
+	background-color: var(--spectrum-background-layer-1-color);
+}
+
 /* Hide the SVG elements that only include references */
 svg:has(symbol):not(:has(use)) {
 	display: none;

.storybook/decorators/context.js

@@ -1,7 +1,8 @@
 import { makeDecorator, useEffect } from "@storybook/preview-api";
 import { fetchContainers, toggleStyles } from "./helpers.js";
 
-import tokens from "@spectrum-css/tokens/dist/index.css?inline";
+import legacyTokens from "@spectrum-css/tokens-legacy/dist/index.css?inline";
+import tokens from "@spectrum-css/tokens/dist/css/index.css?inline";
 
 /**
  * @type import('@storybook/csf').DecoratorFunction<import('@storybook/web-components').WebComponentsFramework>
@@ -18,7 +19,7 @@ export const withContextWrapper = makeDecorator({
 			} = {},
 			globals: {
 				color = "light",
-				context = "legacy",
+				context = "spectrum",
 				scale = "medium",
 			} = {},
 			parameters: {
@@ -52,14 +53,14 @@ export const withContextWrapper = makeDecorator({
 			const isModern = Boolean(context === "spectrum");
 			const isExpress = Boolean(context === "express");
 
-			// Start by attaching the appropriate tokens to the container
-			toggleStyles(document.body, "tokens", tokens, !isRaw);
-
 			if (!isRaw) {
 				// 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");
 			}
 
+			// Start by attaching the appropriate tokens to the container
+			toggleStyles(document.body, "tokens", isModern ? tokens : legacyTokens, !isRaw, context);
+
 			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;
@@ -127,7 +128,7 @@ export const withContextWrapper = makeDecorator({
 				}
 			}
 
-		}, [context, viewMode, original, staticColor, color, scale, rootClass, tokens, staticColorSettings, showTestingGrid]);
+		}, [context, color, scale, viewMode, original, staticColor, rootClass, tokens, legacyTokens, staticColorSettings, showTestingGrid]);
 
 		return StoryFn(data);
 	},