npm - @motion-proto/live-tokens - Versions diffs - 0.30.0 → 0.31.0 - Mend

@motion-proto/live-tokens 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/.claude/skills/live-tokens-create-component/SKILL.md +1 -0
package/dist-plugin/{chunk-2TW77U3O.js → chunk-Y3K6NR6V.js} +11 -1
package/dist-plugin/index.cjs +11 -1
package/dist-plugin/index.js +1 -1
package/dist-plugin/tokensCssMigrations/index.cjs +11 -1
package/dist-plugin/tokensCssMigrations/index.js +1 -1
package/package.json +3 -2
package/src/editor/component-editor/ImageLightboxEditor.svelte +27 -3
package/src/system/components/Dialog.svelte +4 -1
package/src/system/components/ImageLightbox.svelte +500 -153
package/src/system/internal/portal.ts +18 -0
package/src/system/styles/tokens.css +0 -9

package/.claude/skills/live-tokens-create-component/SKILL.md CHANGED Viewed

@@ -106,6 +106,7 @@ The authoritative recognised list lives in `bin/check-component.mjs` (`KNOWN_SUF
 ### Rules that bite
+- **Fixed overlays must portal to `<body>`.** Any `position: fixed` layer (modal, lightbox, full-screen backdrop) is trapped — clipped or painted under other chrome — by a transformed / `isolation` / `contain` / `will-change` ancestor, which real consumer pages (and the editor's own preview pane) commonly have. Render the fixed layer with `use:portal` from `src/system/internal/portal.ts` so it escapes to `<body>`; pass `use:portal={enabled}` to keep an in-flow preview variant in place (see `Dialog`). `check:overlay-portal` fails the build if a component has `position: fixed` without it. Anchored popovers (`position: absolute` relative to a trigger, like `Tooltip`) are exempt. Two consequences of moving to `<body>`: DOM events from the layer no longer bubble to a consumer ancestor (use component callbacks, as `Dialog` does), and a subtree-scoped CSS-variable theme no longer reaches it (this library themes via `:root`, so fine here). If the layer is a modal, also give it `role="dialog"` + `aria-modal`, move focus in on open and restore it on close, and trap `Tab` (see `ImageLightbox`).
 - **State before property.** `--mywidget-button-hover-surface` ✓ — `--mywidget-button-surface-hover` ✗ (breaks sibling matching).
 - **Defaults reference theme tokens, never raw values.** `var(--surface-primary)` ✓ — `#6a4ce8` ✗.
 - **No abbreviations.** `bg` → `surface`; `fg` → `text`; component ids are never abbreviated.

package/dist-plugin/{chunk-2TW77U3O.js → chunk-Y3K6NR6V.js} RENAMED Viewed

@@ -173,6 +173,15 @@ var tokensCssMigration_2026_06_03_transformScaleAdditions = {
   }
 };
+// vite-plugin/tokensCssMigrations/migrations/2026-06-04-remove-dead-size-icon-scale.ts
+var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
+  id: "2026-06-04-remove-dead-size-icon-scale",
+  description: "Remove the unused --size-icon-* scale (live scale is --icon-size-*)",
+  apply(css) {
+    return removeTokensMatching(css, (name) => name.startsWith("--size-icon-"));
+  }
+};
 // vite-plugin/files/dataPaths.ts
 import fs from "fs";
 import path from "path";
@@ -223,7 +232,8 @@ function resolveDataDirs(opts = {}) {
 var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_05_29_typographyScaleAdditions,
   tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup,
-  tokensCssMigration_2026_06_03_transformScaleAdditions
+  tokensCssMigration_2026_06_03_transformScaleAdditions,
+  tokensCssMigration_2026_06_04_removeDeadSizeIconScale
 ];
 function runTokensCssMigrations(css) {
   let out = css;

package/dist-plugin/index.cjs CHANGED Viewed

@@ -797,11 +797,21 @@ var tokensCssMigration_2026_06_03_transformScaleAdditions = {
   }
 };
+// vite-plugin/tokensCssMigrations/migrations/2026-06-04-remove-dead-size-icon-scale.ts
+var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
+  id: "2026-06-04-remove-dead-size-icon-scale",
+  description: "Remove the unused --size-icon-* scale (live scale is --icon-size-*)",
+  apply(css) {
+    return removeTokensMatching(css, (name) => name.startsWith("--size-icon-"));
+  }
+};
 // vite-plugin/tokensCssMigrations/index.ts
 var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_05_29_typographyScaleAdditions,
   tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup,
-  tokensCssMigration_2026_06_03_transformScaleAdditions
+  tokensCssMigration_2026_06_03_transformScaleAdditions,
+  tokensCssMigration_2026_06_04_removeDeadSizeIconScale
 ];
 function runTokensCssMigrations(css) {
   let out = css;

package/dist-plugin/index.js CHANGED Viewed

@@ -4,7 +4,7 @@ import {
   resolveDataDirs,
   runTokensCssMigrations,
   validateTokensCss
-} from "./chunk-2TW77U3O.js";
+} from "./chunk-Y3K6NR6V.js";
 // vite-plugin/themeFileApi.ts
 import fs2 from "fs";

package/dist-plugin/tokensCssMigrations/index.cjs CHANGED Viewed

@@ -218,6 +218,15 @@ var tokensCssMigration_2026_06_03_transformScaleAdditions = {
   }
 };
+// vite-plugin/tokensCssMigrations/migrations/2026-06-04-remove-dead-size-icon-scale.ts
+var tokensCssMigration_2026_06_04_removeDeadSizeIconScale = {
+  id: "2026-06-04-remove-dead-size-icon-scale",
+  description: "Remove the unused --size-icon-* scale (live scale is --icon-size-*)",
+  apply(css) {
+    return removeTokensMatching(css, (name) => name.startsWith("--size-icon-"));
+  }
+};
 // vite-plugin/files/dataPaths.ts
 var import_fs = __toESM(require("fs"), 1);
 var import_path = __toESM(require("path"), 1);
@@ -255,7 +264,8 @@ function readLiveTokensConfig() {
 var TOKENS_CSS_MIGRATIONS = [
   tokensCssMigration_2026_05_29_typographyScaleAdditions,
   tokensCssMigration_2026_05_29_sectiondividerLegacyAxisCleanup,
-  tokensCssMigration_2026_06_03_transformScaleAdditions
+  tokensCssMigration_2026_06_03_transformScaleAdditions,
+  tokensCssMigration_2026_06_04_removeDeadSizeIconScale
 ];
 function runTokensCssMigrations(css) {
   let out = css;

package/dist-plugin/tokensCssMigrations/index.js CHANGED Viewed

@@ -9,7 +9,7 @@ import {
   renameToken,
   runTokensCssMigrations,
   validateTokensCss
-} from "../chunk-2TW77U3O.js";
+} from "../chunk-Y3K6NR6V.js";
 export {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -95,6 +95,7 @@
     "deploy:local": "bash scripts/deploy-local.sh",
     "check:no-style-imports": "node scripts/check-no-style-imports.mjs",
     "check:slot-prose": "node scripts/check-slot-prose.mjs",
+    "check:overlay-portal": "node scripts/check-overlay-portal.mjs",
     "check:editor-font-isolation": "node scripts/check-editor-font-isolation.mjs",
     "check:component-defaults": "node scripts/sync-component-defaults.mjs --check",
     "check:production-is-default": "node scripts/check-production-is-default.mjs",
@@ -104,7 +105,7 @@
     "collapse:manifest": "node scripts/collapse-manifest-to-default.mjs",
     "check:smoke-install": "bash scripts/smoke-install.sh",
     "check:smoke-create": "bash scripts/smoke-create.sh",
-    "prepublishOnly": "npm run check:no-style-imports && npm run check:slot-prose && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:smoke-install && npm run check:smoke-create"
+    "prepublishOnly": "npm run check:no-style-imports && npm run check:slot-prose && npm run check:overlay-portal && npm run check:editor-font-isolation && npm run check:component-defaults && npm run check:production-is-default && npm run check:docs-content && npm run build:lib && npm run check:smoke-install && npm run check:smoke-create"
   },
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.0",

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

@@ -33,18 +33,34 @@
   import ImageLightbox from '../../system/components/ImageLightbox.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import demoImageUrl from '../../system/assets/offering.webp';
+  import offeringUrl from '../../system/assets/offering.webp';
+  import newspaperUrl from '../../system/assets/newspaper.webp';
+  const demoImages = [
+    // Offering carries explicit dimensions (the no-reflow path); Newspaper omits
+    // them to exercise self-measure from the loaded image.
+    { src: offeringUrl, alt: 'Offering', width: 1455, height: 970 },
+    { src: newspaperUrl, alt: 'Newspaper' },
+  ];
+  let multiple = $state(true);
 </script>
 <ComponentEditorBase
   {component}
   title="Image Lightbox"
-  description="Click an inline image to expand it into a centered modal with a backdrop. Extended mode adds zoom controls and drag panning."
+  description="Click an inline image to expand it into a centered modal with a backdrop. Pass multiple images for a gallery (chevrons + counter). Extended mode adds zoom controls and drag panning."
   tokens={allTokens}
 >
   <VariantGroup name="imagelightbox" title="Image Lightbox" {states} {component}>
+    {#snippet stateActions()}
+      <label class="preview-toggle">
+        <input type="checkbox" checked={multiple} onchange={(e) => (multiple = e.currentTarget.checked)} />
+        <span>Multiple images</span>
+      </label>
+    {/snippet}
     <div class="preview-frame">
-      <ImageLightbox src={demoImageUrl} alt="Demo image" width={1024} height={640} extended />
+      <ImageLightbox images={multiple ? demoImages : [demoImages[0]]} extended />
     </div>
   </VariantGroup>
 </ComponentEditorBase>
@@ -55,4 +71,12 @@
     max-width: 28rem;
     margin: 0 auto;
   }
+  .preview-toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ui-space-4);
+    font-size: var(--ui-font-size-sm);
+    color: var(--ui-text-secondary);
+    cursor: pointer;
+  }
 </style>

package/src/system/components/Dialog.svelte CHANGED Viewed

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { createEventDispatcher, tick } from 'svelte';
   import type { Snippet } from 'svelte';
+  import { portal } from '../internal/portal';
   import Button from './Button.svelte';
   import type { ButtonVariant, DialogButtonSpec } from './types';
@@ -105,7 +106,9 @@
 </script>
 {#if show}
-  <div class="dialog-backdrop" class:inline>
+  <!-- The fixed backdrop portals to <body> to escape transformed/isolated
+       ancestors; the inline preview variant stays in flow. -->
+  <div class="dialog-backdrop" class:inline use:portal={!inline}>
     <div class="dialog" style="width: {width}; max-width: {width};">
       <div class="dialog-content">
         {#if title}

package/src/system/components/ImageLightbox.svelte CHANGED Viewed

@@ -1,47 +1,118 @@
 <script lang="ts">
   import { onMount, tick } from 'svelte';
+  import { portal } from '../internal/portal';
-  interface Props {
+  interface GalleryImage {
     src: string;
     alt: string;
+    width?: number;
+    height?: number;
+  }
+  interface Props {
+    src?: string;
+    alt?: string;
     width?: number | undefined;
     height?: number | undefined;
+    /** Pass two or more to turn the lightbox into a gallery: left/right chevrons
+        and an `i / n` counter appear once open, plus arrow-key navigation. A
+        single-entry array behaves exactly like a lone `src`. */
+    images?: GalleryImage[];
     maxWidth?: number | string | undefined;
+    /** Closed-thumbnail object-fit. `cover` crops the thumbnail to fill its box;
+        the expanded modal always uses `contain` so the whole image stays visible.
+        `cover` only crops when the thumbnail has its own box (an aspect from
+        `width`/`height`, or a CSS-constrained container). */
+    fit?: 'contain' | 'cover';
     /** When true, shows a bottom toolbar (zoom in/out + percent) and a top-right close button, and enables wheel/drag zoom inside the open modal. When false, click anywhere closes. */
     extended?: boolean;
   }
   let {
-    src,
-    alt,
+    src = undefined,
+    alt = undefined,
     width = undefined,
     height = undefined,
+    images = undefined,
     maxWidth = undefined,
+    fit = 'contain',
     extended = false,
   }: Props = $props();
+  const items = $derived(
+    images && images.length
+      ? images
+      : src != null
+        ? [{ src, alt: alt ?? '', width, height }]
+        : [],
+  );
+  let index = $state(0);
+  const current = $derived(items[index]);
+  const cover = $derived(items[0]);
+  const isGallery = $derived(items.length > 1);
+  const dialogLabel = $derived(
+    isGallery
+      ? `Image ${index + 1} of ${items.length}${current?.alt ? `: ${current.alt}` : ''}`
+      : current?.alt || 'Image',
+  );
   const MIN_SCALE = 1;
   const MAX_SCALE = 5;
   const ZOOM_STEP = 1.5;
   const TRANSITION_MS = 350;
   const TRANSITION_EASE = 'cubic-bezier(0.65, 0, 0.35, 1)';
-  let wrapperEl: HTMLDivElement;
-  let tileEl: HTMLDivElement;
-  let transformEl: HTMLDivElement;
-  let overlayEl: HTMLDivElement;
+  // Gallery navigation: outgoing slides out + shrinks + fades; incoming slides
+  // in from the opposite side, staggered. Easings mirror --ease-in/out-cubic.
+  const NAV_MS = 250;
+  const NAV_STAGGER_MS = 125;
+  const NAV_SHIFT_PX = 32;
+  const NAV_SCALE = 0.95;
+  const EASE_IN = 'cubic-bezier(0.32, 0, 0.67, 0)';
+  const EASE_OUT = 'cubic-bezier(0.33, 1, 0.68, 1)';
+  let thumbEl: HTMLButtonElement | undefined = $state();
+  let modalEl: HTMLDivElement | undefined = $state();
+  let stageEl: HTMLDivElement | undefined = $state();
+  let transformEl: HTMLDivElement | undefined = $state();
+  let overlayEl: HTMLDivElement | undefined = $state();
   let toolbarEl: HTMLDivElement | undefined = $state();
   let closeBtnEl: HTMLButtonElement | undefined = $state();
+  let prevBtnEl: HTMLButtonElement | undefined = $state();
+  let nextBtnEl: HTMLButtonElement | undefined = $state();
+  let counterEl: HTMLDivElement | undefined = $state();
+  let incomingEl: HTMLImageElement | undefined = $state();
+  let outgoingEl: HTMLImageElement | undefined = $state();
+  // `mounted` keeps the portaled modal in the DOM through the close animation;
+  // `open` is the visual state the chrome reacts to.
+  let mounted = $state(false);
   let open = $state(false);
   let scale = $state(1);
   let offset = { x: 0, y: 0 };
+  // The image leaving during a gallery transition; rendered as a second layer
+  // until its slide-out finishes, then dropped.
+  let outgoing = $state<GalleryImage | null>(null);
+  let navigating = false;
+  // Aspect ratio per image, keyed by src: explicit width/height when given, else
+  // measured from the loaded <img>. The thumbnail reads the cover's entry and the
+  // modal reads the current image's, so they are never confused for each other.
+  let measured = $state<Record<string, number>>({});
+  let reducedMotion = $state(false);
+  const dur = (ms = TRANSITION_MS) => (reducedMotion ? 0 : ms);
   // Pointer drag for pan (extended + zoomed only).
   let dragState: { startX: number; startY: number; baseX: number; baseY: number; pointerId: number } | null = null;
   let didDrag = false;
-  const aspect = $derived(width && height ? width / height : undefined);
+  const aspectOf = (it?: GalleryImage) =>
+    it ? (it.width && it.height ? it.width / it.height : measured[it.src]) : undefined;
+  const coverAspect = $derived(aspectOf(cover)); // inline thumbnail box
+  const aspect = $derived(aspectOf(current)); // open modal box
   function viewportTarget() {
     const vw = window.innerWidth;
@@ -62,8 +133,8 @@
   }
   function clampOffset(x: number, y: number, s: number) {
-    if (!tileEl) return { x: 0, y: 0 };
-    const r = tileEl.getBoundingClientRect();
+    if (!stageEl) return { x: 0, y: 0 };
+    const r = stageEl.getBoundingClientRect();
     const maxX = Math.max(0, (r.width * s - r.width) / 2);
     const maxY = Math.max(0, (r.height * s - r.height) / 2);
     return {
@@ -101,10 +172,8 @@
   function cancelAnimations() {
     // Commit each animation's current value to inline styles before cancelling,
     // so a mid-flight cancel doesn't visually snap the element back to its
-    // pre-animation state. After cancel, the WAAPI effect is gone and the
-    // committed inline values are what we'll either animate from next or
-    // clear via cssText = ''.
-    for (const el of [tileEl, overlayEl, toolbarEl, closeBtnEl]) {
+    // pre-animation state.
+    for (const el of [stageEl, overlayEl, toolbarEl, closeBtnEl, prevBtnEl, nextBtnEl, counterEl]) {
       if (!el) continue;
       for (const a of el.getAnimations()) {
         try { a.commitStyles(); } catch {}
@@ -114,100 +183,218 @@
   }
   async function openLightbox() {
-    if (open || !tileEl) return;
-    cancelAnimations();
-    const start = tileEl.getBoundingClientRect();
-    const target = viewportTarget();
+    if (open || !thumbEl) return;
+    const start = thumbEl.getBoundingClientRect();
+    mounted = true;
     open = true;
     document.body.style.overflow = 'hidden';
     hideEditorOverlay();
     await tick();
+    if (!stageEl || !overlayEl) return;
-    Object.assign(tileEl.style, {
-      position: 'fixed',
+    const target = viewportTarget();
+    Object.assign(stageEl.style, {
       top: `${start.top}px`,
       left: `${start.left}px`,
       width: `${start.width}px`,
       height: `${start.height}px`,
-      zIndex: 'var(--z-modal)',
     });
-    tileEl.animate(
+    stageEl.animate(
       [
         { top: `${start.top}px`, left: `${start.left}px`, width: `${start.width}px`, height: `${start.height}px` },
         { top: `${target.top}px`, left: `${target.left}px`, width: `${target.width}px`, height: `${target.height}px` },
       ],
-      { duration: TRANSITION_MS, easing: TRANSITION_EASE, fill: 'forwards' },
+      { duration: dur(), easing: TRANSITION_EASE, fill: 'forwards' },
     );
     overlayEl.animate([{ opacity: 0 }, { opacity: 1 }], {
-      duration: TRANSITION_MS,
+      duration: dur(),
       easing: TRANSITION_EASE,
       fill: 'forwards',
     });
+    fadeChrome(true);
     if (extended) {
       toolbarEl?.animate([{ opacity: 0, transform: 'translate(-50%, 16px)' }, { opacity: 1, transform: 'translate(-50%, 0)' }], {
-        duration: TRANSITION_MS,
+        duration: dur(),
         easing: TRANSITION_EASE,
         fill: 'forwards',
         delay: 80,
       });
-      closeBtnEl?.animate([{ opacity: 0 }, { opacity: 1 }], {
-        duration: TRANSITION_MS,
+    }
+    // Move focus into the modal so keyboard users land inside the dialog; the
+    // stage (tabindex -1) is the fallback when there is no chrome to focus.
+    (closeBtnEl ?? stageEl)?.focus();
+  }
+  // Close button, gallery chevrons, and counter all share a plain opacity fade;
+  // the zoom toolbar keeps its bespoke slide so it's handled separately.
+  function chromeFadeEls(): HTMLElement[] {
+    const els: (HTMLElement | undefined)[] = [];
+    if (extended || isGallery) els.push(closeBtnEl);
+    if (isGallery) els.push(prevBtnEl, nextBtnEl, counterEl);
+    return els.filter((el): el is HTMLElement => !!el);
+  }
+  function fadeChrome(showing: boolean) {
+    for (const el of chromeFadeEls()) {
+      el.animate([{ opacity: showing ? 0 : 1 }, { opacity: showing ? 1 : 0 }], {
+        duration: dur(),
         easing: TRANSITION_EASE,
         fill: 'forwards',
-        delay: 80,
+        delay: showing ? 80 : 0,
       });
     }
   }
   function closeLightbox() {
-    if (!open || !tileEl || !wrapperEl) return;
+    if (!open || !stageEl || !thumbEl || !overlayEl) return;
     cancelAnimations();
-    const target = wrapperEl.getBoundingClientRect();
-    const current = tileEl.getBoundingClientRect();
+    const target = thumbEl.getBoundingClientRect();
+    const from = stageEl.getBoundingClientRect();
-    const anim = tileEl.animate(
+    const anim = stageEl.animate(
       [
-        { top: `${current.top}px`, left: `${current.left}px`, width: `${current.width}px`, height: `${current.height}px` },
+        { top: `${from.top}px`, left: `${from.left}px`, width: `${from.width}px`, height: `${from.height}px` },
         { top: `${target.top}px`, left: `${target.left}px`, width: `${target.width}px`, height: `${target.height}px` },
       ],
-      { duration: TRANSITION_MS, easing: TRANSITION_EASE, fill: 'forwards' },
+      { duration: dur(), easing: TRANSITION_EASE, fill: 'forwards' },
     );
     overlayEl.animate([{ opacity: 1 }, { opacity: 0 }], {
-      duration: TRANSITION_MS,
+      duration: dur(),
       easing: TRANSITION_EASE,
       fill: 'forwards',
     });
+    fadeChrome(false);
     if (extended) {
       toolbarEl?.animate([{ opacity: 1 }, { opacity: 0 }], {
-        duration: TRANSITION_MS,
-        easing: TRANSITION_EASE,
-        fill: 'forwards',
-      });
-      closeBtnEl?.animate([{ opacity: 1 }, { opacity: 0 }], {
-        duration: TRANSITION_MS,
+        duration: dur(),
         easing: TRANSITION_EASE,
         fill: 'forwards',
       });
     }
     anim.onfinish = () => {
-      cancelAnimations();
-      tileEl.style.cssText = '';
-      transformEl.style.transform = '';
       scale = 1;
       offset = { x: 0, y: 0 };
+      index = 0;
       open = false;
+      mounted = false;
       document.body.style.overflow = '';
       restoreEditorOverlay();
+      thumbEl?.focus();
     };
   }
+  // Re-fit the open modal to the viewport — used on resize (snap) and when the
+  // gallery image or its measured aspect changes (animated morph).
+  function fitToViewport(animate: boolean) {
+    if (!open || !stageEl) return;
+    const target = viewportTarget();
+    if (animate) {
+      const from = stageEl.getBoundingClientRect();
+      for (const a of stageEl.getAnimations()) {
+        try { a.commitStyles(); } catch {}
+        a.cancel();
+      }
+      stageEl.animate(
+        [
+          { top: `${from.top}px`, left: `${from.left}px`, width: `${from.width}px`, height: `${from.height}px` },
+          { top: `${target.top}px`, left: `${target.left}px`, width: `${target.width}px`, height: `${target.height}px` },
+        ],
+        { duration: dur(), easing: TRANSITION_EASE, fill: 'forwards' },
+      );
+    } else {
+      Object.assign(stageEl.style, {
+        top: `${target.top}px`,
+        left: `${target.left}px`,
+        width: `${target.width}px`,
+        height: `${target.height}px`,
+      });
+    }
+    offset = clampOffset(offset.x, offset.y, scale);
+    applyTransform(scale, offset);
+  }
+  function settleNav() {
+    incomingEl?.getAnimations().forEach((a) => a.cancel());
+    outgoingEl?.getAnimations().forEach((a) => a.cancel());
+    outgoing = null;
+    navigating = false;
+  }
+  // dir: +1 when paging via the right chevron (content exits left, the next
+  // image enters from the right), -1 for the left chevron.
+  async function goTo(target: number, dir: number) {
+    if (!isGallery) return;
+    const n = ((target % items.length) + items.length) % items.length;
+    if (n === index) return;
+    if (navigating) settleNav();
+    scale = 1;
+    offset = { x: 0, y: 0 };
+    applyTransform(scale, offset);
+    outgoing = current;
+    index = n;
+    navigating = true;
+    await tick();
+    const exit = -NAV_SHIFT_PX * dir;
+    outgoingEl?.animate(
+      [
+        { transform: 'translateX(0) scale(1)', opacity: 1 },
+        { transform: `translateX(${exit}px) scale(${NAV_SCALE})`, opacity: 0 },
+      ],
+      { duration: dur(NAV_MS), easing: EASE_IN, fill: 'forwards' },
+    );
+    const enter = incomingEl?.animate(
+      [
+        { transform: `translateX(${-exit}px) scale(${NAV_SCALE})`, opacity: 0 },
+        { transform: 'translateX(0) scale(1)', opacity: 1 },
+      ],
+      // `fill: both` holds the opacity-0 start state through the stagger delay,
+      // otherwise the incoming image flashes at full opacity before sliding in.
+      { duration: dur(NAV_MS), easing: EASE_OUT, fill: 'both', delay: dur(NAV_STAGGER_MS) },
+    );
+    fitToViewport(true); // resize the stage if the incoming aspect differs; a no-op when it matches
+    if (enter) enter.onfinish = settleNav;
+    else settleNav();
+  }
+  const next = () => goTo(index + 1, 1);
+  const prev = () => goTo(index - 1, -1);
+  function record(src: string, e: Event) {
+    const img = e.currentTarget as HTMLImageElement;
+    if (img.naturalWidth && img.naturalHeight) measured[src] = img.naturalWidth / img.naturalHeight;
+  }
+  function onCoverLoad(e: Event) {
+    if (cover) record(cover.src, e);
+  }
+  function onImgLoad(e: Event) {
+    if (current) record(current.src, e);
+    if (open) fitToViewport(true);
+  }
+  $effect(() => {
+    if (!isGallery || typeof Image === 'undefined') return;
+    for (const d of [index + 1, index - 1]) {
+      const it = items[((d % items.length) + items.length) % items.length];
+      if (it) new Image().src = it.src;
+    }
+  });
   function zoomTo(nextScale: number, anchor?: { x: number; y: number }) {
     const s = Math.max(MIN_SCALE, Math.min(MAX_SCALE, nextScale));
     if (s <= MIN_SCALE) {
@@ -216,18 +403,18 @@
       applyTransform(scale, offset);
       return;
     }
-    let next: { x: number; y: number };
-    if (anchor && tileEl) {
-      const r = tileEl.getBoundingClientRect();
+    let nextOffset: { x: number; y: number };
+    if (anchor && stageEl) {
+      const r = stageEl.getBoundingClientRect();
       const dx = anchor.x - (r.left + r.width / 2);
       const dy = anchor.y - (r.top + r.height / 2);
       const ratio = scale > 0 ? s / scale : 1;
-      next = clampOffset(dx * (1 - ratio) + offset.x * ratio, dy * (1 - ratio) + offset.y * ratio, s);
+      nextOffset = clampOffset(dx * (1 - ratio) + offset.x * ratio, dy * (1 - ratio) + offset.y * ratio, s);
     } else {
-      next = clampOffset(offset.x, offset.y, s);
+      nextOffset = clampOffset(offset.x, offset.y, s);
     }
     scale = s;
-    offset = next;
+    offset = nextOffset;
     applyTransform(scale, offset);
   }
@@ -267,44 +454,63 @@
     }
   }
-  function onTileClick() {
+  function onStageClick() {
     if (didDrag) {
       didDrag = false;
       return;
     }
-    if (!open) {
-      openLightbox();
-    } else if (!extended) {
-      closeLightbox();
-    }
+    if (!extended && !isGallery) closeLightbox();
   }
-  function onTileKeyDown(e: KeyboardEvent) {
-    if (e.key === 'Enter' || e.code === 'Space') {
+  // Keep Tab inside the open dialog. The stage (tabindex -1) is excluded, so an
+  // image-only lightbox with no chrome simply holds focus on the stage.
+  function trapTab(e: KeyboardEvent) {
+    if (!modalEl) return;
+    const f = [
+      ...modalEl.querySelectorAll<HTMLElement>('button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])'),
+    ];
+    if (f.length === 0) {
+      e.preventDefault();
+      stageEl?.focus();
+      return;
+    }
+    const first = f[0];
+    const last = f[f.length - 1];
+    const active = document.activeElement as HTMLElement | null;
+    const inside = active && modalEl.contains(active);
+    if (e.shiftKey && (!inside || active === first)) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && (!inside || active === last)) {
       e.preventDefault();
-      onTileClick();
+      first.focus();
     }
   }
   onMount(() => {
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape' && open) closeLightbox();
-    };
-    const onResize = () => {
-      if (!open || !tileEl) return;
-      const target = viewportTarget();
-      Object.assign(tileEl.style, {
-        top: `${target.top}px`,
-        left: `${target.left}px`,
-        width: `${target.width}px`,
-        height: `${target.height}px`,
-      });
-      offset = clampOffset(offset.x, offset.y, scale);
-      applyTransform(scale, offset);
+      if (!open) return;
+      if (e.key === 'Escape') {
+        closeLightbox();
+      } else if (e.key === 'Tab') {
+        trapTab(e);
+      } else if (isGallery && e.key === 'ArrowRight') {
+        e.preventDefault();
+        next();
+      } else if (isGallery && e.key === 'ArrowLeft') {
+        e.preventDefault();
+        prev();
+      }
     };
+    const onResize = () => fitToViewport(false);
+    const motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+    reducedMotion = motionQuery.matches;
+    const onMotionChange = (e: MediaQueryListEvent) => { reducedMotion = e.matches; };
+    motionQuery.addEventListener('change', onMotionChange);
     document.addEventListener('keydown', onKey);
     window.addEventListener('resize', onResize);
     return () => {
+      motionQuery.removeEventListener('change', onMotionChange);
       document.removeEventListener('keydown', onKey);
       window.removeEventListener('resize', onResize);
       document.body.style.overflow = '';
@@ -316,97 +522,151 @@
 </script>
 <div
-  bind:this={wrapperEl}
   class="image-lightbox-wrapper"
-  style:aspect-ratio={aspect ? `${width} / ${height}` : undefined}
+  style:aspect-ratio={coverAspect ? `${coverAspect}` : undefined}
   style:max-width={typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth}
 >
-  <div
-    bind:this={tileEl}
-    class="image-lightbox-tile"
-    class:open
-    role="button"
-    tabindex="0"
-    aria-label={open ? `Close image: ${alt}` : `Expand image: ${alt}`}
-    onclick={onTileClick}
-    onkeydown={onTileKeyDown}
-    onpointerdown={onPointerDown}
-    onpointermove={onPointerMove}
-    onpointerup={onPointerUp}
-    onpointercancel={onPointerUp}
-    onwheel={onWheel}
-  >
-    <div class="image-lightbox-clip">
-      <div bind:this={transformEl} class="image-lightbox-transform">
-        <img {src} {alt} draggable="false" />
-      </div>
-    </div>
-  </div>
-</div>
-<div
-  bind:this={overlayEl}
-  class="image-lightbox-overlay"
-  class:active={open}
-  aria-hidden="true"
-  onclick={closeLightbox}
-  role="presentation"
-></div>
-{#if extended}
   <button
-    bind:this={closeBtnEl}
-    class="image-lightbox-chrome image-lightbox-close"
-    class:active={open}
+    bind:this={thumbEl}
+    class="image-lightbox-thumb"
+    style:--imagelightbox-tile-object-fit={fit}
     type="button"
-    aria-label="Close"
-    onclick={closeLightbox}
+    aria-label={cover?.alt ? `Expand image: ${cover.alt}` : 'Expand image'}
+    onclick={openLightbox}
   >
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-      <path d="M18 6L6 18" />
-      <path d="M6 6l12 12" />
-    </svg>
+    <img src={cover?.src} alt={cover?.alt} draggable="false" onload={onCoverLoad} />
   </button>
+</div>
+{#if mounted}
   <div
-    bind:this={toolbarEl}
-    class="image-lightbox-toolbar"
-    class:active={open}
+    bind:this={modalEl}
+    class="image-lightbox-modal"
+    role="dialog"
+    aria-modal="true"
+    aria-label={dialogLabel}
+    use:portal
   >
-    <button
-      class="image-lightbox-chrome-button"
-      type="button"
-      aria-label="Zoom out"
-      disabled={scale <= MIN_SCALE + 0.001}
-      onclick={() => zoomTo(scale / ZOOM_STEP)}
+    <div
+      bind:this={overlayEl}
+      class="image-lightbox-overlay"
+      class:active={open}
+      aria-hidden="true"
+      onclick={closeLightbox}
+      role="presentation"
+    ></div>
+    {#if isGallery}
+      <div class="image-lightbox-sr" aria-live="polite">{`Image ${index + 1} of ${items.length}`}</div>
+    {/if}
+    <div
+      bind:this={stageEl}
+      class="image-lightbox-stage"
+      role="presentation"
+      tabindex="-1"
+      onclick={onStageClick}
+      onpointerdown={onPointerDown}
+      onpointermove={onPointerMove}
+      onpointerup={onPointerUp}
+      onpointercancel={onPointerUp}
+      onwheel={onWheel}
     >
-      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-        <path d="M5 12h14" />
-      </svg>
-    </button>
-    <span class="image-lightbox-toolbar-label">{percentLabel}</span>
-    <button
-      class="image-lightbox-chrome-button"
-      type="button"
-      aria-label="Zoom in"
-      disabled={scale >= MAX_SCALE - 0.001}
-      onclick={() => zoomTo(scale * ZOOM_STEP)}
-    >
-      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-        <path d="M12 5v14" />
-        <path d="M5 12h14" />
-      </svg>
-    </button>
+      <div class="image-lightbox-clip">
+        <div bind:this={transformEl} class="image-lightbox-transform">
+          {#if outgoing}
+            <img bind:this={outgoingEl} class="image-lightbox-layer image-lightbox-layer-exit" src={outgoing.src} alt="" draggable="false" />
+          {/if}
+          <img bind:this={incomingEl} class="image-lightbox-layer" src={current?.src} alt={current?.alt} draggable="false" onload={onImgLoad} />
+        </div>
+      </div>
+    </div>
+    {#if extended || isGallery}
+      <button
+        bind:this={closeBtnEl}
+        class="image-lightbox-chrome image-lightbox-close"
+        class:active={open}
+        type="button"
+        aria-label="Close"
+        onclick={closeLightbox}
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <path d="M18 6L6 18" />
+          <path d="M6 6l12 12" />
+        </svg>
+      </button>
+    {/if}
+    {#if isGallery}
+      <button
+        bind:this={prevBtnEl}
+        class="image-lightbox-chrome image-lightbox-nav image-lightbox-nav-prev"
+        class:active={open}
+        type="button"
+        aria-label="Previous image"
+        onclick={prev}
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <path d="M15 18l-6-6 6-6" />
+        </svg>
+      </button>
+      <button
+        bind:this={nextBtnEl}
+        class="image-lightbox-chrome image-lightbox-nav image-lightbox-nav-next"
+        class:active={open}
+        type="button"
+        aria-label="Next image"
+        onclick={next}
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <path d="M9 6l6 6-6 6" />
+        </svg>
+      </button>
+      <div bind:this={counterEl} class="image-lightbox-counter" aria-hidden="true">
+        {index + 1} / {items.length}
+      </div>
+    {/if}
+    {#if extended}
+      <div bind:this={toolbarEl} class="image-lightbox-toolbar" class:active={open}>
+        <button
+          class="image-lightbox-chrome-button"
+          type="button"
+          aria-label="Zoom out"
+          disabled={scale <= MIN_SCALE + 0.001}
+          onclick={() => zoomTo(scale / ZOOM_STEP)}
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M5 12h14" />
+          </svg>
+        </button>
+        <span class="image-lightbox-toolbar-label">{percentLabel}</span>
+        <button
+          class="image-lightbox-chrome-button"
+          type="button"
+          aria-label="Zoom in"
+          disabled={scale >= MAX_SCALE - 0.001}
+          onclick={() => zoomTo(scale * ZOOM_STEP)}
+        >
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="M12 5v14" />
+            <path d="M5 12h14" />
+          </svg>
+        </button>
+      </div>
+    {/if}
   </div>
 {/if}
 <style>
   :global(:root) {
-    /* tile (closed inline + animated modal surface) */
+    /* thumbnail (closed inline) + animated modal stage */
     --imagelightbox-tile-radius:           var(--radius-2xl);
     --imagelightbox-tile-border:           var(--color-transparent);
     --imagelightbox-tile-border-width:     var(--border-width-0);
     --imagelightbox-tile-shadow:           var(--shadow-md);
+    --imagelightbox-tile-object-fit:       contain;
     /* overlay */
     --imagelightbox-overlay-surface:       color-mix(in srgb, var(--color-neutral-950) 76%, transparent);
@@ -425,31 +685,63 @@
     width: 100%;
   }
-  .image-lightbox-tile {
+  .image-lightbox-thumb {
     position: absolute;
     inset: 0;
+    padding: 0;
     cursor: zoom-in;
     border: var(--imagelightbox-tile-border-width) solid var(--imagelightbox-tile-border);
     border-radius: var(--imagelightbox-tile-radius);
     box-shadow: var(--imagelightbox-tile-shadow);
     background: transparent;
-    overflow: visible;
+    overflow: hidden;
     transition: transform 250ms ease;
   }
-  .image-lightbox-tile:hover:not(.open) {
+  .image-lightbox-thumb:hover {
     transform: scale(1.02);
   }
-  .image-lightbox-tile.open {
-    cursor: zoom-out;
-  }
-  .image-lightbox-tile:focus-visible {
+  .image-lightbox-thumb:focus-visible {
     outline: 2px solid var(--border-brand-medium);
     outline-offset: 2px;
   }
+  .image-lightbox-thumb img {
+    width: 100%;
+    height: 100%;
+    object-fit: var(--imagelightbox-tile-object-fit);
+    object-position: center;
+    user-select: none;
+    display: block;
+  }
+  .image-lightbox-modal {
+    display: contents;
+  }
+  .image-lightbox-sr {
+    position: fixed;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+    border: 0;
+  }
+  .image-lightbox-stage {
+    position: fixed;
+    z-index: var(--z-modal);
+    cursor: zoom-out;
+    border: var(--imagelightbox-tile-border-width) solid var(--imagelightbox-tile-border);
+    border-radius: var(--imagelightbox-tile-radius);
+    box-shadow: var(--imagelightbox-tile-shadow);
+    background: transparent;
+  }
   .image-lightbox-clip {
     position: absolute;
     inset: 0;
@@ -464,14 +756,26 @@
     transform-origin: center center;
   }
-  .image-lightbox-transform img {
+  .image-lightbox-layer {
+    position: absolute;
+    inset: 0;
     width: 100%;
     height: 100%;
     object-fit: contain;
     object-position: center;
+    transform-origin: center center;
     user-select: none;
     pointer-events: none;
     display: block;
+    /* Incoming layer sits above the exiting one so the new image fades in over
+       the old; own compositor layer keeps the crossfade from flickering. */
+    z-index: 1;
+    will-change: transform, opacity;
+    backface-visibility: hidden;
+  }
+  .image-lightbox-layer-exit {
+    z-index: 0;
   }
   .image-lightbox-overlay {
@@ -509,6 +813,7 @@
   .image-lightbox-close {
     top: var(--space-24);
     right: var(--space-24);
+    /* 2.75rem = 44px, the min touch-target floor for primary nav. */
     width: 2.75rem;
     height: 2.75rem;
     display: flex;
@@ -521,6 +826,48 @@
     background: var(--imagelightbox-chrome-hover-surface);
   }
+  .image-lightbox-nav {
+    top: 50%;
+    transform: translateY(-50%);
+    /* 2.75rem = 44px, the min touch-target floor for primary nav. */
+    width: 2.75rem;
+    height: 2.75rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+  }
+  .image-lightbox-nav-prev {
+    left: var(--space-24);
+  }
+  .image-lightbox-nav-next {
+    right: var(--space-24);
+  }
+  .image-lightbox-nav:hover {
+    background: var(--imagelightbox-chrome-hover-surface);
+  }
+  .image-lightbox-counter {
+    position: fixed;
+    right: var(--space-24);
+    bottom: var(--space-24);
+    z-index: var(--z-modal);
+    padding: var(--space-8) var(--space-16);
+    background: var(--imagelightbox-chrome-surface);
+    border: var(--imagelightbox-chrome-border-width) solid var(--imagelightbox-chrome-border);
+    border-radius: var(--imagelightbox-chrome-radius);
+    color: var(--imagelightbox-chrome-icon);
+    backdrop-filter: blur(var(--blur-md));
+    font-family: var(--font-mono);
+    font-size: var(--font-size-xs);
+    letter-spacing: var(--letter-spacing-wider);
+    opacity: 0;
+    pointer-events: none;
+  }
   .image-lightbox-toolbar {
     position: fixed;
     left: 50%;

package/src/system/internal/portal.ts ADDED Viewed

@@ -0,0 +1,18 @@
+// Move a `position: fixed` overlay to <body> so it escapes any transformed /
+// `isolation` / `contain` / scrolling ancestor that would otherwise clip it or
+// trap its stacking order (the editor's `.content` pane is one such ancestor;
+// consumer pages have countless others). Every shipped component that renders a
+// fixed overlay uses this — see check-overlay-portal.
+//
+// `enabled` is read once, at mount: pass `false` to leave the node in flow
+// (Dialog's `inline` preview). It is intentionally not reactive — every consumer
+// sets it statically, so there is no move-it-back path to get wrong.
+export function portal(node: HTMLElement, enabled = true) {
+  if (enabled) document.body.appendChild(node);
+  return {
+    destroy() {
+      if (enabled) node.remove();
+    },
+  };
+}

package/src/system/styles/tokens.css CHANGED Viewed

@@ -415,15 +415,6 @@
   --border-width-20: 20px;
   --border-width-24: 24px;
-  /* Icon sizing (square) */
-  --size-icon-sm: 1rem;     /* 16px */
-  --size-icon-md: 1.25rem;  /* 20px */
-  --size-icon-lg: 1.5rem;   /* 24px */
-  --size-icon-xl: 2rem;     /* 32px */
-  --size-icon-2xl: 4rem;    /* 64px */
-  --size-icon-3xl: 6rem;    /* 96px */
-  --size-icon-4xl: 8rem;    /* 128px */
   /* Spacing */
   --space-0: 0;
   --space-2: 0.125rem;    /* 2px */