@motion-proto/live-tokens 0.68.1 → 0.69.0

package/src/editor/component-editor/ButtonEditor.svelte

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildSiblings } from './scaffolding/siblings';
-  import type { Token } from './scaffolding/types';
+  import type { Token, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'button';
 
@@ -101,14 +101,34 @@
   );
 
   const variantOptions = variants.map((v) => ({ value: v, label: v.charAt(0).toUpperCase() + v.slice(1) }));
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'shimmer',
+      variants: ['default'],
+      variable: () => '--button-shimmer',
+      values: ['var(--shimmer-on)', 'var(--shimmer-off)'],
+      default: { default: 'var(--shimmer-on)' },
+    },
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--button-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--button-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import Button from '../../system/components/Button.svelte';
   import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState, setComponentAlias } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
 
   let shimmerRef = $derived($editorState.components.button?.aliases['--button-shimmer']);
@@ -118,12 +138,49 @@
     setComponentAlias('button', '--button-shimmer', { kind: 'token', name: checked ? '--shimmer-on' : '--shimmer-off' });
   }
 
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--button-primary-hover-surface', '--button-primary-surface'],
+    ['--button-secondary-hover-surface', '--button-secondary-surface'],
+    ['--button-outline-hover-surface', '--button-outline-surface'],
+    ['--button-success-hover-surface', '--button-success-surface'],
+    ['--button-danger-hover-surface', '--button-danger-surface'],
+    ['--button-warning-hover-surface', '--button-warning-surface'],
+  ];
+  const TINT_ON = 'var(--button-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.button?.aliases['--button-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('button', '--button-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('button', hover, { kind: 'token', name: base });
+      else clearComponentAlias('button', hover);
+    }
+  }
+
   let previewSize = $state<'default' | 'small'>('default');
 
   let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
 
   let visibleVariantStates = $derived((v: Variant) => Object.fromEntries(
-    Object.entries(variantStates(v)).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(variantStates(v)).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 
   let visibleSmallStates = $derived(Object.fromEntries(
@@ -158,7 +215,17 @@
       >
         {#snippet extraPropertyRows(stateName)}
           {#if stateName === 'hover'}
-            <div class="property-row">
+            <div class="property-row" data-token-variables="--button-hover-tint-enabled">
+              <span class="property-label">tint layer</span>
+              <Toggle checked={tintOn} onchange={setTintOn} />
+            </div>
+            {#if tintOn}
+              <div class="property-row">
+                <span class="property-label">tint color</span>
+                <UIPaletteSelector variable="--button-hover-tint" {component} showNone={false} />
+              </div>
+            {/if}
+            <div class="property-row" data-token-variables="--button-shimmer">
               <span class="property-label">hover shimmer</span>
               <Toggle checked={shimmerEnabled} onchange={handleShimmerChange} />
             </div>

package/src/editor/component-editor/CardEditor.svelte

@@ -92,14 +92,14 @@
     {
       key: 'hover-border',
       variants: ['default'],
-      variable: () => '--card-hover-border-active',
+      variable: () => '--card-hover-border-enabled',
       values: [HOVER_OFF.border, HOVER_ON.border],
       default: { default: HOVER_OFF.border },
     },
     {
       key: 'hover-shadow',
       variants: ['default'],
-      variable: () => '--card-hover-shadow-active',
+      variable: () => '--card-hover-shadow-enabled',
       values: [HOVER_OFF.shadow, HOVER_ON.shadow],
       default: { default: HOVER_OFF.shadow },
     },
@@ -122,15 +122,15 @@
     ($editorState.components[component]?.aliases ?? {}) as Record<string, import('../core/store/editorTypes').CssVarRef>,
   );
   let hoverEnabled = $derived.by(() => {
-    const ref = aliases['--card-hover-border-active'];
+    const ref = aliases['--card-hover-border-enabled'];
     const raw = ref?.kind === 'literal' ? ref.value : HOVER_OFF.border;
     return raw === HOVER_ON.border;
   });
 
   function setHoverEnabled(checked: boolean) {
     const v = checked ? HOVER_ON : HOVER_OFF;
-    setComponentAlias(component, '--card-hover-border-active', { kind: 'literal', value: v.border });
-    setComponentAlias(component, '--card-hover-shadow-active', { kind: 'literal', value: v.shadow });
+    setComponentAlias(component, '--card-hover-border-enabled', { kind: 'literal', value: v.border });
+    setComponentAlias(component, '--card-hover-shadow-enabled', { kind: 'literal', value: v.shadow });
   }
 </script>
 
@@ -146,7 +146,7 @@
       {#if stateName === 'hover'}
         <div
           class="hover-control"
-          data-token-variables="--card-hover-border-active --card-hover-shadow-active"
+          data-token-variables="--card-hover-border-enabled --card-hover-shadow-enabled"
         >
           <label class="hover-enable">
             <input type="checkbox" checked={hoverEnabled} onchange={(e) => setHoverEnabled(e.currentTarget.checked)} />

package/src/editor/component-editor/DialogEditor.svelte

@@ -12,11 +12,11 @@
   const DEFAULT_CONFIRM: ButtonVariant = 'primary';
   const DEFAULT_CANCEL: ButtonVariant = 'outline';
 
-  // Frame-level tokens (the dialog box itself + overlay + header + body + footer + close icon).
+  // Frame-level tokens (the dialog box itself + scrim + header + body + footer + close icon).
   // Button styling lives in Button.svelte — the dialog only owns its own chrome.
   const frameStates: Record<string, Token[]> = {
-    overlay: [
-      { label: 'backdrop color', groupKey: 'surface', variable: '--dialog-overlay-surface' },
+    scrim: [
+      { label: 'scrim color', groupKey: 'surface', variable: '--dialog-scrim-surface' },
     ],
     dialog: [
       { label: 'surface color', variable: '--dialog-surface' },

package/src/editor/component-editor/IconButtonEditor.svelte

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildSiblings } from './scaffolding/siblings';
-  import type { Token } from './scaffolding/types';
+  import type { Token, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'iconbutton';
 
@@ -92,21 +92,72 @@
     danger: 'fas fa-trash',
     warning: 'fas fa-triangle-exclamation',
   };
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--iconbutton-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--iconbutton-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import IconButton from '../../system/components/IconButton.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--iconbutton-primary-hover-surface', '--iconbutton-primary-surface'],
+    ['--iconbutton-secondary-hover-surface', '--iconbutton-secondary-surface'],
+    ['--iconbutton-outline-hover-surface', '--iconbutton-outline-surface'],
+    ['--iconbutton-success-hover-surface', '--iconbutton-success-surface'],
+    ['--iconbutton-danger-hover-surface', '--iconbutton-danger-surface'],
+    ['--iconbutton-warning-hover-surface', '--iconbutton-warning-surface'],
+  ];
+  const TINT_ON = 'var(--iconbutton-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.iconbutton?.aliases['--iconbutton-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('iconbutton', '--iconbutton-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('iconbutton', hover, { kind: 'token', name: base });
+      else clearComponentAlias('iconbutton', hover);
+    }
+  }
 
   let previewSize = $state<'default' | 'small'>('default');
 
   let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
 
   let visibleVariantStates = $derived((v: Variant) => Object.fromEntries(
-    Object.entries(variantStates(v)).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(variantStates(v)).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 
   let visibleSmallStates = $derived(Object.fromEntries(
@@ -139,6 +190,20 @@
         siblings={buildSiblings(variants, v, variantStates)}
         previewActions={sizeAction}
       >
+        {#snippet extraPropertyRows(stateName)}
+          {#if stateName === 'hover'}
+            <div class="property-row" data-token-variables="--iconbutton-hover-tint-enabled">
+              <span class="property-label">tint layer</span>
+              <Toggle checked={tintOn} onchange={setTintOn} />
+            </div>
+            {#if tintOn}
+              <div class="property-row">
+                <span class="property-label">tint color</span>
+                <UIPaletteSelector variable="--iconbutton-hover-tint" {component} showNone={false} />
+              </div>
+            {/if}
+          {/if}
+        {/snippet}
         {#snippet children({ activeState })}
           {@const forceClass = activeState === 'hover' ? 'force-hover' : activeState === 'active' ? 'force-active' : ''}
           {@const isDisabled = activeState === 'disabled'}

package/src/editor/component-editor/ImageEditor.svelte

@@ -16,22 +16,22 @@
 
   export const allTokens: Token[] = Object.values(states).flat();
 
-  // Global zoom defaults. `none` = off; `scale(...)` = on. `--image-zoom-hover` scales the
-  // content within the masked frame (overflow scaling); `--image-grow-hover` scales the whole
+  // Global zoom defaults. `none` = off; `scale(...)` = on. `--image-zoom-enabled` scales the
+  // content within the masked frame (overflow scaling); `--image-grow-enabled` scales the whole
   // frame so it grows. At most one is ever `scale(...)`.
   const ZOOM_ON = 'scale(var(--image-zoom-scale))';
   export const intrinsics: IntrinsicSpec[] = [
     {
       key: 'zoom',
       variants: ['default'],
-      variable: () => '--image-zoom-hover',
+      variable: () => '--image-zoom-enabled',
       values: ['none', ZOOM_ON],
       default: { default: 'none' },
     },
     {
       key: 'grow',
       variants: ['default'],
-      variable: () => '--image-grow-hover',
+      variable: () => '--image-grow-enabled',
       values: ['none', ZOOM_ON],
       default: { default: 'none' },
     },
@@ -52,15 +52,15 @@
     const ref = aliases[variable];
     return ref?.kind === 'literal' ? ref.value : fallback;
   }
-  let contentOn = $derived(aliasValue('--image-zoom-hover', intrinsics[0].default.default) === ZOOM_ON);
-  let frameOn = $derived(aliasValue('--image-grow-hover', intrinsics[1].default.default) === ZOOM_ON);
+  let contentOn = $derived(aliasValue('--image-zoom-enabled', intrinsics[0].default.default) === ZOOM_ON);
+  let frameOn = $derived(aliasValue('--image-grow-enabled', intrinsics[1].default.default) === ZOOM_ON);
   let useZoom = $derived(contentOn || frameOn);
   // Overflow scaling = mask the zoom to the frame (the content path). Off = grow the frame.
   let overflowScaling = $derived(!frameOn);
 
   function applyZoom(zoomOn: boolean, masked: boolean) {
-    setComponentAlias(component, '--image-zoom-hover', { kind: 'literal', value: zoomOn && masked ? ZOOM_ON : 'none' });
-    setComponentAlias(component, '--image-grow-hover', { kind: 'literal', value: zoomOn && !masked ? ZOOM_ON : 'none' });
+    setComponentAlias(component, '--image-zoom-enabled', { kind: 'literal', value: zoomOn && masked ? ZOOM_ON : 'none' });
+    setComponentAlias(component, '--image-grow-enabled', { kind: 'literal', value: zoomOn && !masked ? ZOOM_ON : 'none' });
   }
   const setUseZoom = (checked: boolean) => applyZoom(checked, overflowScaling);
   const setOverflowScaling = (checked: boolean) => applyZoom(useZoom, checked);

package/src/editor/component-editor/ImageLightboxEditor.svelte

@@ -1,5 +1,5 @@
 <script module lang="ts">
-  import type { Token } from './scaffolding/types';
+  import type { Token, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'imagelightbox';
 
@@ -28,6 +28,17 @@
   };
 
   export const allTokens: Token[] = Object.values(states).flat();
+
+  // How a tile crops inside its frame: a structural choice, not a themeable value.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'tile-fit',
+      variants: ['default'],
+      variable: () => '--imagelightbox-tile-object-fit',
+      values: ['contain', 'cover'],
+      default: { default: 'contain' },
+    },
+  ];
 </script>
 
 <script lang="ts">

package/src/editor/component-editor/MenuSelectEditor.svelte

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildTypeGroupTokens, buildTypeGroupShareableContexts } from './scaffolding/buildTypeGroupTokens';
-  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import type { Token, TypeGroupConfig, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'menuselect';
 
@@ -91,14 +91,55 @@
     ['--menuselect-selected-icon-size', 'selected item'],
     ['--menuselect-disabled-icon-size', 'disabled item'],
   ]);
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--menuselect-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--menuselect-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import MenuSelect from '../../system/components/MenuSelect.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--menuselect-hover-surface', '--menuselect-default-surface'],
+  ];
+  const TINT_ON = 'var(--menuselect-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.menuselect?.aliases['--menuselect-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('menuselect', '--menuselect-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('menuselect', hover, { kind: 'token', name: base });
+      else clearComponentAlias('menuselect', hover);
+    }
+  }
 
   type Item = { value: string; label: string; icon?: string; disabled?: boolean };
   const items: Item[] = [
@@ -114,7 +155,12 @@
   let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
 
   let visibleStates = $derived(Object.fromEntries(
-    Object.entries(states).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(states).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 </script>
 
@@ -126,6 +172,20 @@
     {typeGroups}
     {component}
   >
+    {#snippet extraPropertyRows(stateName)}
+      {#if stateName === 'hover item'}
+        <div class="property-row" data-token-variables="--menuselect-hover-tint-enabled">
+          <span class="property-label">tint layer</span>
+          <Toggle checked={tintOn} onchange={setTintOn} />
+        </div>
+        {#if tintOn}
+          <div class="property-row">
+            <span class="property-label">tint color</span>
+            <UIPaletteSelector variable="--menuselect-hover-tint" {component} showNone={false} />
+          </div>
+        {/if}
+      {/if}
+    {/snippet}
     {#snippet canvasToolbarExtras()}
       <hr class="canvas-toolbar-divider" />
       <label class="show-icons-row">

package/src/editor/component-editor/SegmentedControlEditor.svelte

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildTypeGroupTokens, buildTypeGroupShareableContexts } from './scaffolding/buildTypeGroupTokens';
-  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import type { Token, TypeGroupConfig, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'segmentedcontrol';
 
@@ -123,14 +123,55 @@
   const linkableContexts = new Map<string, string>(
     buildTypeGroupShareableContexts(typeGroups),
   );
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--segmentedcontrol-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--segmentedcontrol-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import SegmentedControl from '../../system/components/SegmentedControl.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--segmentedcontrol-option-hover-surface', '--color-transparent'],
+  ];
+  const TINT_ON = 'var(--segmentedcontrol-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.segmentedcontrol?.aliases['--segmentedcontrol-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('segmentedcontrol', '--segmentedcontrol-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('segmentedcontrol', hover, { kind: 'token', name: base });
+      else clearComponentAlias('segmentedcontrol', hover);
+    }
+  }
 
   type Segment = { value: string; label: string; icon?: string; disabled?: boolean };
   const segments: Segment[] = [
@@ -148,7 +189,12 @@
   let activeTypeGroups = $derived(previewSize === 'small' ? emptyTypeGroups : typeGroups);
 
   let visibleStates = $derived(Object.fromEntries(
-    Object.entries(activeStates).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(activeStates).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 </script>
 
@@ -160,6 +206,20 @@
     typeGroups={activeTypeGroups}
     {component}
   >
+    {#snippet extraPropertyRows(stateName)}
+      {#if stateName === 'hover option'}
+        <div class="property-row" data-token-variables="--segmentedcontrol-hover-tint-enabled">
+          <span class="property-label">tint layer</span>
+          <Toggle checked={tintOn} onchange={setTintOn} />
+        </div>
+        {#if tintOn}
+          <div class="property-row">
+            <span class="property-label">tint color</span>
+            <UIPaletteSelector variable="--segmentedcontrol-hover-tint" {component} showNone={false} />
+          </div>
+        {/if}
+      {/if}
+    {/snippet}
     {#snippet previewActions()}
       <label>
         <span>Size</span>

package/src/editor/component-editor/SideNavigationEditor.svelte

@@ -1,6 +1,6 @@
 <script module lang="ts">
   import { buildTypeGroupColorTokens } from './scaffolding/buildTypeGroupTokens';
-  import type { Token, TypeGroupConfig } from './scaffolding/types';
+  import type { Token, TypeGroupConfig, IntrinsicSpec } from './scaffolding/types';
 
   export const component = 'sidenavigation';
 
@@ -259,14 +259,59 @@
     ['--sidenavigation-panel-padding', 'panel'],
     ['--sidenavigation-title-label-border-width', 'title block'],
   ]);
+
+  // The hover tint is off unless a project turns it on: the gate holds a
+  // transparent layer, a no-op, until it holds the tint itself.
+  export const intrinsics: IntrinsicSpec[] = [
+    {
+      key: 'hover-tint',
+      variants: ['default'],
+      variable: () => '--sidenavigation-hover-tint-enabled',
+      values: ['var(--color-transparent)', 'var(--sidenavigation-hover-tint)'],
+      default: { default: 'var(--color-transparent)' },
+    },
+  ];
 </script>
 
 <script lang="ts">
   import SideNavigation, { type SideNavSection, type SideNavFooter } from '../../system/components/SideNavigation.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import { editorState } from '../core/store/editorStore';
+  import { editorState, setComponentAlias, clearComponentAlias } from '../core/store/editorStore';
   import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+  import Toggle from '../ui/Toggle.svelte';
+  import UIPaletteSelector from '../ui/UIPaletteSelector.svelte';
+
+  // One switch. Turning the tint on also stands each hover surface down to its
+  // own base, so hover is the tint alone rather than a swap wearing a wash.
+  // Written as aliases rather than gated in CSS: a component token's value is
+  // substituted at :root, so it can never name a per-variant private var.
+  // Off clears the overrides, returning each surface to its shipped default.
+  const HOVER_SWAPS: readonly (readonly [hover: string, base: string])[] = [
+    ['--sidenavigation-title-hover-surface', '--sidenavigation-title-default-surface'],
+    ['--sidenavigation-toggle-hover-surface', '--sidenavigation-toggle-default-surface'],
+    ['--sidenavigation-section-hover-surface', '--sidenavigation-section-default-surface'],
+    ['--sidenavigation-item-hover-surface', '--sidenavigation-item-default-surface'],
+    ['--sidenavigation-footer-hover-surface', '--sidenavigation-footer-default-surface'],
+  ];
+  const TINT_ON = 'var(--sidenavigation-hover-tint)';
+  const TINT_OFF = 'var(--color-transparent)';
+
+  let tintOn = $derived.by(() => {
+    const ref = $editorState.components.sidenavigation?.aliases['--sidenavigation-hover-tint-enabled'];
+    return (ref?.kind === 'literal' ? ref.value : TINT_OFF) === TINT_ON;
+  });
+
+  function setTintOn(checked: boolean) {
+    setComponentAlias('sidenavigation', '--sidenavigation-hover-tint-enabled', {
+      kind: 'literal',
+      value: checked ? TINT_ON : TINT_OFF,
+    });
+    for (const [hover, base] of HOVER_SWAPS) {
+      if (checked) setComponentAlias('sidenavigation', hover, { kind: 'token', name: base });
+      else clearComponentAlias('sidenavigation', hover);
+    }
+  }
 
   const demoSections: SideNavSection[] = [
     {
@@ -296,7 +341,12 @@
   let previewOpen = $state(true);
 
   let visibleStates = $derived(Object.fromEntries(
-    Object.entries(states).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+    Object.entries(states).map(([name, list]) => [
+      name,
+      withLinkedDisabled(list, linked.varSet).map((t) =>
+        tintOn && t.variable.endsWith('-hover-surface') ? { ...t, disabled: true } : t,
+      ),
+    ]),
   ) as Record<string, Token[]>);
 
   // Map the active part/state to the demo's force-hover / force-active hooks
@@ -331,6 +381,20 @@
     {component}
     selectorLabel="Part"
   >
+    {#snippet extraPropertyRows(stateName)}
+      {#if stateName.endsWith(' / Hover')}
+        <div class="property-row" data-token-variables="--sidenavigation-hover-tint-enabled">
+          <span class="property-label">tint layer</span>
+          <Toggle checked={tintOn} onchange={setTintOn} />
+        </div>
+        {#if tintOn}
+          <div class="property-row">
+            <span class="property-label">tint color</span>
+            <UIPaletteSelector variable="--sidenavigation-hover-tint" {component} showNone={false} />
+          </div>
+        {/if}
+      {/if}
+    {/snippet}
     {#snippet children({ activeState })}
       {@const { forceHoverPart, forceActivePart } = deriveForce(activeState)}
       <div class="sn-preview-frame">