@noxlovette/material 0.6.1 → 0.7.0

package/claude-skill/material-design/SKILL.md

@@ -52,11 +52,14 @@ This repo is a single, already-opinionated M3 component library, not a blank can
 
 - Color tokens: `md-sys-color-{primary,secondary,tertiary,error}`, each with a `-container` tonal pair and `on-*` text/icon pair (guarantees AA contrast by construction).
 - Type: `md-sys-typescale-{display,headline,title,body,label}-{large,medium,small}`, plus `md-sys-typescale-emphasized-*` for selected/active/unread states.
-- Spacing: `*-spacing-{0,25,50,75,100,…,900}` (M3 `md.sys.measurement.space*`, 8dp base: `p-spacing-200` = 16dp).
+- Spacing: `*-spacing-{0,25,50,75,100,…,900}` (M3 `md.sys.measurement.space*`, 8dp base: `p-spacing-200` = 16dp). Off-grid component dimensions: `--md-comp-*` in `styles/components.css`, used as `w-(--md-comp-…)`.
+- Surfaces: the window (`App`, rail, navbar, nav lists) is `surface-container`; content sits in `surface` panes (`Pane`'s default). A viewport `Rail` publishes `--md-rail-inset`, which `App` and `AppBar` already use; never offset a page by hand (`md:ml-24`).
+- `tv` and `twMerge` come from `$lib/utils/tv.js`, never `tailwind-variants`/`tailwind-merge` directly.
 - Elevation: `shadow-elevation-{0..5}`.
 - Shape: `radius-{none,xs,sm,md,lg,xl,full}` (buttons instead drive shape via the `--btn-shape`/`--btn-pressed-shape` CSS vars in `.md-btn-morph`).
+- Icons: `Icon.svelte` with a typed `name`. Selected state is `fill={1}`. A control whose icon swaps with its state passes `transition: 'rotate'` (toggles) or `'fade'`. See motion-guide.md → "Icon swaps".
 - Expressive shapes (circle, cookie, sunny, heart…): `animatableShapes`/`animatableShapesSmall` + `shapeMorph` for morphs. See motion-guide.md → "Shape morphing".
-- Motion: M3 Expressive springs only (`springTokens` in `animation/spring.ts`). JS: `presence`/`Presence` + `enterExit` presets, `containerTransform`, `sharedAxis`, `lateral`, `fadeThrough`, `skeleton` — all on Motion, never Svelte transitions. CSS: `transition-* md-sys-motion-{fast-spatial,spatial,slow-spatial,fast-effects,effects,slow-effects}` utilities, never `duration-*`/`ease-*`.
+- Motion: M3 Expressive springs only (`springTokens` in `animation/spring.ts`). Dragging: the `drag()` attachment + `resist()`. Several parts changing together: one progress spring in a CSS variable (the rail's `--rail-p`). JS: `presence`/`Presence` + `enterExit` presets, `containerTransform`, `sharedAxis`, `lateral`, `fadeThrough`, `skeleton` — all on Motion, never Svelte transitions. CSS: `transition-* md-sys-motion-{fast-spatial,spatial,slow-spatial,fast-effects,effects,slow-effects}` utilities, never `duration-*`/`ease-*`.
 - Transition pattern choice: appearing on this screen → enter/exit. Hero expands into its detail → container transform (only in shallow hierarchies). Parent/child or sequential steps → forward/backward (`sharedAxis`). Peers in one set → lateral, which never fades. Navbar/rail/drawer destinations → top level (`fadeThrough`), never lateral. Never use enter/exit or lateral for hierarchical navigation. Sheets slide without fading. Don't use bouncy (`fastSpatial`) springs for navigation transitions.
 - Shared primitives: wrap interactive surfaces with `Layer.svelte` (state layer + ripple, already skips itself under `prefers-reduced-motion`), render icons with `Icon.svelte`, use `Divider.svelte` instead of Bits UI's `Separator`.
 

package/claude-skill/material-design/references/accessibility-checklist.md

@@ -11,9 +11,14 @@ Run through this before calling a component/UI change done.
 
 - Interactive elements should hit the M3 minimum 48dp target. The existing `size` scales already encode this (e.g. button `sm`/`md` = `h-spacing-500`/`h-spacing-700`); when adding a new interactive size below that, either pad the hit area (see `.text-link`'s `min-height: 44px` + padding trick) or confirm it's genuinely dense-UI/desktop-only and document why.
 
+- A target can be larger than what's drawn: a rail destination's link spans the rail's full width while its indicator hugs the icon; a chip's 18dp trailing icon gets a 48dp `::after` target. Draw state layers and focus rings on the visible element, triggered by the whole target (`group-hover:`, `group-focus-visible:`).
+
 ## Focus
 
 - Anything focusable needs a visible focus state — use `md-sys-state-focus-indicator`, don't rely on the browser default or remove `outline` without replacing it.
+- Every drag has a keyboard equivalent and an announcement: `ChipGroup` reorders on Alt+Arrow and reports "X, moved to N of M" in an `aria-live` region, with the instructions in an `aria-describedby` hint.
+- Toggles report their state (`aria-expanded` on the rail's menu button); a modal surface closes on Escape and a scrim click (the modal rail also closes when a destination is picked); removable items remove on Backspace/Delete (input chips).
+- Icons are decorative (`aria-hidden`) by default. Give `Icon` an `aria-label` only when it carries meaning with no visible text beside it; it then takes `role="img"`.
 - Verify keyboard operability, not just click handlers — Bits UI primitives (dialogs, menus, selects) handle this by default; if you're building something interactive from scratch, check it against Bits UI's docs (https://bits-ui.com/llms.txt) for the expected keyboard model first.
 
 ## Motion

package/claude-skill/material-design/references/component-patterns.md

@@ -2,7 +2,7 @@
 
 ## The `tv()` shape
 
-Every component's styles live in the category's `theme.ts`, built with `tv()` from `tailwind-variants`:
+Every component's styles live in the category's `theme.ts`, built with `tv()`. Import it from `$lib/utils/tv.js`, not `tailwind-variants`: that instance teaches tailwind-merge the library's own class groups, so a caller's `z-40` replaces a `z-layer-*` and `size-[18px]`/`p-4` replaces `size-spacing-250`/`p-spacing-200` instead of both shipping. For a class list built outside `tv()`, use the `twMerge` exported from the same file.
 
 - `slots` — one key per rendered element (`base`, `icon`, `label`, ...) so multi-element components can vary each part independently
 - `variants` — one axis per meaningful design decision (`variant`, `color`, `size`, `shape`, `selected`, ...); each value maps to either a class string (single-slot components) or an object keyed by slot (multi-slot components)
@@ -26,8 +26,15 @@ Only fall back to `bare` (no color/background at all) when the component supplie
 
 ## Reuse before you build
 
-- **State layer / ripple** — wrap the interactive element with `Layer.svelte` (`src/lib/utils/Layer.svelte`) rather than writing hover/press opacity by hand. It listens for `.m3-layer` on its parent, already respects `prefers-reduced-motion` for the ripple, and its tint intensity (hover 0.08 / pressed·focus 0.12) matches the M3 state-layer spec — don't retune those numbers per component.
-- **Icons** — always `Icon.svelte` (`name`, `fill`, `wght`, `size` props), never a raw `<span class="material-symbols-...">` or an inline SVG for a Material Symbol.
+- **State layer / ripple** — wrap the interactive element with `Layer.svelte` (`src/lib/utils/Layer.svelte`) rather than writing hover/press opacity by hand. It listens for `.m3-layer` on its parent, already respects `prefers-reduced-motion` for the ripple, and its tint (hover 0.08, focus and pressed 0.10) matches the M3 state-layer tokens — don't retune those numbers per component.
+- **Icons** — always `Icon.svelte`, never a raw `<span class="material-symbols-...">` or an inline SVG for a Material Symbol.
+  - `name` is typed (`MaterialSymbolName`), so a typo is a type error. A `string[]` of names needs `as const` or `satisfies MaterialSymbolName[]`.
+  - Show state with `fill` (0 → 1 on the selected item; it animates), not a weight change.
+  - `size="inline"` for a symbol set in running text. `grad` defaults to `'auto'` (-25 on dark schemes).
+  - When a control's icon swaps between two states (menu ↔ menu_open, add ↔ close, play ↔ pause), pass `transition: 'rotate'` (a toggle) or `'fade'`. Otherwise the glyph jumps. See motion-guide.md → "Icon swaps".
+- **Dragging** — the `drag()` attachment (`$lib/attachments`), never hand-rolled pointer events. It handles pointer capture (and recapture when the node moves in the DOM), a start `threshold`, a touch long-press `touchDelay` so swipes still scroll, the release velocity, and swallowing the click after a drag. Pair it with `resist()` for rubber-banding at the bounds and a Motion spring on release that takes the velocity. `DraggablePane` and `ChipGroup` are built on it.
+- **Sets of chips** — `ChipGroup` (8dp gaps, wrapping; `reorderable` adds drag and Alt+Arrow reordering with the M3 dragged state), not a flex row of `Chip`s. An input chip is two buttons (its action, and a remove button with a `removeLabel`) and removes on Backspace/Delete; a filter chip takes `trailingIconProps` (e.g. a dropdown arrow).
+- **Lists** — `List`'s `variant` depends on what's behind it. `standard` items are `surface` and assume a `surface` backdrop (a `surface` pane). On the `surface-container` window (a sidebar nav on a backgroundless pane), use `segmented`: its segments take the window's tone, so only the selected pill and hover tint show. A standard list there renders as notched white slabs. The selected fill is its own element (`selection` slot), not the item's background, so it can travel between items; keep it that way when restyling selection.
 - **Dividers** — `Divider.svelte`, not Bits UI's `Separator` (per project CLAUDE.md — it already implements the same primitive).
 - **Focus ring** — the `md-sys-state-focus-indicator` utility, not a custom `:focus` style.
 - **Disabled state** — `.md-component-button-base`'s disabled handling (via `disabled:`/`aria-disabled`/`data-disabled` selectors in `component.css`), not a manually-toggled opacity class.
@@ -50,6 +57,20 @@ in the library, not in a one-off route file:
 
 See `/docs/pane` in the showcase site for the full prop reference and worked examples.
 
+### Surfaces: window vs panes
+
+`App` paints the window `surface-container`; content lives in `surface` panes (`Pane`'s default `background`, rounded top corners). Navigation belongs to the window, not a pane: the `Rail` (on `surface-container`, the spec's optional role), a `Navbar`, a guides-style nav list on a `background={false}` pane. So keep the content `Pane` at its default background, and don't separate a nav column from the content with a border: the colour change does it.
+
+### Page ends and overscroll
+
+- **End space:** a `full` Pane (the default, a page that scrolls with the window) ends its content 72dp above its bottom edge, whatever its `padding` preset (not with `padding="none"`). That's a 56dp FAB plus its 16dp margin, so the last line scrolls clear of a FAB and doesn't finish flush against the window. Don't add bottom padding by hand on top of it.
+- **Overscroll:** a page with an `App` doesn't bounce or pull-to-refresh (`overscroll-behavior: none` on `:root:has(.md-app)`, base layer), and its canvas is `surface-container`. An app that wants pull-to-refresh sets `html { overscroll-behavior: auto }`.
+- **Pane basis follows the grid:** inside a `PaneGrid`, a Pane's `flex-basis` is its width in a row and `auto` in a column (each direction tier restates it), so stacked panes take their content height. Don't set `basis-*` on a Pane yourself.
+
+### Clearing the rail
+
+A viewport-anchored `Rail` publishes `--md-rail-inset` on `<html>`: 0 below `md`, the collapsed 96dp on medium windows (the expanded rail is modal there and overlays), and its live width from `lg` (it pushes content, in step with its spring). `App`'s shell pads by it and `AppBar` starts at it. Never add `md:ml-24` or similar to a page, a `PaneGrid` or an app bar. A custom shell uses `ps-(--md-rail-inset)`; another fixed surface spanning the window uses `left-(--md-rail-inset)`. A rail with `anchor="parent"` renders a spacer beside itself instead, so it and its content go in a flex row.
+
 ## Before exporting a new component
 
 Follow CLAUDE.md's "Adding a New Component" steps as the mechanical checklist (create `.svelte` + `types.ts`, define `theme.ts` with `tv()`, export from the category `index.ts`, run `bun scripts/generate-components-index.ts`, add a showcase route and a docs page) — this skill governs the _design_ decisions (which variant/color/motion) that should be made before or while writing that `theme.ts`, not the export mechanics themselves.

package/claude-skill/material-design/references/motion-guide.md

@@ -54,16 +54,18 @@ Spatial springs overshoot by design (fast spatial most, at damping ratio 0.6); e
 
 ## JS: picking a primitive
 
-| M3 pattern                                                        | Primitive                                                    | Notes                                                                                                                                                                                                                                                                                              |
-| ----------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Enter and exit** — a surface appears/leaves within the screen   | `presence(() => open, enterExit.<preset>)`                   | Attachment. Presets: `fade`, `scale` (menus/popovers/tooltips — sets `transform-origin` to bits-ui's anchor side, so never add an `origin-*` class), `slideUp` (snackbar), `dialog`, `sideSheet`, `bottomSheet`. Interruptible: reopening mid-exit retargets from the current value with velocity. |
-| Same, outside bits-ui (element must stay mounted during its exit) | `new Presence(() => open)`                                   | `{#if p.mounted}<div {@attach p.attach(enterExit.x)}>`. Construct during component init. Used by Snackbar, SideSheet, BottomSheet.                                                                                                                                                                 |
-| **Container transform** — card → detail, FAB → sheet              | `containerTransform(update, { from, to })`                   | Motion `animateView()` (View Transition API). `update` swaps the DOM (`async () => { open = true; await tick(); }`); `to` may be a selector for an element that only exists after the update.                                                                                                      |
-| **Forward and backward** — hierarchy levels, wizard steps         | `sharedAxis(update, { target, axis, direction })`            | `axis: 'x' \| 'y' \| 'z'`, `direction: 'forward' \| 'backward'`. `target` is the persistent region whose content changes; omit for the whole page.                                                                                                                                                 |
-| **Lateral** — peer screens (tabs, carousels)                      | `lateral(update, { target, direction })`                     | Edge-to-edge slide, no fade.                                                                                                                                                                                                                                                                       |
-| **Top level** — unrelated destinations (navigation bar)           | `fadeThrough(update, { target })`                            | Old fades out, new fades in scaling from 92%.                                                                                                                                                                                                                                                      |
-| **Skeleton loaders**                                              | `{@attach skeleton}` on the placeholder                      | Pulses until replaced; reveal the content with `presence(…, enterExit.fade)`.                                                                                                                                                                                                                      |
-| Anything custom                                                   | `animate(node, keyframes, springTransition(springTokens.x))` | `springTransition` converts a token to Motion's physics spring (`stiffness`/`damping`), which inherits velocity on interruption.                                                                                                                                                                   |
+| M3 pattern                                                        | Primitive                                                    | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Enter and exit** — a surface appears/leaves within the screen   | `presence(() => open, enterExit.<preset>)`                   | Attachment. Presets: `fade`, `scale` (menus/popovers/tooltips — sets `transform-origin` to bits-ui's anchor side, so never add an `origin-*` class), `slideUp` (snackbar), `dialog`, `sideSheet`, `bottomSheet`. Interruptible: reopening mid-exit retargets from the current value with velocity.                                                                                                                                              |
+| Same, outside bits-ui (element must stay mounted during its exit) | `new Presence(() => open)`                                   | `{#if p.mounted}<div {@attach p.attach(enterExit.x)}>`. Construct during component init. Used by Snackbar, SideSheet, BottomSheet.                                                                                                                                                                                                                                                                                                              |
+| **Container transform** — card → detail, FAB → sheet              | `containerTransform(update, { from, to })`                   | Motion `animateView()` (View Transition API). `update` swaps the DOM (`async () => { open = true; await tick(); }`); `to` may be a selector for an element that only exists after the update.                                                                                                                                                                                                                                                   |
+| **Forward and backward** — hierarchy levels, wizard steps         | `sharedAxis(update, { target, axis, direction })`            | `axis: 'x' \| 'y' \| 'z'`, `direction: 'forward' \| 'backward'`. `target` is the persistent region whose content changes; omit for the whole page.                                                                                                                                                                                                                                                                                              |
+| **Lateral** — peer screens (tabs, carousels)                      | `lateral(update, { target, direction, axis })`               | Edge-to-edge slide, no fade, along the axis the peers are laid out on: `axis: 'y'` for vertical tabs, a vertical carousel or a top-to-bottom stepper (`forward` = next, pushing up from below). Never on a vertical nav list: that's a drawer, so top level.                                                                                                                                                                                    |
+| **Top level** — unrelated destinations (navigation bar)           | `fadeThrough(update, { target })`                            | Old fades out, new fades in scaling from 92%. The `target` region swaps its box instantly (no slide or resize, so a scroll reset doesn't glide). In SvelteKit, call it from `onNavigate` in the root layout, skip hash-only changes, and fade only the region whose content changed: `main` between rail/navbar destinations, a section's content pane between pages of a nav that stays on screen (the showcase site's root layout does both). |
+| **Skeleton loaders**                                              | `{@attach skeleton}` on the placeholder                      | Pulses until replaced; reveal the content with `presence(…, enterExit.fade)`.                                                                                                                                                                                                                                                                                                                                                                   |
+| **Direct manipulation** — dragging a pane, reordering chips       | `drag()` attachment + `resist()` + a spring on release       | The attachment reports offsets and release velocity; the caller moves things. Release on `fastSpatial` with `velocity` so the throw carries (DraggablePane, ChipGroup). Neighbours making room play FLIP: measure, reorder, `flushSync()`, spring each from its old offset to 0.                                                                                                                                                                |
+| **Several parts moving as one state change** — rail expand        | One number spring written to a CSS variable                  | `animate(from, to, { ...spring, onUpdate })` writes the progress (`--rail-p`, 0–1) and every part interpolates on it in CSS `calc()`: widths, gaps, heights, positions. One spring keeps them in step and an interruption reverses them together. Things that must not be seen mid-change (the rail label's side and typescale) switch at the halfway point while faded out.                                                                    |
+| Anything custom                                                   | `animate(node, keyframes, springTransition(springTokens.x))` | `springTransition` converts a token to Motion's physics spring (`stiffness`/`damping`), which inherits velocity on interruption.                                                                                                                                                                                                                                                                                                                |
 
 ### Which components must use which pattern
 
@@ -115,8 +117,48 @@ Within a set, every path has the same point count, start point and winding, so M
 - **Morph with `shapeMorph(() => path)`** (attachment on a `<path>`) or `morphShape(pathEl, to)`. Both use `fastSpatial` by default, stop the previous morph and start from the shape on screen, and swap instantly under `prefers-reduced-motion`.
 - **Pick by name** with `animatableShapes[name]` / `animatableShapesSmall[name]` (`ShapeName`, `shapeNames`). A map pulls in its whole set, so import individual `pathAnimatable*` constants when bundle size matters.
 - `LoadingIndicator` morphs through seven of the small shapes (`LOADING_SHAPES`) on its own component spring.
+- `Avatar` takes any shape (`shape`, a clip path from the small set, morphing on change) and can turn it at a constant speed (`spin="clockwise" | "counterclockwise"`, one turn per 14s, off under reduced motion). Like the loading indicator's global rotation, a constant spin is linear, not a spring.
 - Live demo: Storybook → Motion/Shapes.
 
+## Icon swaps
+
+Material Symbols are font glyphs, so one icon can't morph its outline into another. When a
+control's icon changes with its state, `Icon`'s `transition` prop crossfades the two glyphs on
+springs instead of swapping them in one frame (presets in `utils/icon/swap.ts`, run through
+`presence`):
+
+- **`'rotate'`**: for a toggle between two states of one control: menu ↔ menu_open (the rail's
+  menu button), add ↔ close, expand ↔ collapse. The old glyph turns out the same way the new
+  one turns in, so the pair reads as one motion.
+- **`'fade'`**: scale and fade without turning, for swaps that aren't a toggle (play ↔ pause,
+  a status icon changing).
+- **`'none'`** (default): leave icons that change with data (list rows, table cells) on this,
+  or a whole list animates when its data reloads.
+
+```svelte
+<ButtonIcon iconProps={{ name: open ? 'menu_open' : 'menu', transition: 'rotate' }} … />
+```
+
+Movement is on `fastSpatial` (an icon is a small element), opacity on `fastEffects`, and a
+change back mid-flight retargets the leaving glyph instead of stacking a third. Under reduced
+motion both become a plain crossfade. Outlined ↔ filled for a selected state is `fill`, not a
+swap; it already animates through `font-variation-settings`. True path morphs between icons are
+issue #36.
+
+## Selection indicators
+
+A selection that moves between peers moves its indicator rather than blinking it out and in.
+
+- **Between items of one set** (a `List`'s selected fill, Tabs' bar): the indicator travels from
+  the old item to the new one. `ListItem` hands the outgoing fill's rect (relative to the `List`)
+  through the List context in `$effect.pre`, and the incoming item springs its own fill from
+  there in `$effect` on `spatial`, lifted above the items it crosses. Reuse that hand-off for
+  new selectable sets, not a list-level overlay: segment backgrounds would hide one.
+- **Appearing in place** (the rail's active indicator): it grows from its centre to its edges
+  and fades in on `fastSpatial`, and the deselected one shrinks back; the state layer stays on
+  top. RailItem drives a 0–1 spring into `--rail-sel`.
+- Under reduced motion both just appear at the end state.
+
 ## CSS: state-driven transitions
 
 For hover/press/selected/focus motion driven by pseudo-classes or `data-*` state, use a Tailwind transition-property utility plus one spring utility from `motion.css`:
@@ -158,6 +200,6 @@ Not implemented yet — tracked in https://github.com/noxlovette/material/issues
 
 Target behavior, per [Applying transitions](https://m3.material.io/styles/motion/transitions/applying-transitions). When `prefers-reduced-motion: reduce` is set:
 
-- **Swap movement for subtle fades rather than removing the transition** (a jump cut would break the "no jarring jump cuts" rule). `enterExit.scale`/`dialog`/`slideUp`/`sideSheet`/`bottomSheet` fall back to `enterExit.fade`. `sharedAxis`, `lateral` and `containerTransform` fall back to a `fadeThrough`-style opacity-only fade, with no translate or scale.
+- **Swap movement for subtle fades rather than removing the transition** (a jump cut would break the "no jarring jump cuts" rule). `enterExit.scale`/`dialog`/`slideUp`/`sideSheet`/`bottomSheet` fall back to `enterExit.fade`. `sharedAxis`, `lateral` and `fadeThrough` fall back to an opacity-only fade with no translate or scale, their region's box swapping instantly; `containerTransform` crossfades its two states in place without growing (`animation/reducedMotion.ts`).
 - **Disable decorative effects**: shape morphing (button `--btn-shape` morphs; `morphShape`/`shapeMorph` already swap instantly), parallax, the ripple (already done).
 - Keep effects-spring color/opacity feedback (state layers, hover/press color), since that motion carries meaning and isn't intense.

package/claude-skill/material-design/references/tokens-and-styles.md

@@ -48,6 +48,10 @@ The full M3 type scale (https://m3.material.io/styles/typography/type-scale-toke
 
 `md.sys.measurement.space<N>` (N/100 × the 8dp base) is registered in Tailwind's spacing namespace. Every spacing utility therefore takes it: `p-spacing-200` (16dp), `gap-spacing-50` (4dp), `mr-spacing-300` (24dp), `size-spacing-600` (48dp). The available numbers are 0, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 400, 450, 500, 600, 700, 800 and 900. The number is M3's token number, not Tailwind's 4px multiplier.
 
+## Component dimensions (`src/lib/styles/components.css`)
+
+M3 component dimensions that aren't on the spacing grid are custom properties named after their token in the M3 token database, with dots as dashes: `--md-comp-nav-rail-collapsed-container-width` (96dp), `--md-comp-nav-rail-expanded-container-width-minimum` (220dp), and so on. Use them as `w-(--md-comp-…)`. A new off-grid spec value goes in this file under its token name, never as a Tailwind number (`w-24`) or an arbitrary value (`w-[96px]`). A dimension that is on the grid uses the spacing token instead. Migrating the remaining numeric/arbitrary sizes is issue #30.
+
 ## Elevation (`src/lib/styles/elevation.css`)
 
 `shadow-elevation-{0..5}`, each a two-layer (spot + ambient) shadow scaled to the M3 elevation spec, using `color-mix` against the `shadow` color role so it adapts per theme automatically. Elevation communicates depth/priority — reach for a higher level when a surface should read as "above" its neighbors (menus, FABs, dialogs), not as a decorative effect.

package/dist/animation/TransitionPatterns.stories.svelte

@@ -98,6 +98,24 @@
     );
   };
 
+  /* Lateral on the y axis — vertical tabs: the next peer pushes up from below. */
+  const steps = ['Shipping', 'Payment', 'Review'];
+  let step = $state(0);
+  const runLateralY = () => {
+    const next = (step + 1) % steps.length;
+    return lateral(
+      async () => {
+        step = next;
+        await tick();
+      },
+      {
+        target: '[data-demo="lateral-y"]',
+        axis: 'y',
+        direction: next > step ? 'forward' : 'backward'
+      }
+    );
+  };
+
   /* Top level — unrelated destinations, as from a navigation bar. */
   const destinations = [
     { label: 'Home', color: 'bg-md-sys-color-primary-container text-md-sys-color-primary' },
@@ -172,6 +190,14 @@
   } satisfies Record<string, Pattern>;
 
   const all = Object.values(patterns);
+  // A variant of lateral, not a seventh pattern: its own story, not in the overview grid.
+  const lateralY: Pattern = {
+    id: 'lateral-y',
+    title: 'Lateral, vertical',
+    summary: "Peers laid out top to bottom slide on the y axis: lateral with axis: 'y'.",
+    anchor: 'lateral',
+    run: runLateralY
+  };
 
   /** Loops `run` while `looping` is on; toggling the loop restarts the interval. */
   const loop =
@@ -258,6 +284,29 @@
         aria-hidden="true">{tab + 1}</span
       >
     </div>
+  {:else if pattern.id === 'lateral-y'}
+    <div class="inset-spacing-150 gap-spacing-200 absolute flex">
+      <div class="gap-spacing-200 flex flex-col justify-center">
+        {#each steps as name, i (name)}
+          <span
+            class={[
+              'md-sys-typescale-label-large',
+              i === step ? 'text-md-sys-color-primary' : 'text-md-sys-color-on-surface-variant'
+            ]}>{name}</span
+          >
+        {/each}
+      </div>
+      <div
+        data-demo="lateral-y"
+        class="bg-md-sys-color-surface-container relative flex flex-1 items-center justify-center rounded-lg"
+      >
+        {@render shape(pathFourLeafClover, 'size-24 text-md-sys-color-secondary')}
+        <span
+          class="md-sys-typescale-display-small text-md-sys-color-on-secondary absolute"
+          aria-hidden="true">{step + 1}</span
+        >
+      </div>
+    </div>
   {:else if pattern.id === 'top'}
     <div
       data-demo="top"
@@ -364,6 +413,7 @@
 <Story name="Container transform" asChild>{@render single(patterns.container)}</Story>
 <Story name="Forward and backward" asChild>{@render single(patterns.axis)}</Story>
 <Story name="Lateral" asChild>{@render single(patterns.lateral)}</Story>
+<Story name="Lateral vertical" asChild>{@render single(lateralY)}</Story>
 <Story name="Top level" asChild>{@render single(patterns.top)}</Story>
 <Story name="Enter and exit" asChild>{@render single(patterns.enterExit)}</Story>
 <Story name="Skeleton loaders" asChild>{@render single(patterns.skeleton)}</Story>

package/dist/animation/containerTransform.js

@@ -1,4 +1,5 @@
 import { animateView } from 'motion';
+import { prefersReducedMotion } from './reducedMotion.js';
 import { springTokens, springTransition } from './spring.js';
 /**
  * M3 container transform: one container morphs its bounds, shape and color into another while
@@ -27,7 +28,12 @@ import { springTokens, springTransition } from './spring.js';
  * );
  * ```
  */
-export const containerTransform = (update, { from, to, spring = springTokens.spatial }) => animateView(update, springTransition(spring))
-    .add(from, to)
-    .old({ opacity: [1, 0] }, springTransition(springTokens.fastEffects))
-    .new({ opacity: [0, 1] }, { ...springTransition(springTokens.effects), delay: 0.05 });
+export const containerTransform = (update, { from, to, spring = springTokens.spatial }) => {
+    const builder = animateView(update, springTransition(spring)).add(from, to);
+    // Reduced motion: the container doesn't grow; its two states just crossfade in place.
+    if (prefersReducedMotion())
+        builder.layout({ duration: 0 });
+    return builder
+        .old({ opacity: [1, 0] }, springTransition(springTokens.fastEffects))
+        .new({ opacity: [0, 1] }, { ...springTransition(springTokens.effects), delay: 0.05 });
+};

package/dist/animation/reducedMotion.d.ts

@@ -0,0 +1,2 @@
+/** Whether the user asked for reduced motion. False where there's no `matchMedia` (SSR). */
+export declare const prefersReducedMotion: () => boolean;

package/dist/animation/reducedMotion.js

@@ -0,0 +1,2 @@
+/** Whether the user asked for reduced motion. False where there's no `matchMedia` (SSR). */
+export const prefersReducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;

package/dist/animation/sharedAxisTransition.d.ts

@@ -8,6 +8,15 @@ interface NavigationOptions {
     direction?: NavigationDirection;
     spring?: SpringToken;
 }
+export interface LateralOptions extends NavigationOptions {
+    /**
+     * The axis the peers are laid out on: `x` for a row (tabs, a carousel), `y` for a column
+     * (vertical tabs, a vertical carousel, a stepper laid out top to bottom). `forward` moves to
+     * the next peer: right or down.
+     * @default 'x'
+     */
+    axis?: 'x' | 'y';
+}
 export interface SharedAxisOptions extends NavigationOptions {
     /** `x` for horizontal steps, `y` for vertical, `z` for parent → child depth. */
     axis?: 'x' | 'y' | 'z';
@@ -30,18 +39,21 @@ export interface SharedAxisOptions extends NavigationOptions {
 export declare const sharedAxis: (update: () => void | Promise<void>, { target, axis, direction, spring }?: SharedAxisOptions) => import("motion-dom").ViewTransitionBuilder;
 /**
  * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
- * without fading — the new screen pushes the old one out.
+ * without fading — the new screen pushes the old one out. Along the axis the peers are laid out
+ * on: `axis: 'y'` for a vertical set (vertical tabs, a vertical carousel, a top-to-bottom
+ * stepper), where the next peer pushes up from below.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
  *
  * Only for peers in one set (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it for hierarchical screens
  * (use `sharedAxis`) or navbar/rail/drawer destinations (use `fadeThrough`, since the implied swipe
- * conflicts with carousels and swipeable list items). Don't add a fade: it hides the peer
+ * conflicts with carousels and swipeable list items). A vertical nav list is still a drawer: a
+ * vertical slide there reads as the page jumping its scroll. Don't add a fade: it hides the peer
  * relationship and makes the slide look like forward/backward.
  *
  * Built in: `TabHolder` (switching content panels) and `DateField`/`DateRangeField` (changing the
  * visible month). Any new component that pages between peer views must use this too.
  */
-export declare const lateral: (update: () => void | Promise<void>, { target, direction, spring }?: NavigationOptions) => import("motion-dom").ViewTransitionBuilder;
+export declare const lateral: (update: () => void | Promise<void>, { target, axis, direction, spring }?: LateralOptions) => import("motion-dom").ViewTransitionBuilder;
 /**
  * M3 top level (fade through): destinations with no spatial relationship, e.g. navigation bar
  * items. The outgoing screen fades out, then the incoming one fades in while scaling up from 92%.
@@ -53,6 +65,11 @@ export declare const lateral: (update: () => void | Promise<void>, { target, dir
  *
  * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
  * its own route change in this.
+ *
+ * The `target` region swaps its box instantly instead of sliding or resizing to the new page's:
+ * that movement would be exactly the spatial connection this pattern avoids, and after a
+ * navigation that resets the scroll, the region would glide down by the distance scrolled.
+ * Its snapshots aren't cropped, and the old one stays where it was on screen (see `fadeInPlace`).
  */
 export declare const fadeThrough: (update: () => void | Promise<void>, { target, spring }?: Omit<NavigationOptions, "direction">) => import("motion-dom").ViewTransitionBuilder;
 export {};

package/dist/animation/sharedAxisTransition.js

@@ -1,4 +1,5 @@
 import { animateView } from 'motion';
+import { prefersReducedMotion } from './reducedMotion.js';
 import { springTokens, springTransition } from './spring.js';
 const SHARED_AXIS_OFFSET_PX = 30;
 const view = (update, target, spring) => {
@@ -10,6 +11,46 @@ const view = (update, target, spring) => {
    and hidden in the fastest part of the motion. Don't lengthen these. */
 const fadeOut = springTransition(springTokens.fastEffects);
 const fadeIn = { ...springTransition(springTokens.effects), delay: 0.05 };
+/* For fades with nothing moving to hide the handover (fade through, reduced motion): the new
+   page waits until the old one is all but gone (fastEffects is under 0.5% at 120ms). Starting
+   earlier leaves a ghost of the old layout behind the new one, made brighter by the additive
+   blend the browser puts on a crossfade. M3's fade through starts the incoming screen about a
+   third of the way in, so this is on spec. */
+const fadeInAfterOut = { ...springTransition(springTokens.effects), delay: 0.12 };
+/*
+  A region that fades in place, for fade through and every reduced-motion fade:
+  - Its box swaps to the new page's at once: sliding or resizing it would be the spatial
+    connection these fades avoid.
+  - Neither snapshot is cropped. Motion crops a region whose aspect ratio changed, scaling both
+    snapshots to cover the new box, so a short page fading out over a tall one looked zoomed.
+  - The outgoing snapshot stays exactly where it was on screen. A navigation usually resets the
+    scroll, so the region's new box sits elsewhere than the old one (400px lower after scrolling
+    400px); drawn in the new box, the old page would jump to its top as it fades, and the two
+    layouts look like they collide. The offset is measured around `update` and written into the
+    old keyframes, which Motion reads only once the update has run.
+*/
+const fadeInPlace = (update, target, spring, incoming) => {
+    const outgoing = { opacity: [1, 0] };
+    const region = () => typeof target === 'string' ? document.querySelector(target) : (target ?? null);
+    const before = target ? region()?.getBoundingClientRect() : undefined;
+    const run = async () => {
+        await update();
+        const after = region()?.getBoundingClientRect();
+        if (!before || !after)
+            return;
+        const dx = before.left - after.left;
+        const dy = before.top - after.top;
+        if (dx || dy)
+            outgoing.transform = Array(2).fill(`translate(${dx}px, ${dy}px)`);
+    };
+    const builder = view(run, target, spring);
+    if (target)
+        builder.layout({ duration: 0 }).crop(false);
+    return builder.old(outgoing, fadeOut).new(...incoming);
+};
+/* Reduced motion: every navigation pattern becomes this fade, with no movement or scale. M3
+   swaps movement for a subtle fade rather than cutting. */
+const reducedFade = (update, target, spring) => fadeInPlace(update, target, spring, [{ opacity: [0, 1] }, fadeInAfterOut]);
 /**
  * M3 forward and backward (shared axis): outgoing and incoming content travel together along one
  * axis while fading through each other.
@@ -26,6 +67,8 @@ const fadeIn = { ...springTransition(springTokens.effects), delay: 0.05 };
  * Not built into any component: hierarchy levels and wizard steps live in the consuming app.
  */
 export const sharedAxis = (update, { target, axis = 'x', direction = 'forward', spring = springTokens.spatial } = {}) => {
+    if (prefersReducedMotion())
+        return reducedFade(update, target, spring);
     const forward = direction === 'forward';
     const [outgoing, incoming] = axis === 'z'
         ? [`scale(${forward ? 1.1 : 0.8})`, `scale(${forward ? 0.8 : 1.1})`]
@@ -40,22 +83,28 @@ export const sharedAxis = (update, { target, axis = 'x', direction = 'forward',
 };
 /**
  * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
- * without fading — the new screen pushes the old one out.
+ * without fading — the new screen pushes the old one out. Along the axis the peers are laid out
+ * on: `axis: 'y'` for a vertical set (vertical tabs, a vertical carousel, a top-to-bottom
+ * stepper), where the next peer pushes up from below.
  * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
  *
  * Only for peers in one set (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it for hierarchical screens
  * (use `sharedAxis`) or navbar/rail/drawer destinations (use `fadeThrough`, since the implied swipe
- * conflicts with carousels and swipeable list items). Don't add a fade: it hides the peer
+ * conflicts with carousels and swipeable list items). A vertical nav list is still a drawer: a
+ * vertical slide there reads as the page jumping its scroll. Don't add a fade: it hides the peer
  * relationship and makes the slide look like forward/backward.
  *
  * Built in: `TabHolder` (switching content panels) and `DateField`/`DateRangeField` (changing the
  * visible month). Any new component that pages between peer views must use this too.
  */
-export const lateral = (update, { target, direction = 'forward', spring = springTokens.spatial } = {}) => {
+export const lateral = (update, { target, axis = 'x', direction = 'forward', spring = springTokens.spatial } = {}) => {
+    if (prefersReducedMotion())
+        return reducedFade(update, target, spring);
     const sign = direction === 'forward' ? 1 : -1;
+    const move = axis === 'y' ? 'translateY' : 'translateX';
     const builder = view(update, target, spring)
-        .old({ transform: ['translateX(0%)', `translateX(${-sign * 100}%)`] })
-        .new({ transform: [`translateX(${sign * 100}%)`, 'translateX(0%)'] });
+        .old({ transform: [`${move}(0%)`, `${move}(${-sign * 100}%)`] })
+        .new({ transform: [`${move}(${sign * 100}%)`, `${move}(0%)`] });
     return target ? builder.crop(true) : builder;
 };
 /**
@@ -69,7 +118,17 @@ export const lateral = (update, { target, direction = 'forward', spring = spring
  *
  * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
  * its own route change in this.
+ *
+ * The `target` region swaps its box instantly instead of sliding or resizing to the new page's:
+ * that movement would be exactly the spatial connection this pattern avoids, and after a
+ * navigation that resets the scroll, the region would glide down by the distance scrolled.
+ * Its snapshots aren't cropped, and the old one stays where it was on screen (see `fadeInPlace`).
  */
-export const fadeThrough = (update, { target, spring = springTokens.spatial } = {}) => view(update, target, spring)
-    .old({ opacity: [1, 0] }, fadeOut)
-    .new({ opacity: [0, 1], transform: ['scale(0.92)', 'scale(1)'] }, { opacity: { ...springTransition(springTokens.effects), delay: 0.09 } });
+export const fadeThrough = (update, { target, spring = springTokens.spatial } = {}) => {
+    if (prefersReducedMotion())
+        return reducedFade(update, target, spring);
+    return fadeInPlace(update, target, spring, [
+        { opacity: [0, 1], transform: ['scale(0.92)', 'scale(1)'] },
+        { opacity: fadeInAfterOut }
+    ]);
+};

package/dist/attachments/drag.d.ts

@@ -0,0 +1,52 @@
+import type { Attachment } from 'svelte/attachments';
+export type DragPoint = {
+    x: number;
+    y: number;
+};
+export type DragOptions = {
+    /** Stops new drags from starting. A drag already running finishes. */
+    disabled?: boolean;
+    /**
+     * How far (px) the pointer must move before a drag starts. Below it the press stays a plain
+     * press, so a click on a draggable button still clicks. `0` starts on pointerdown.
+     * @default 0
+     */
+    threshold?: number;
+    /**
+     * Touch only: how long (ms) a finger must rest before a drag starts. Moving sooner scrolls the
+     * page instead, so a row of draggable things doesn't trap swipes. `0` treats touch like a mouse.
+     * @default 0
+     */
+    touchDelay?: number;
+    /** The drag started. */
+    onStart?: (event: PointerEvent) => void;
+    /** The pointer moved; `offset` is its total travel since the press. */
+    onMove?: (offset: DragPoint, event: PointerEvent) => void;
+    /**
+     * The drag ended. `velocity` (px/s) is the pointer's speed over its last 100ms, for a spring to
+     * carry on release; it's zero when the browser cancelled the pointer.
+     */
+    onEnd?: (velocity: DragPoint) => void;
+};
+/**
+ * Pointer dragging for an element: capture, a start threshold, a long-press delay on touch, and
+ * the release velocity. It moves nothing itself: `onMove` gets the pointer's offset and the
+ * caller positions things, typically with `resist` at the edges and a Motion spring on release.
+ *
+ * Options are read through a getter at event time, so changing them never tears down a drag in
+ * progress:
+ *
+ * ```svelte
+ * <div {@attach drag(() => ({ threshold: 4, onMove: (o) => (offset = o) }))}>…</div>
+ * ```
+ *
+ * After a drag the click that would follow the release is swallowed, so dragging a button
+ * doesn't also press it.
+ */
+export declare function drag(getOptions: () => DragOptions): Attachment<HTMLElement>;
+/**
+ * `value` clamped to `[min, max]` with rubber-banding instead of a wall: past an edge it keeps
+ * following the pointer, less and less. `size` is the scale of the resistance, usually the
+ * extent of the bounds on that axis.
+ */
+export declare function resist(value: number, min: number, max: number, size: number): number;