feat(button): complete 2nd-gen migration

.changeset/new-donuts-march.md

@@ -0,0 +1,17 @@
+---
+'@adobe/spectrum-wc': minor
+---
+
+**feat(button):** Add 2nd-gen `<swc-button>` with full Spectrum 2 visual fidelity. Key changes from 1st-gen `<sp-button>`:
+
+- Renders an internal native `<button>` as the semantic control; the custom-element host carries no button role or tab stop (`delegatesFocus: true`)
+- `ButtonBase` in `core` owns accessible-name resolution, pending-label behavior, and attribute-forwarding so future button-like components can reuse the semantic contract
+- `fill-style` replaces `treatment`; `accessible-label` replaces `label`; `truncate` replaces `no-wrap`; `justified` is new
+- Link API (`href`, `target`, `download`, etc.) removed — use a native `<a>` with global button styles instead
+- Pending state sets `aria-disabled="true"`, derives a descriptive default busy label (`"${name}, busy"`), and remains focusable (fixes SWC-459)
+- Focus indication uses `outline` so the ring is not clipped by truncated overflow (fixes SWC-886)
+- Button label inherits host `visibility` (fixes SWC-701)
+- Static white outline is demonstrated on approved background colors to maintain hover contrast (fixes SWC-1139)
+- `global-button.css` is now auto-generated from `button.css` by the new `@adobe/vite-global-elements-css` plugin, eliminating drift between the component and global-element styling
+
+See the [consumer migration guide](https://spectrum-web-components.adobe.com/?path=/docs/components-button-consumer-migration-guide--readme) for upgrading from 1st-gen `sp-button`.

.changeset/strong-houses-share.md

@@ -0,0 +1,10 @@
+---
+'@spectrum-web-components/button': patch
+---
+
+**deprecate(button):** Mark 1st-gen `sp-button` properties and exports as deprecated ahead of 2nd-gen migration.
+
+- `quiet` property: deprecated with `@deprecated` JSDoc and runtime `window.__swc.warn()`; use `treatment="outline"` instead
+- `treatment` property: deprecated with `@deprecated` JSDoc; use `fill-style` in 2nd-gen
+- `no-wrap` property: deprecated with `@deprecated` JSDoc; use `truncate` in 2nd-gen
+- Type and const exports deprecated: `ButtonVariants`, `ButtonTreatments`, `ButtonStaticColors`, `DeprecatedButtonVariants`, `VALID_VARIANTS`, `VALID_STATIC_COLORS`

.prettierignore

@@ -11,6 +11,7 @@
 **/test-results/
 **/tokens.css
 **/tokens.json
+2nd-gen/packages/swc/stylesheets/global/
 1st-gen/packages/icons/
 1st-gen/packages/iconset/
 1st-gen/packages/icons-ui/

.stylelintignore

@@ -33,4 +33,5 @@
 1st-gen/packages/icons
 1st-gen/packages/iconset
 1st-gen/packages/icons-ui
-1st-gen/packages/icons-workflow
+1st-gen/packages/icons-workflow
+2nd-gen/packages/swc/stylesheets/global

1st-gen/packages/button/src/Button.ts

@@ -22,15 +22,34 @@ import { PendingStateController } from '@spectrum-web-components/reactive-contro
 import buttonStyles from './button.css.js';
 import { ButtonBase } from './ButtonBase.js';
 
+/**
+ * @deprecated The `DeprecatedButtonVariants` type export is deprecated and will
+ * be removed in a future release.
+ */
 export type DeprecatedButtonVariants = 'cta' | 'overBackground';
+
+/**
+ * @deprecated The `ButtonStaticColors` type export is deprecated and will be
+ * removed in a future release.
+ */
 export type ButtonStaticColors = 'white' | 'black';
+
+/**
+ * @deprecated The `ButtonVariants` type export is deprecated and will be
+ * removed in a future release.
+ */
 export type ButtonVariants =
   | 'accent'
   | 'primary'
   | 'secondary'
   | 'negative'
   | ButtonStaticColors
   | DeprecatedButtonVariants;
+
+/**
+ * @deprecated The `VALID_VARIANTS` export is deprecated and will be removed
+ * in a future release.
+ */
 export const VALID_VARIANTS = [
   'accent',
   'primary',
@@ -39,8 +58,17 @@ export const VALID_VARIANTS = [
   'white',
   'black',
 ];
+
+/**
+ * @deprecated The `VALID_STATIC_COLORS` export is deprecated and will be
+ * removed in a future release.
+ */
 export const VALID_STATIC_COLORS = ['white', 'black'];
 
+/**
+ * @deprecated The `ButtonTreatments` type export is deprecated and will be
+ * removed in a future release.
+ */
 export type ButtonTreatments = 'fill' | 'outline';
 
 /**
@@ -161,26 +189,60 @@ export class Button extends SizedMixin(ButtonBase, { noDefaultSize: true }) {
 
   /**
    * The visual treatment to apply to this button.
+   *
+   * @deprecated The `treatment` property is deprecated and will be replaced by
+   * `fill-style` in a future release.
    */
   @property({ reflect: true })
   public treatment: ButtonTreatments = 'fill';
 
   /**
-   * Style this button to be less obvious
+   * Style this button to be less obvious.
+   *
+   * @deprecated The `quiet` property is deprecated and will be removed in a
+   * future release.
    */
   @property({ type: Boolean })
   public set quiet(quiet: boolean) {
     this.treatment = quiet ? 'outline' : 'fill';
+    if (window.__swc?.DEBUG) {
+      window.__swc.warn(
+        this,
+        `The "quiet" property on <${this.localName}> has been deprecated and will be removed in a future release.`,
+        'https://opensource.adobe.com/spectrum-web-components/components/button',
+        { level: 'deprecation' }
+      );
+    }
   }
 
   /**
    * Disables text wrapping within the button component's label.
    * Please note that this option is not a part of the design specification
    * and should be used carefully, with consideration of this overflow behavior
    * and the readability of the button's content.
+   *
+   * @deprecated The `no-wrap` attribute is deprecated and will be replaced by
+   * `truncate` in a future release.
    */
   @property({ type: Boolean, attribute: 'no-wrap', reflect: true })
-  public noWrap = false;
+  public set noWrap(value: boolean) {
+    const oldValue = this._noWrap;
+    this._noWrap = value;
+    this.requestUpdate('noWrap', oldValue);
+    if (window.__swc?.DEBUG) {
+      window.__swc.warn(
+        this,
+        `The "no-wrap" attribute on <${this.localName}> has been deprecated and will be replaced by "truncate" in a future release.`,
+        'https://opensource.adobe.com/spectrum-web-components/components/button',
+        { level: 'deprecation' }
+      );
+    }
+  }
+
+  public get noWrap(): boolean {
+    return this._noWrap;
+  }
+  private _noWrap = false;
 
   public get quiet(): boolean {
     return this.treatment === 'outline';

2nd-gen/packages/core/components/button/Button.base.ts

@@ -0,0 +1,222 @@
+/**
+ * Copyright 2026 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.
+ */
+
+import { PropertyValues } from 'lit';
+import { property, state } from 'lit/decorators.js';
+
+import { SpectrumElement } from '@spectrum-web-components/core/element/index.js';
+import {
+  ObserveSlotPresence,
+  ObserveSlotText,
+  SizedMixin,
+} from '@spectrum-web-components/core/mixins/index.js';
+
+import { BUTTON_VALID_SIZES } from './Button.types.js';
+
+/**
+ * Abstract base class for all button-like components. Owns shared semantic
+ * concerns: interaction state, sizing, slot-derived icon/label state,
+ * accessible-name resolution, and host-to-internal-button attribute forwarding.
+ *
+ * Visual API specific to `sp-button` (`variant`, `fill-style`, `static-color`)
+ * is intentionally absent so that ActionButton, ClearButton, CloseButton,
+ * PickerButton, and InfieldButton can extend this base without inheriting
+ * the `swc-button` visual surface.
+ *
+ * @slot - Visible button label.
+ * @slot icon - Optional leading icon.
+ *
+ * @attribute {ElementSize} size - The size of the button.
+ *
+ * @todo We currently have 3 levels of mixins on this class, but the mixin
+ * composition guide recommends a maximum of 2. Explore reducing after milestone 2.
+ */
+export abstract class ButtonBase extends SizedMixin(
+  ObserveSlotText(ObserveSlotPresence(SpectrumElement, '[slot="icon"]'), ''),
+  { validSizes: BUTTON_VALID_SIZES }
+) {
+  static override shadowRootOptions: ShadowRootInit = {
+    ...SpectrumElement.shadowRootOptions,
+    delegatesFocus: true,
+  };
+
+  // ──────────────────
+  //     SHARED API
+  // ──────────────────
+
+  /**
+   * Whether the button is disabled. Removes focusability and prevents
+   * interaction.
+   */
+  @property({ type: Boolean, reflect: true })
+  public disabled: boolean = false;
+
+  /**
+   * Whether the button is in a pending (busy) state. The button remains
+   * focusable but activation is suppressed.
+   */
+  @property({ type: Boolean, reflect: true })
+  public pending: boolean = false;
+
+  /**
+   * Accessible label forwarded to the internal `<button>` element as
+   * `aria-label`. Required for icon-only buttons, which have no visible text.
+   */
+  @property({ type: String, attribute: 'accessible-label' })
+  public accessibleLabel?: string;
+
+  /**
+   * Custom accessible label used during the pending state. When omitted,
+   * the pending label is derived from the resolved non-busy accessible name
+   * plus a busy suffix (e.g. "Save, busy").
+   */
+  @property({ type: String, attribute: 'pending-label' })
+  public pendingLabel?: string;
+
+  /**
+   * Tracks whether the pending visual (disabled colors + spinner) is currently
+   * active. Set to `true` after a 1-second delay once `pending` becomes true,
+   * so the button does not immediately flash to its unavailable appearance.
+   * Protected so subclasses can reference it in their `classMap` binding.
+   */
+  @state()
+  protected pendingActive: boolean = false;
+
+  // ──────────────────────
+  //     IMPLEMENTATION
+  // ──────────────────────
+
+  private _pendingTimer: number | null = null;
+
+  protected get hasIcon(): boolean {
+    return this.slotContentIsPresent;
+  }
+
+  protected get hasLabel(): boolean {
+    return this.slotHasContent;
+  }
+
+  /**
+   * Resolves the accessible name for the button from `accessibleLabel` or
+   * visible text content. Returns `null` when no accessible name is
+   * determinable.
+   *
+   * @internal
+   */
+  protected getResolvedAccessibleName(): string | null {
+    return this.accessibleLabel ?? (this.textContent?.trim() || null);
+  }
+
+  /**
+   * Derives the pending-state accessible label. Prefers an explicit
+   * `pendingLabel`, then falls back to the resolved non-busy accessible
+   * name plus a ", busy" suffix, then a fixed "Busy" fallback.
+   *
+   * @internal
+   */
+  protected getPendingAccessibleName(): string {
+    if (this.pendingLabel) {
+      return this.pendingLabel;
+    }
+    const resolvedName = this.getResolvedAccessibleName();
+    return resolvedName ? `${resolvedName}, busy` : 'Busy';
+  }
+
+  /**
+   * Returns the set of attributes that should be forwarded to the internal
+   * semantic `<button>` element, if not otherwise directly managed.
+   *
+   * @internal
+   */
+  protected getForwardedButtonAttributes(): Record<
+    string,
+    string | boolean | undefined
+  > {
+    return {
+      disabled: this.disabled,
+      'aria-disabled': this.pending && !this.disabled ? 'true' : undefined,
+    };
+  }
+
+  public override connectedCallback(): void {
+    super.connectedCallback();
+    this.addEventListener('click', this.handleClick);
+  }
+
+  public override disconnectedCallback(): void {
+    this.removeEventListener('click', this.handleClick);
+    if (this._pendingTimer !== null) {
+      clearTimeout(this._pendingTimer);
+      this._pendingTimer = null;
+    }
+    this.pendingActive = false;
+    super.disconnectedCallback();
+  }
+
+  /**
+   * Suppresses click activation while the button is in a `pending` state.
+   * Subclasses' templates wire this onto the rendered `<button>` via `@click`.
+   */
+  protected readonly handleClick = (event: Event): void => {
+    if (this.pending) {
+      event.stopImmediatePropagation();
+    }
+  };
+
+  protected override update(changedProperties: PropertyValues): void {
+    if (changedProperties.has('pending')) {
+      if (this.pending) {
+        this._pendingTimer = setTimeout(() => {
+          if (this.pending) {
+            const internalButton = this.renderRoot.querySelector('button');
+            if (internalButton) {
+              internalButton.style.setProperty(
+                '--_swc-button-pending-inline-size',
+                `${internalButton.offsetWidth}px`
+              );
+            }
+            this.pendingActive = true;
+          }
+          this._pendingTimer = null;
+        }, 1000);
+      } else {
+        if (this._pendingTimer !== null) {
+          clearTimeout(this._pendingTimer);
+          this._pendingTimer = null;
+        }
+        this.renderRoot
+          .querySelector('button')
+          ?.style.removeProperty('--_swc-button-pending-inline-size');
+        this.pendingActive = false;
+      }
+    }
+    super.update(changedProperties);
+    if (window.__swc?.DEBUG) {
+      if (this.pending && this.disabled) {
+        window.__swc.warn(
+          this,
+          `<${this.localName}> should not set both "pending" and "disabled" simultaneously. Use "pending" to keep the button focusable while unavailable, or "disabled" to fully remove it from the tab order.`,
+          'https://opensource.adobe.com/spectrum-web-components/components/button/#pending',
+          { issues: ['pending + disabled'] }
+        );
+      }
+      if (this.hasIcon && !this.hasLabel && !this.accessibleLabel) {
+        window.__swc.warn(
+          this,
+          `<${this.localName}> with an icon and no label must have an "accessible-label" attribute to be accessible.`,
+          'https://opensource.adobe.com/spectrum-web-components/components/button/#icon-only',
+          { issues: ['accessible-label'] }
+        );
+      }
+    }
+  }
+}