@ds-mo/ui 2.4.0 → 2.5.0

package/src/wc/components/Menu/Menu.tsx

@@ -2,6 +2,8 @@ import { Component, Prop, State, Event, EventEmitter, Element, Watch, Listen, h,
 import { resolveCssLengthPx, resolveCssTimeMs, TOKEN_DEFAULTS } from '../../utils';
 import { computeMenuPosition, type MenuAlign, type MenuSide } from './menu-position';
 import type { MenuItemData, MenuSection } from './menu-types';
+import { isMenuGradientPickerSection } from './menu-types';
+import type { ShellGradientPreset } from '../../nav/shell-gradient-presets';
 
 /** rAF retries while the popup mounts or the anchor resolves. */
 const POSITION_RETRY_BUDGET = 8;
@@ -41,6 +43,8 @@ export class Menu {
 
   @Event() dsClose!: EventEmitter<void>;
   @Event() dsSelect!: EventEmitter<MenuItemData>;
+  /** Emitted when a `gradient-picker` section swatch is chosen. */
+  @Event() dsGradientSelect!: EventEmitter<ShellGradientPreset>;
 
   private clickOutsideHandler: ((e: MouseEvent) => void) | null = null;
   private scrollResizeHandler: (() => void) | null = null;
@@ -136,7 +140,9 @@ export class Menu {
   }
 
   private get flatItems(): MenuItemData[] {
-    return this.activeSections.flatMap(s => s.items);
+    return this.activeSections.flatMap(section =>
+      isMenuGradientPickerSection(section) ? [] : section.items,
+    );
   }
 
   private cancelPositionRetry() {
@@ -309,6 +315,10 @@ export class Menu {
     this.close();
   }
 
+  private handleGradientSelect(preset: ShellGradientPreset) {
+    this.dsGradientSelect.emit(preset);
+  }
+
   render() {
     if (!this.shouldRender) return <Host style={{ display: 'contents' }} />;
 
@@ -339,7 +349,11 @@ export class Menu {
           {sections.map((section, si) => (
             <div
               key={si}
-              class={{ 'menu-section': true, 'menu-section--divided': si < sections.length - 1 }}
+              class={{
+                'menu-section': true,
+                'menu-section--divided': si < sections.length - 1,
+                'menu-section--gradient-picker': isMenuGradientPickerSection(section),
+              }}
               role={section.header ? 'group' : undefined}
               aria-label={section.header}
             >
@@ -348,7 +362,16 @@ export class Menu {
                   <span class="text-body-small-emphasis section-label">{section.header}</span>
                 </div>
               )}
-              {section.items.map(item => {
+              {isMenuGradientPickerSection(section) ? (
+                <ds-shell-gradient-picker
+                  value={section.value}
+                  onDsChange={(e: CustomEvent<ShellGradientPreset>) => {
+                    e.stopPropagation();
+                    this.handleGradientSelect(e.detail);
+                  }}
+                />
+              ) : (
+                section.items.map(item => {
                 const idx = flatIdx++;
                 const isFocused = this.focusedIndex === idx;
                 return (
@@ -387,7 +410,7 @@ export class Menu {
                     )}
                   </button>
                 );
-              })}
+              }))}
             </div>
           ))}
         </div>

package/src/wc/components/Menu/menu-types.ts

@@ -1,3 +1,5 @@
+import type { ShellGradientPreset } from '../../nav/shell-gradient-presets';
+
 export type { MenuAlign, MenuSide } from './menu-position';
 
 export interface MenuItemData {
@@ -11,7 +13,23 @@ export interface MenuItemData {
   toggleValue?: boolean;
 }
 
-export interface MenuSection {
+export interface MenuItemsSection {
   header?: string;
   items: MenuItemData[];
 }
+
+export interface MenuGradientPickerSection {
+  header?: string;
+  variant: 'gradient-picker';
+  value: ShellGradientPreset;
+}
+
+export type MenuSection = MenuItemsSection | MenuGradientPickerSection;
+
+export function isMenuGradientPickerSection(
+  section: MenuSection,
+): section is MenuGradientPickerSection {
+  return 'variant' in section && section.variant === 'gradient-picker';
+}
+
+export type { ShellGradientPreset };

package/src/wc/components/PanelTools/PanelTools.tsx

@@ -148,7 +148,7 @@ export class PanelTools {
     this.dsToolChange.emit({ id, selected: next.selected });
   };
 
-  /** Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this. */
+  /** Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this. */
   @Method()
   async activateTool(id: PanelToolsToolId) {
     const item = this.railItems.find(entry => entry.id === id);

package/src/wc/components/ShellGradientPicker/ShellGradientPicker.tsx

@@ -0,0 +1,49 @@
+import { Component, Prop, Event, EventEmitter, h, Host } from '@stencil/core';
+import {
+  SHELL_GRADIENT_PRESETS,
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  type ShellGradientPreset,
+} from '../ShellGradientSwatch/shell-gradient-swatch-types';
+
+@Component({
+  tag: 'ds-shell-gradient-picker',
+  styleUrl: 'ShellGradientPicker.css',
+  scoped: true,
+})
+export class ShellGradientPicker {
+  /** Active shell wash preset. */
+  @Prop({ mutable: true, reflect: true }) value: ShellGradientPreset =
+    DEFAULT_SHELL_GRADIENT_PRESET;
+
+  @Event() dsChange!: EventEmitter<ShellGradientPreset>;
+
+  private handleSwatchSelect = (preset: ShellGradientPreset) => {
+    if (preset === this.value) return;
+    this.value = preset;
+    this.dsChange.emit(preset);
+  };
+
+  render() {
+    return (
+      <Host>
+        <div
+          class="shell-gradient-picker"
+          role="radiogroup"
+          aria-label="Shell gradient theme"
+        >
+          {SHELL_GRADIENT_PRESETS.map(preset => (
+            <ds-shell-gradient-swatch
+              key={preset}
+              preset={preset}
+              selected={this.value === preset}
+              onDsSelect={(e: CustomEvent<ShellGradientPreset>) => {
+                e.stopPropagation();
+                this.handleSwatchSelect(e.detail);
+              }}
+            />
+          ))}
+        </div>
+      </Host>
+    );
+  }
+}

package/src/wc/components/ShellGradientSwatch/ShellGradientSwatch.tsx

@@ -0,0 +1,53 @@
+import { Component, Prop, Event, EventEmitter, h, Host } from '@stencil/core';
+import {
+  SHELL_GRADIENT_PRESET_LABELS,
+  buildShellRadialGradientForPreset,
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  type ShellGradientPreset,
+} from './shell-gradient-swatch-types';
+
+@Component({
+  tag: 'ds-shell-gradient-swatch',
+  styleUrl: 'ShellGradientSwatch.css',
+  scoped: true,
+})
+export class ShellGradientSwatch {
+  /** Wash preset this orb previews. */
+  @Prop({ reflect: true }) preset: ShellGradientPreset = DEFAULT_SHELL_GRADIENT_PRESET;
+
+  /** Selected state — shows an inset brand ring. */
+  @Prop({ reflect: true }) selected = false;
+
+  @Prop() inactive = false;
+
+  @Prop({ attribute: 'aria-label' }) ariaLabel: string | undefined;
+
+  @Event() dsSelect!: EventEmitter<ShellGradientPreset>;
+
+  private handleClick = () => {
+    if (this.inactive) return;
+    this.dsSelect.emit(this.preset);
+  };
+
+  render() {
+    const label = this.ariaLabel ?? SHELL_GRADIENT_PRESET_LABELS[this.preset];
+
+    return (
+      <Host>
+        <button
+          type="button"
+          class={{
+            'shell-gradient-swatch': true,
+            'ds-focus-ring-inset': true,
+            'shell-gradient-swatch--selected': this.selected,
+          }}
+          style={{ backgroundImage: buildShellRadialGradientForPreset(this.preset) }}
+          aria-label={label}
+          aria-pressed={this.selected ? 'true' : 'false'}
+          disabled={this.inactive}
+          onClick={this.handleClick}
+        />
+      </Host>
+    );
+  }
+}

package/src/wc/components/ShellGradientSwatch/shell-gradient-swatch-types.ts

@@ -0,0 +1,16 @@
+import type { ShellGradientPreset } from '../../nav/shell-gradient-presets';
+import {
+  SHELL_GRADIENT_PRESET_LABELS,
+  buildShellRadialGradientForPreset,
+} from '../../nav/shell-gradient-presets';
+
+export type { ShellGradientPreset };
+
+export {
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  SHELL_GRADIENT_PRESETS,
+  SHELL_GRADIENT_PRESET_LABELS,
+  buildShellRadialGradientForPreset,
+  isShellGradientPreset,
+  shellGradientPresetStopToken,
+} from '../../nav/shell-gradient-presets';

package/src/wc/components.d.ts

@@ -7,6 +7,7 @@
 import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
 import { AccordionItemData } from "./components/Accordion/Accordion";
 import { NavChromeStyle } from "./nav/nav-chrome";
+import { ShellGradientPreset } from "./nav/shell-gradient-presets";
 import { BadgeSurface, BadgeVariant } from "./components/Badge/Badge";
 import { BannerContrast, BannerIntent } from "./components/Banner/Banner";
 import { BarNavTab } from "./components/BarNav/bar-nav-types";
@@ -31,6 +32,7 @@ import { PanelToolsItem, PanelToolsToolId } from "./components/PanelTools/panel-
 import { RadioOption } from "./components/RadioGroup/RadioGroup";
 import { ScrollbarVariant } from "./components/Scrollbar/Scrollbar";
 import { SelectOption } from "./components/Select/Select";
+import { ShellGradientPreset as ShellGradientPreset1 } from "./components/ShellGradientSwatch/shell-gradient-swatch-types";
 import { SkeletonVariant } from "./components/Skeleton/Skeleton";
 import { SurfaceBackground, SurfaceContrast, SurfaceElement, SurfaceElevation, SurfaceIntent, SurfaceRadius } from "./components/Surface/Surface";
 import { TabItem } from "./components/TabGroup/tab-item-utils";
@@ -45,6 +47,7 @@ import { ToggleGroupBackground, ToggleGroupElevation, ToggleGroupItem, ToggleGro
 import { TooltipAlign, TooltipSide } from "./components/Tooltip/Tooltip";
 export { AccordionItemData } from "./components/Accordion/Accordion";
 export { NavChromeStyle } from "./nav/nav-chrome";
+export { ShellGradientPreset } from "./nav/shell-gradient-presets";
 export { BadgeSurface, BadgeVariant } from "./components/Badge/Badge";
 export { BannerContrast, BannerIntent } from "./components/Banner/Banner";
 export { BarNavTab } from "./components/BarNav/bar-nav-types";
@@ -69,6 +72,7 @@ export { PanelToolsItem, PanelToolsToolId } from "./components/PanelTools/panel-
 export { RadioOption } from "./components/RadioGroup/RadioGroup";
 export { ScrollbarVariant } from "./components/Scrollbar/Scrollbar";
 export { SelectOption } from "./components/Select/Select";
+export { ShellGradientPreset as ShellGradientPreset1 } from "./components/ShellGradientSwatch/shell-gradient-swatch-types";
 export { SkeletonVariant } from "./components/Skeleton/Skeleton";
 export { SurfaceBackground, SurfaceContrast, SurfaceElement, SurfaceElevation, SurfaceIntent, SurfaceRadius } from "./components/Surface/Surface";
 export { TabItem } from "./components/TabGroup/tab-item-utils";
@@ -103,6 +107,11 @@ export namespace Components {
           * @default false
          */
         "gradient": boolean;
+        /**
+          * Built-in shell wash preset when `gradient` is true. `cool` (blue), `neutral` (grey), `warm` (yellow). `gradientSrc` overrides when set.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "gradientPreset": ShellGradientPreset;
         /**
           * Optional custom gradient for `background-image` (e.g. SVG URL). When set, overrides the built-in radial wash.
           * @default ''
@@ -119,7 +128,7 @@ export namespace Components {
          */
         "navStyle": NavChromeStyle;
         /**
-          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K/A/S/M/N toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native.
           * @default true
          */
         "shortcutsEnabled": boolean;
@@ -719,7 +728,7 @@ export namespace Components {
     }
     interface DsPanelTools {
         /**
-          * Toggle any rail tool open/closed — shell shortcuts ⌘/Ctrl+K/A/S/M/N call this.
+          * Toggle any rail tool open/closed — shell shortcuts K/A/S/M/N call this.
          */
         "activateTool": (id: PanelToolsToolId) => Promise<void>;
         /**
@@ -802,6 +811,30 @@ export namespace Components {
          */
         "value": string;
     }
+    interface DsShellGradientPicker {
+        /**
+          * Active shell wash preset.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "value": ShellGradientPreset1;
+    }
+    interface DsShellGradientSwatch {
+        "ariaLabel": string | undefined;
+        /**
+          * @default false
+         */
+        "inactive": boolean;
+        /**
+          * Wash preset this orb previews.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "preset": ShellGradientPreset1;
+        /**
+          * Selected state — shows an inset brand ring.
+          * @default false
+         */
+        "selected": boolean;
+    }
     interface DsSkeleton {
         /**
           * Height as a CSS value string or number (px).
@@ -1212,6 +1245,14 @@ export interface DsSelectCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLDsSelectElement;
 }
+export interface DsShellGradientPickerCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsShellGradientPickerElement;
+}
+export interface DsShellGradientSwatchCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLDsShellGradientSwatchElement;
+}
 export interface DsSliderCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLDsSliderElement;
@@ -1480,6 +1521,7 @@ declare global {
     interface HTMLDsMenuElementEventMap {
         "dsClose": void;
         "dsSelect": MenuItemData;
+        "dsGradientSelect": ShellGradientPreset;
     }
     interface HTMLDsMenuElement extends Components.DsMenu, HTMLStencilElement {
         addEventListener<K extends keyof HTMLDsMenuElementEventMap>(type: K, listener: (this: HTMLDsMenuElement, ev: DsMenuCustomEvent<HTMLDsMenuElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
@@ -1613,6 +1655,40 @@ declare global {
         prototype: HTMLDsSelectElement;
         new (): HTMLDsSelectElement;
     };
+    interface HTMLDsShellGradientPickerElementEventMap {
+        "dsChange": ShellGradientPreset1;
+    }
+    interface HTMLDsShellGradientPickerElement extends Components.DsShellGradientPicker, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsShellGradientPickerElementEventMap>(type: K, listener: (this: HTMLDsShellGradientPickerElement, ev: DsShellGradientPickerCustomEvent<HTMLDsShellGradientPickerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsShellGradientPickerElementEventMap>(type: K, listener: (this: HTMLDsShellGradientPickerElement, ev: DsShellGradientPickerCustomEvent<HTMLDsShellGradientPickerElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsShellGradientPickerElement: {
+        prototype: HTMLDsShellGradientPickerElement;
+        new (): HTMLDsShellGradientPickerElement;
+    };
+    interface HTMLDsShellGradientSwatchElementEventMap {
+        "dsSelect": ShellGradientPreset1;
+    }
+    interface HTMLDsShellGradientSwatchElement extends Components.DsShellGradientSwatch, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLDsShellGradientSwatchElementEventMap>(type: K, listener: (this: HTMLDsShellGradientSwatchElement, ev: DsShellGradientSwatchCustomEvent<HTMLDsShellGradientSwatchElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLDsShellGradientSwatchElementEventMap>(type: K, listener: (this: HTMLDsShellGradientSwatchElement, ev: DsShellGradientSwatchCustomEvent<HTMLDsShellGradientSwatchElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLDsShellGradientSwatchElement: {
+        prototype: HTMLDsShellGradientSwatchElement;
+        new (): HTMLDsShellGradientSwatchElement;
+    };
     interface HTMLDsSkeletonElement extends Components.DsSkeleton, HTMLStencilElement {
     }
     var HTMLDsSkeletonElement: {
@@ -1800,6 +1876,8 @@ declare global {
         "ds-radio-group": HTMLDsRadioGroupElement;
         "ds-scrollbar": HTMLDsScrollbarElement;
         "ds-select": HTMLDsSelectElement;
+        "ds-shell-gradient-picker": HTMLDsShellGradientPickerElement;
+        "ds-shell-gradient-swatch": HTMLDsShellGradientSwatchElement;
         "ds-skeleton": HTMLDsSkeletonElement;
         "ds-slider": HTMLDsSliderElement;
         "ds-surface": HTMLDsSurfaceElement;
@@ -1840,6 +1918,11 @@ declare namespace LocalJSX {
           * @default false
          */
         "gradient"?: boolean;
+        /**
+          * Built-in shell wash preset when `gradient` is true. `cool` (blue), `neutral` (grey), `warm` (yellow). `gradientSrc` overrides when set.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "gradientPreset"?: ShellGradientPreset;
         /**
           * Optional custom gradient for `background-image` (e.g. SVG URL). When set, overrides the built-in radial wash.
           * @default ''
@@ -1856,7 +1939,7 @@ declare namespace LocalJSX {
          */
         "navStyle"?: NavChromeStyle;
         /**
-          * When `true` (default), registers global shell keyboard shortcuts. Tool chords (⌘/Ctrl+K/A/S/M/N) toggle their drawer open and closed; ⌘/Ctrl+[ toggles panel nav; ⌘/Ctrl+] closes any open tool drawer.
+          * When `true` (default), registers global shell keyboard shortcuts. `[` toggles panel nav; `]` closes tools; K/A/S/M/N toggle tool drawers. Modifiers are ignored so browser chords like ⌘N stay native.
           * @default true
          */
         "shortcutsEnabled"?: boolean;
@@ -2374,6 +2457,10 @@ declare namespace LocalJSX {
         "menuWidth"?: string | undefined;
         "minWidth"?: string | undefined;
         "onDsClose"?: (event: DsMenuCustomEvent<void>) => void;
+        /**
+          * Emitted when a `gradient-picker` section swatch is chosen.
+         */
+        "onDsGradientSelect"?: (event: DsMenuCustomEvent<ShellGradientPreset>) => void;
         "onDsSelect"?: (event: DsMenuCustomEvent<MenuItemData>) => void;
         /**
           * @default false
@@ -2597,6 +2684,32 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    interface DsShellGradientPicker {
+        "onDsChange"?: (event: DsShellGradientPickerCustomEvent<ShellGradientPreset1>) => void;
+        /**
+          * Active shell wash preset.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "value"?: ShellGradientPreset1;
+    }
+    interface DsShellGradientSwatch {
+        "ariaLabel"?: string | undefined;
+        /**
+          * @default false
+         */
+        "inactive"?: boolean;
+        "onDsSelect"?: (event: DsShellGradientSwatchCustomEvent<ShellGradientPreset1>) => void;
+        /**
+          * Wash preset this orb previews.
+          * @default DEFAULT_SHELL_GRADIENT_PRESET
+         */
+        "preset"?: ShellGradientPreset1;
+        /**
+          * Selected state — shows an inset brand ring.
+          * @default false
+         */
+        "selected"?: boolean;
+    }
     interface DsSkeleton {
         /**
           * Height as a CSS value string or number (px).
@@ -2964,6 +3077,7 @@ declare namespace LocalJSX {
         "gradient": boolean;
         "grid": boolean;
         "gradientSrc": string;
+        "gradientPreset": ShellGradientPreset;
         "shortcutsEnabled": boolean;
     }
     interface DsBadgeAttributes {
@@ -3171,6 +3285,15 @@ declare namespace LocalJSX {
         "ariaLabel": string | undefined;
         "ariaLabelledby": string | undefined;
     }
+    interface DsShellGradientPickerAttributes {
+        "value": ShellGradientPreset;
+    }
+    interface DsShellGradientSwatchAttributes {
+        "preset": ShellGradientPreset;
+        "selected": boolean;
+        "inactive": boolean;
+        "ariaLabel": string | undefined;
+    }
     interface DsSkeletonAttributes {
         "variant": SkeletonVariant;
         "width": string;
@@ -3309,6 +3432,8 @@ declare namespace LocalJSX {
         "ds-radio-group": Omit<DsRadioGroup, keyof DsRadioGroupAttributes> & { [K in keyof DsRadioGroup & keyof DsRadioGroupAttributes]?: DsRadioGroup[K] } & { [K in keyof DsRadioGroup & keyof DsRadioGroupAttributes as `attr:${K}`]?: DsRadioGroupAttributes[K] } & { [K in keyof DsRadioGroup & keyof DsRadioGroupAttributes as `prop:${K}`]?: DsRadioGroup[K] };
         "ds-scrollbar": Omit<DsScrollbar, keyof DsScrollbarAttributes> & { [K in keyof DsScrollbar & keyof DsScrollbarAttributes]?: DsScrollbar[K] } & { [K in keyof DsScrollbar & keyof DsScrollbarAttributes as `attr:${K}`]?: DsScrollbarAttributes[K] } & { [K in keyof DsScrollbar & keyof DsScrollbarAttributes as `prop:${K}`]?: DsScrollbar[K] };
         "ds-select": Omit<DsSelect, keyof DsSelectAttributes> & { [K in keyof DsSelect & keyof DsSelectAttributes]?: DsSelect[K] } & { [K in keyof DsSelect & keyof DsSelectAttributes as `attr:${K}`]?: DsSelectAttributes[K] } & { [K in keyof DsSelect & keyof DsSelectAttributes as `prop:${K}`]?: DsSelect[K] };
+        "ds-shell-gradient-picker": Omit<DsShellGradientPicker, keyof DsShellGradientPickerAttributes> & { [K in keyof DsShellGradientPicker & keyof DsShellGradientPickerAttributes]?: DsShellGradientPicker[K] } & { [K in keyof DsShellGradientPicker & keyof DsShellGradientPickerAttributes as `attr:${K}`]?: DsShellGradientPickerAttributes[K] } & { [K in keyof DsShellGradientPicker & keyof DsShellGradientPickerAttributes as `prop:${K}`]?: DsShellGradientPicker[K] };
+        "ds-shell-gradient-swatch": Omit<DsShellGradientSwatch, keyof DsShellGradientSwatchAttributes> & { [K in keyof DsShellGradientSwatch & keyof DsShellGradientSwatchAttributes]?: DsShellGradientSwatch[K] } & { [K in keyof DsShellGradientSwatch & keyof DsShellGradientSwatchAttributes as `attr:${K}`]?: DsShellGradientSwatchAttributes[K] } & { [K in keyof DsShellGradientSwatch & keyof DsShellGradientSwatchAttributes as `prop:${K}`]?: DsShellGradientSwatch[K] };
         "ds-skeleton": Omit<DsSkeleton, keyof DsSkeletonAttributes> & { [K in keyof DsSkeleton & keyof DsSkeletonAttributes]?: DsSkeleton[K] } & { [K in keyof DsSkeleton & keyof DsSkeletonAttributes as `attr:${K}`]?: DsSkeletonAttributes[K] } & { [K in keyof DsSkeleton & keyof DsSkeletonAttributes as `prop:${K}`]?: DsSkeleton[K] };
         "ds-slider": Omit<DsSlider, keyof DsSliderAttributes> & { [K in keyof DsSlider & keyof DsSliderAttributes]?: DsSlider[K] } & { [K in keyof DsSlider & keyof DsSliderAttributes as `attr:${K}`]?: DsSliderAttributes[K] } & { [K in keyof DsSlider & keyof DsSliderAttributes as `prop:${K}`]?: DsSlider[K] } & OneOf<"label", DsSlider["label"], DsSliderAttributes["label"]>;
         "ds-surface": Omit<DsSurface, keyof DsSurfaceAttributes> & { [K in keyof DsSurface & keyof DsSurfaceAttributes]?: DsSurface[K] } & { [K in keyof DsSurface & keyof DsSurfaceAttributes as `attr:${K}`]?: DsSurfaceAttributes[K] } & { [K in keyof DsSurface & keyof DsSurfaceAttributes as `prop:${K}`]?: DsSurface[K] };
@@ -3356,6 +3481,8 @@ declare module "@stencil/core" {
             "ds-radio-group": LocalJSX.IntrinsicElements["ds-radio-group"] & JSXBase.HTMLAttributes<HTMLDsRadioGroupElement>;
             "ds-scrollbar": LocalJSX.IntrinsicElements["ds-scrollbar"] & JSXBase.HTMLAttributes<HTMLDsScrollbarElement>;
             "ds-select": LocalJSX.IntrinsicElements["ds-select"] & JSXBase.HTMLAttributes<HTMLDsSelectElement>;
+            "ds-shell-gradient-picker": LocalJSX.IntrinsicElements["ds-shell-gradient-picker"] & JSXBase.HTMLAttributes<HTMLDsShellGradientPickerElement>;
+            "ds-shell-gradient-swatch": LocalJSX.IntrinsicElements["ds-shell-gradient-swatch"] & JSXBase.HTMLAttributes<HTMLDsShellGradientSwatchElement>;
             "ds-skeleton": LocalJSX.IntrinsicElements["ds-skeleton"] & JSXBase.HTMLAttributes<HTMLDsSkeletonElement>;
             "ds-slider": LocalJSX.IntrinsicElements["ds-slider"] & JSXBase.HTMLAttributes<HTMLDsSliderElement>;
             "ds-surface": LocalJSX.IntrinsicElements["ds-surface"] & JSXBase.HTMLAttributes<HTMLDsSurfaceElement>;

package/src/wc/nav/index.ts

@@ -37,6 +37,15 @@ export {
   readShellViewportDimensions,
 } from './shell-gradient';
 export type { ShellGradientLayout, ShellViewportDimensions } from './shell-gradient';
+export type { ShellGradientPreset } from './shell-gradient-presets';
+export {
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  SHELL_GRADIENT_PRESETS,
+  SHELL_GRADIENT_PRESET_LABELS,
+  buildShellRadialGradientForPreset,
+  isShellGradientPreset,
+  shellGradientPresetStopToken,
+} from './shell-gradient-presets';
 export type { ChromeTransitionDetail, ChromeTransitionSource } from './chrome-transition';
 export {
   CHROME_TRANSITION_END,

package/src/wc/nav/shell-gradient-presets.ts

@@ -0,0 +1,35 @@
+/** Built-in shell chrome wash presets — cool (blue), neutral (grey), warm (yellow). */
+export type ShellGradientPreset = 'cool' | 'neutral' | 'warm';
+
+export const SHELL_GRADIENT_PRESETS: ShellGradientPreset[] = ['cool', 'neutral', 'warm'];
+
+/** Default wash when `gradient-preset` is omitted. */
+export const DEFAULT_SHELL_GRADIENT_PRESET: ShellGradientPreset = 'neutral';
+
+export const SHELL_GRADIENT_PRESET_LABELS: Record<ShellGradientPreset, string> = {
+  cool: 'Cool',
+  neutral: 'Neutral',
+  warm: 'Warm',
+};
+
+const SHELL_GRADIENT_PRESET_STOP: Record<ShellGradientPreset, string> = {
+  cool: 'var(--color-color-intent-blue-strong-background)',
+  neutral: 'var(--color-color-intent-grey-strong-background)',
+  warm: 'var(--color-color-intent-yellow-strong-background)',
+};
+
+const GRADIENT_GEOMETRY = '100% 100% at 0% 0%';
+
+export function shellGradientPresetStopToken(preset: ShellGradientPreset): string {
+  return SHELL_GRADIENT_PRESET_STOP[preset];
+}
+
+export function isShellGradientPreset(value: string): value is ShellGradientPreset {
+  return (SHELL_GRADIENT_PRESETS as string[]).includes(value);
+}
+
+/** Radial wash for a preset — transparent at top-left into the intent stop. */
+export function buildShellRadialGradientForPreset(preset: ShellGradientPreset): string {
+  const stop = shellGradientPresetStopToken(preset);
+  return `radial-gradient(${GRADIENT_GEOMETRY}, var(--color-background-transparent) 0%, ${stop} 100%)`;
+}

package/src/wc/nav/shell-gradient.ts

@@ -1,4 +1,20 @@
 /** CSS var names consumed by `ds-panel-nav` / `ds-bar-nav` inside `ds-app-shell`. */
+import type { ShellGradientPreset } from './shell-gradient-presets';
+import {
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  buildShellRadialGradientForPreset,
+} from './shell-gradient-presets';
+
+export type { ShellGradientPreset } from './shell-gradient-presets';
+export {
+  DEFAULT_SHELL_GRADIENT_PRESET,
+  SHELL_GRADIENT_PRESETS,
+  SHELL_GRADIENT_PRESET_LABELS,
+  buildShellRadialGradientForPreset,
+  isShellGradientPreset,
+  shellGradientPresetStopToken,
+} from './shell-gradient-presets';
+
 export const SHELL_GRADIENT_IMAGE_VAR = '--ds-shell-gradient-image';
 export const SHELL_GRADIENT_SIZE_VAR = '--ds-shell-gradient-size';
 export const SHELL_GRADIENT_POSITION_PANEL_VAR = '--ds-shell-gradient-position-panel';
@@ -15,19 +31,21 @@ export function shellChromeLayerActive(gradient: boolean, grid: boolean): boolea
   return gradient || grid;
 }
 
-const GRADIENT_GEOMETRY = '100% 100% at 0% 0%';
-
 /**
  * Shell radial wash — same for panel and bar nav.
- * Tokens follow `data-theme` (light/dark blue intent).
+ * Tokens follow `data-theme` (light/dark intent stops).
  */
-export function buildShellRadialGradient(): string {
-  return `radial-gradient(${GRADIENT_GEOMETRY}, var(--color-background-transparent) 0%, var(--color-color-intent-blue-strong-background) 100%)`;
+export function buildShellRadialGradient(
+  preset: ShellGradientPreset = DEFAULT_SHELL_GRADIENT_PRESET,
+): string {
+  return buildShellRadialGradientForPreset(preset);
 }
 
-/** Built-in radial image (optional `gradientSrc` on shell overrides). */
-export function shellGradientImage(): string {
-  return buildShellRadialGradient();
+/** Built-in radial image (`gradientSrc` on shell overrides). */
+export function shellGradientImage(
+  preset: ShellGradientPreset = DEFAULT_SHELL_GRADIENT_PRESET,
+): string {
+  return buildShellRadialGradient(preset);
 }
 
 export interface ShellViewportDimensions {

package/src/wc/nav/shell-shortcuts.ts

@@ -13,13 +13,13 @@ const TOOL_SHORTCUT_KEYS: Record<string, PanelToolsToolId> = {
   n: 'activity',
 };
 
-/** Tool shortcut chords (⌘/Ctrl+K/A/S/M/N) toggle open/closed via `ds-panel-tools.activateTool`. */
+/** Tool shortcut keys (K/A/S/M/N) toggle open/closed via `ds-panel-tools.activateTool`. */
 
-/** True when Cmd (macOS) or Ctrl (Windows/Linux) is held without Alt/Shift. */
-export function isShellShortcutModifier(
+/** True when no modifier keys are held — avoids browser/app chords like ⌘N. */
+export function isBareShellShortcutKey(
   e: Pick<KeyboardEvent, 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>,
 ): boolean {
-  return (e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey;
+  return !e.metaKey && !e.ctrlKey && !e.altKey && !e.shiftKey;
 }
 
 /** Skip shell shortcuts while typing in an editable control. */
@@ -46,11 +46,11 @@ function normalizedShortcutKey(e: Pick<KeyboardEvent, 'key' | 'code'>): string {
   return e.key.length === 1 ? e.key.toLowerCase() : e.key.toLowerCase();
 }
 
-/** Resolve a shell chrome shortcut, or `null` when the chord is not handled. */
+/** Resolve a shell chrome shortcut, or `null` when the key is not handled. */
 export function resolveShellShortcut(
   e: Pick<KeyboardEvent, 'key' | 'code' | 'metaKey' | 'ctrlKey' | 'altKey' | 'shiftKey'>,
 ): ShellShortcutAction | null {
-  if (!isShellShortcutModifier(e)) return null;
+  if (!isBareShellShortcutKey(e)) return null;
 
   const key = normalizedShortcutKey(e);
   if (key === '[') return 'toggle-panel-nav';