@honeydeck/honeydeck 0.7.0 → 0.9.0

package/AGENTS.md

@@ -5,7 +5,7 @@ This package publishes the scoped public `@honeydeck/honeydeck` npm package. It
 ## Rules
 
 - Keep public import paths as `@honeydeck/honeydeck/...`.
-- `Readme.md` is the compact package README and links to the public docs site. Reader-facing docs live in `packages/docs/content/docs`.
+- `Readme.md` is the compact package README and links to the public docs site. Reader-facing docs live in `packages/docs/content/docs`; update those canonical docs for user-facing behavior changes.
 - Built-in runtime reference pages cover project-specific theme tokens, active layouts, and built-in component docs. They do not render public docs in-deck.
 - Specs, `DEVELOPMENT.md`, and skills must remain included in npm package contents.
 - Use suffixed `lucide-react` icon exports.

package/docs/configuration.md

@@ -16,7 +16,9 @@ Defined in the first frontmatter block of the deck entry file (before any slide
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional PDF color mode; when unset, falls back to pinned `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | PDF includes all steps or final state |
-| `transition` | `boolean` | `true` | Enable crossfade between slides |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or custom CSS name) |
+| `transitionDuration` | `number` | `200` | Default slide transition duration in milliseconds |
+| `transitionEasing` | `string` | `ease` | Default slide transition timing function |
 | `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
 | `layouts` | `string` | `""` (built-in) | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
@@ -46,13 +48,17 @@ When pinned, the viewer cannot switch mode from navigation controls.
 
 ### Transitions
 
-A subtle crossfade (~200ms) is applied between slides by default:
+A subtle named `fade` transition is applied between slides by default:
 
 ```yaml
-transition: true    # default
-transition: false   # disable
+transition: fade    # default
+transition: none    # disable
 ```
 
+Legacy booleans still work: `transition: true` maps to `fade`, and `transition: false` maps to `none`.
+
+For built-ins, custom CSS transitions, duration, and easing, see [Transitions](transitions.md).
+
 ### Magic Code Duration
 
 Magic Code animations default to 800ms. Set a deck-wide default with `magicCodeDuration`:
@@ -70,6 +76,9 @@ Per-slide frontmatter (after `---`):
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `layout` | `string` | (uses `defaultLayout`) | Layout to use (PascalCase) |
+| `transition` | `string \| boolean` | deck default | Named transition into this slide |
+| `transitionDuration` | `number` | deck default | Transition duration into this slide in milliseconds |
+| `transitionEasing` | `string` | deck default | Transition easing into this slide |
 | ...layout props | varies | — | Additional props the layout accepts |
 
 Example:
@@ -96,6 +105,9 @@ in the first frontmatter block alongside deck-level settings.
 ---
 title: "My First Deck"
 colorMode: system
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 layouts: "@honeydeck/honeydeck/layouts"
 layout: Cover
 ---

package/docs/deeper-dive.md

@@ -111,19 +111,22 @@ Deck-level settings live in the first frontmatter block of the deck entry file.
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional PDF color mode; falls back to pinned `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | PDF step handling |
-| `transition` | `boolean` | `true` | Crossfade between slides |
+| `transition` | `string \| boolean` | `fade` | Named slide transition |
 | `layouts` | `string` | `""` (built-in) | Custom layout map path |
 | `defaultLayout` | `string` | `"Default"` | Fallback layout |
 | `showSlideNumbers` | `boolean` | `false` | Show slide numbers |
 
-Slide-level frontmatter chooses the slide layout and passes layout-specific props.
+Slide-level frontmatter chooses the slide layout, passes layout-specific props, and can override the transition into that slide.
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `layout` | `string` | Layout name in PascalCase |
+| `transition` | `string \| boolean` | Named transition into this slide |
+| `transitionDuration` | `number` | Transition duration in milliseconds |
+| `transitionEasing` | `string` | Transition timing function |
 | layout props | varies | Layout-specific fields |
 
-For the full reference, see [Configuration](configuration.md).
+For the full reference, see [Configuration](configuration.md) and [Transitions](transitions.md).
 
 ## Core components
 

package/docs/index.json

@@ -45,6 +45,17 @@
       "file": "configuration.md",
       "sourcePath": "packages/docs/content/docs/(core)/configuration.mdx"
     },
+    {
+      "slug": "transitions",
+      "title": "Transitions",
+      "description": "Configure built-in and custom slide transitions in Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Transitions"
+      ],
+      "file": "transitions.md",
+      "sourcePath": "packages/docs/content/docs/(core)/transitions.mdx"
+    },
     {
       "slug": "steps-and-reveals",
       "title": "Steps and reveals",

package/docs/transitions.md

@@ -0,0 +1,126 @@
+<!-- Generated from packages/docs/content/docs/(core)/transitions.mdx. Do not edit by hand. -->
+
+# Transitions
+
+Honeydeck uses named slide transitions. Set a deck-wide default in the first frontmatter block, then override individual slides when needed.
+
+## Deck defaults
+
+```yaml
+---
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
+---
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `transition` | `string \| boolean` | `fade` | Named transition for slide changes |
+| `transitionDuration` | `number` | `200` | Duration in milliseconds |
+| `transitionEasing` | `string` | `ease` | CSS timing function |
+
+Built-in transition names:
+
+- `fade` — default crossfade
+- `none` — no slide transition
+- `slide-left` — horizontal slide, reverse-aware when navigating backward
+
+## Slide overrides
+
+Slide frontmatter controls the transition **into that slide**:
+
+```mdx
+---
+transition: slide-left
+transitionDuration: 500
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# A slide with a custom entrance
+```
+
+Slides without transition frontmatter use the deck defaults.
+
+## Custom transitions
+
+Any transition name that is not built in becomes a CSS hook. For example:
+
+```mdx
+---
+transition: honey-spin
+transitionDuration: 700
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# Custom CSS Transition
+```
+
+Honeydeck adds classes to only the entering and exiting slide layers:
+
+```html
+<div class="honeydeck-slide-layer honeydeck-transition-honey-spin honeydeck-transition-enter">
+```
+
+```html
+<div class="honeydeck-slide-layer honeydeck-transition-honey-spin honeydeck-transition-exit">
+```
+
+Scope your CSS to both the transition name and enter/exit class:
+
+```css
+.honeydeck-slide-layer.honeydeck-transition-honey-spin.honeydeck-transition-enter {
+  animation-name: honey-spin-enter;
+  animation-duration: var(--honeydeck-transition-duration);
+  animation-timing-function: var(--honeydeck-transition-easing);
+  animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-honey-spin.honeydeck-transition-exit {
+  animation-name: honey-spin-exit;
+  animation-duration: var(--honeydeck-transition-duration);
+  animation-timing-function: var(--honeydeck-transition-easing);
+  animation-fill-mode: both;
+}
+```
+
+## Reverse-aware CSS
+
+Honeydeck provides a direction variable:
+
+```css
+--honeydeck-transition-direction: 1;  /* forward */
+--honeydeck-transition-direction: -1; /* backward */
+```
+
+Use it in transform math when your custom transition should reverse with navigation direction:
+
+```css
+@keyframes custom-enter {
+  from {
+    opacity: 0;
+    transform: translateX(calc(40% * var(--honeydeck-transition-direction)));
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes custom-exit {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(calc(-20% * var(--honeydeck-transition-direction)));
+  }
+}
+```
+
+Honeydeck cannot safely invert arbitrary custom keyframes automatically, so reverse behavior is opt-in through CSS variables.
+
+## Reduced motion
+
+If the viewer has `prefers-reduced-motion: reduce`, Honeydeck disables slide transition animations.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {

package/src/cli/templates/SPEC.md

@@ -43,8 +43,9 @@ Generated starter tree includes `package.json`, `deck.mdx`, `styles.css`, `.giti
 
 Tutorial-style `deck.mdx` imports `./styles.css` so styling stays explicit and user-controlled. It demonstrates:
 
-- Deck frontmatter, including `colorMode: system`
+- Deck frontmatter, including `colorMode: system`, named transition defaults (`transition`, `transitionDuration`, `transitionEasing`), and layout map hints
 - Slide separators
+- Built-in slide transitions via deck-level defaults and at least one slide-level `transition:` override
 - Built-in layouts via per-slide `layout:` (`Default`, `Section`, `TwoCol`, `Cover`, `Blank`)
 - Code highlighting with step-through
 - Custom interactive component (`SparkleButton`)

package/src/cli/templates/starter/deck.mdx

@@ -3,6 +3,10 @@ title: demo-deck
 description: A clean Honeydeck starter deck
 # Define the color mode for your slides: light, dark, system.
 colorMode: system
+# Configure slide transitions. Use "none" to disable.
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 # Swap layouts for a custom layout map or the included bee theme (also update css).
 # - Custom layouts: layouts: "./layouts"
 # - Bee layouts: layouts: "@honeydeck/honeydeck/layouts/bee"
@@ -44,6 +48,24 @@ All you need is `---` for new slides.
 You can press <Keyboard>↓</Keyboard> to skip revealed content and jump to the next slide.
 </Reveal>
 
+---
+transition: slide-left
+transitionDuration: 500
+transitionEasing: cubic-bezier(0.22, 1, 0.36, 1)
+---
+
+# Choose slide transitions 🎬
+
+Deck-level frontmatter sets the default transition. Slide frontmatter overrides the transition into that slide.
+
+```yaml
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
+```
+
+Use `transition: none` when you want no slide animation.
+
 ---
 
 # Grow into React when needed ⚛️

package/src/runtime/Deck.tsx

@@ -27,6 +27,7 @@
 
 import { config } from "virtual:honeydeck/config";
 import {
+	type CSSProperties,
 	useCallback,
 	useEffect,
 	useLayoutEffect,
@@ -82,6 +83,80 @@ function calcScaleFromElement(el: HTMLElement | null): number | null {
 	return Math.min(el.clientWidth / BASE_WIDTH, el.clientHeight / BASE_HEIGHT);
 }
 
+type SlideTransitionState = {
+	from: number;
+	to: number;
+	name: string;
+	className: string;
+	duration: number;
+	easing: string;
+	direction: 1 | -1;
+	enterFromOpacity: number;
+	exitFromOpacity: number;
+};
+
+function normalizeTransitionName(value: unknown): string {
+	if (value === false) return "none";
+	if (value === true || value == null) return "fade";
+	if (typeof value !== "string") return "fade";
+
+	const name = value.trim();
+	if (!name) return "fade";
+	if (name === "true") return "fade";
+	if (name === "false") return "none";
+	return name;
+}
+
+function normalizeTransitionDuration(value: unknown): number | null {
+	if (typeof value !== "number" || !Number.isFinite(value)) return null;
+	return Math.max(0, Math.round(value));
+}
+
+function normalizeTransitionEasing(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const easing = value.trim();
+	return easing ? easing : null;
+}
+
+function transitionClassName(name: string): string {
+	return name.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+}
+
+function readLayerOpacity(
+	element: HTMLElement | null | undefined,
+): number | null {
+	if (!element) return null;
+	const opacity = Number.parseFloat(window.getComputedStyle(element).opacity);
+	return Number.isFinite(opacity) ? opacity : null;
+}
+
+function getTransitionOptions(
+	slideIndex: number,
+): Omit<
+	SlideTransitionState,
+	"from" | "to" | "direction" | "enterFromOpacity" | "exitFromOpacity"
+> {
+	const frontmatter = slideData[slideIndex]?.frontmatter ?? {};
+	const name = normalizeTransitionName(
+		frontmatter.transition ?? config.transition,
+	);
+	const duration =
+		normalizeTransitionDuration(frontmatter.transitionDuration) ??
+		normalizeTransitionDuration(config.transitionDuration) ??
+		200;
+	const easing =
+		normalizeTransitionEasing(frontmatter.transitionEasing) ??
+		normalizeTransitionEasing(config.transitionEasing) ??
+		"ease";
+
+	return {
+		name,
+		className: transitionClassName(name),
+		duration,
+		easing,
+	};
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -102,6 +177,7 @@ export function Deck() {
 	});
 	const [effectiveColorMode, setEffectiveColorMode] =
 		useState<EffectiveColorMode>("light");
+	const [reducedMotion, setReducedMotion] = useState(false);
 
 	const route = useRoute();
 	const pointerLayout = usePointerLayout();
@@ -126,6 +202,17 @@ export function Deck() {
 		return () => mq.removeEventListener("change", onChange);
 	}, [colorMode]);
 
+	// ── Reduced motion: disable slide transition animations ────────────────
+	useEffect(() => {
+		const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+		setReducedMotion(mq.matches);
+
+		const onChange = (event: MediaQueryListEvent) =>
+			setReducedMotion(event.matches);
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	}, []);
+
 	// ── Observe stage size → recalculate scale ─────────────────────────────
 	useEffect(() => {
 		if (route.view !== "slide" && route.view !== "overview") return;
@@ -247,6 +334,73 @@ export function Deck() {
 		});
 	}, [scale, slideZoom]);
 
+	const currentSlide = Math.max(
+		1,
+		Math.min(route.slide, slideData.length || 1),
+	);
+	const previousSlideRef = useRef<number | null>(null);
+	const slideLayerRefs = useRef<Record<number, HTMLDivElement | null>>({});
+	const [slideTransition, setSlideTransition] =
+		useState<SlideTransitionState | null>(null);
+	const slideTransitionRef = useRef<SlideTransitionState | null>(null);
+	slideTransitionRef.current = slideTransition;
+
+	useLayoutEffect(() => {
+		if (route.view !== "slide") {
+			previousSlideRef.current = currentSlide;
+			setSlideTransition(null);
+			return;
+		}
+
+		if (reducedMotion) {
+			previousSlideRef.current = currentSlide;
+			setSlideTransition(null);
+			return;
+		}
+
+		const previousSlide = previousSlideRef.current;
+		if (previousSlide === null) {
+			previousSlideRef.current = currentSlide;
+			return;
+		}
+		if (previousSlide === currentSlide) return;
+
+		const direction: 1 | -1 = currentSlide > previousSlide ? 1 : -1;
+		const options = getTransitionOptions(currentSlide - 1);
+		previousSlideRef.current = currentSlide;
+
+		if (options.name === "none" || options.duration === 0) {
+			setSlideTransition(null);
+			return;
+		}
+
+		const activeTransition = slideTransitionRef.current;
+		const isInterruptingFade = activeTransition?.name === "fade";
+		const nextTransition = {
+			...options,
+			from: previousSlide,
+			to: currentSlide,
+			direction,
+			enterFromOpacity: isInterruptingFade
+				? (readLayerOpacity(slideLayerRefs.current[currentSlide]) ?? 0)
+				: 0,
+			exitFromOpacity: isInterruptingFade
+				? (readLayerOpacity(slideLayerRefs.current[previousSlide]) ?? 1)
+				: 1,
+		};
+		setSlideTransition(nextTransition);
+
+		const timeout = window.setTimeout(() => {
+			setSlideTransition((active) =>
+				active?.from === nextTransition.from && active.to === nextTransition.to
+					? null
+					: active,
+			);
+		}, options.duration);
+
+		return () => window.clearTimeout(timeout);
+	}, [currentSlide, reducedMotion, route.view]);
+
 	// ── Reference mode: delegate to DocsView ─────────────────────────────
 	if (route.view === "kit") {
 		return (
@@ -265,9 +419,6 @@ export function Deck() {
 		);
 	}
 
-	// Whether slide transitions are enabled (can be disabled via deck frontmatter)
-	const enableTransition = config.transition !== false;
-
 	// ─────────────────────────────────────────────────────────────────────────
 	// Guard: no slides
 	// ─────────────────────────────────────────────────────────────────────────
@@ -280,14 +431,15 @@ export function Deck() {
 		);
 	}
 
-	const currentSlide = Math.max(1, Math.min(route.slide, slideData.length));
 	const currentStep = Math.max(0, route.step);
 	const controlRoute =
 		route.view === "slide" || route.view === "overview"
 			? { ...route, slide: currentSlide, step: currentStep }
 			: route;
 	const activeSlideScale = scale * slideZoom;
+	const viewportScale = scale || 1;
 	const slideTransform = `translate(${slidePan.x}px, ${slidePan.y}px) scale(${activeSlideScale})`;
+	const zoomedSlideTransform = `translate(${slidePan.x / viewportScale}px, ${slidePan.y / viewportScale}px) scale(${slideZoom})`;
 	const showSlideNumbers = config.showSlideNumbers === true;
 	const disableSlideTextSelection =
 		route.view === "slide" &&
@@ -326,6 +478,31 @@ export function Deck() {
 					{slideData.map((data, i) => {
 						const slideNumber = i + 1;
 						const isCurrent = slideNumber === currentSlide;
+						const activeTransition = slideTransition;
+						const transitionRole =
+							activeTransition?.to === slideNumber
+								? "enter"
+								: activeTransition?.from === slideNumber
+									? "exit"
+									: null;
+						const isVisible = isCurrent || transitionRole !== null;
+						const transitionLayerClass =
+							transitionRole && activeTransition
+								? `honeydeck-transition-${activeTransition.className} honeydeck-transition-${transitionRole}`
+								: "";
+						const layerStyle =
+							transitionRole && activeTransition
+								? ({
+										"--honeydeck-transition-duration": `${activeTransition.duration}ms`,
+										"--honeydeck-transition-easing": activeTransition.easing,
+										"--honeydeck-transition-direction":
+											activeTransition.direction,
+										"--honeydeck-transition-enter-from-opacity":
+											activeTransition.enterFromOpacity,
+										"--honeydeck-transition-exit-from-opacity":
+											activeTransition.exitFromOpacity,
+									} as CSSProperties)
+								: undefined;
 						const { Component, stepCount, title, frontmatter, layoutName } =
 							data;
 						const LayoutComponent = resolveLayout(layoutName);
@@ -335,42 +512,67 @@ export function Deck() {
 								key={data.id}
 								aria-hidden={!isCurrent}
 								className={`absolute inset-0 flex items-center justify-center ${
-									isCurrent
-										? "opacity-100 visible pointer-events-auto z-1"
-										: "opacity-0 invisible pointer-events-none z-0"
+									isVisible ? "visible" : "invisible"
+								} ${isCurrent ? "pointer-events-auto" : "pointer-events-none"} ${
+									transitionRole === "enter"
+										? "z-2"
+										: transitionRole === "exit"
+											? "z-1"
+											: isCurrent
+												? "z-1"
+												: "z-0"
 								}`}
-								style={{
-									transition: enableTransition
-										? `opacity 200ms ease, visibility 0s ${isCurrent ? "0s" : "200ms"}`
-										: "none",
-								}}
 							>
-								<TimelineProvider
-									stepIndex={isCurrent ? currentStep : 0}
-									stepCount={stepCount}
+								<div
+									className="shrink-0 overflow-hidden"
+									style={{
+										width: BASE_WIDTH,
+										height: BASE_HEIGHT,
+										transform: `scale(${scale})`,
+										transformOrigin: "center center",
+									}}
 								>
-									<SlideScaleProvider scale={activeSlideScale}>
-										<div
-											className="honeydeck-slide-canvas shrink-0 relative overflow-hidden box-border"
-											style={{
-												width: BASE_WIDTH,
-												height: BASE_HEIGHT,
-												transform: slideTransform,
-												transformOrigin: "center center",
-											}}
+									<div
+										ref={(element) => {
+											slideLayerRefs.current[slideNumber] = element;
+										}}
+										className={`honeydeck-slide-layer relative ${
+											isCurrent ? "opacity-100" : "opacity-0"
+										} ${transitionLayerClass}`}
+										style={{
+											width: BASE_WIDTH,
+											height: BASE_HEIGHT,
+											...layerStyle,
+										}}
+									>
+										<TimelineProvider
+											stepIndex={isCurrent ? currentStep : 0}
+											stepCount={stepCount}
 										>
-											<ErrorBoundary slideNumber={slideNumber}>
-												<LayoutComponent
-													title={title || null}
-													frontmatter={frontmatter}
-													rawChildren={<Component />}
+											<SlideScaleProvider scale={activeSlideScale}>
+												<div
+													className="honeydeck-slide-canvas shrink-0 relative overflow-hidden box-border"
+													style={{
+														width: BASE_WIDTH,
+														height: BASE_HEIGHT,
+														transform: zoomedSlideTransform,
+														transformOrigin: "center center",
+													}}
 												>
-													<Component />
-												</LayoutComponent>
-											</ErrorBoundary>
-										</div>
-									</SlideScaleProvider>
-								</TimelineProvider>
+													<ErrorBoundary slideNumber={slideNumber}>
+														<LayoutComponent
+															title={title || null}
+															frontmatter={frontmatter}
+															rawChildren={<Component />}
+														>
+															<Component />
+														</LayoutComponent>
+													</ErrorBoundary>
+												</div>
+											</SlideScaleProvider>
+										</TimelineProvider>
+									</div>
+								</div>
 							</div>
 						);
 					})}

package/src/runtime/SPEC.md

@@ -223,12 +223,20 @@ Build output is a single-page application. The app preserves client-side slide t
 
 ### Slide Transitions
 
-Honeydeck includes a single subtle crossfade (~200ms) between slides. Disabled with:
+Honeydeck uses a named slide transition system. Deck-level frontmatter sets defaults, and slide-level frontmatter overrides the transition **into that slide**:
 
 ```yaml
-transition: false
+transition: fade
+transitionDuration: 200
+transitionEasing: ease
 ```
 
+Built-in transition names are `fade`, `none`, and `slide-left`. Any other string is exposed as a custom CSS hook on the participating slide layers. Legacy `transition: true` maps to `fade`, and `transition: false` maps to `none`.
+
+During slide navigation, Honeydeck keeps the outgoing and incoming slide layers mounted inside a scaled slide-sized clipping viewport, applies `honeydeck-slide-layer`, `honeydeck-transition-{name}`, and either `honeydeck-transition-enter` or `honeydeck-transition-exit` only to those two layers, then clears transition state after the configured duration. Transition visuals are clipped to the slide canvas area and must not animate into letterbox or pillarbox bars around the slide. If the next transition is `none` or navigation is interrupted, stale transition state is cleared/replaced so old slides do not remain visible. Outgoing layers are visible during the transition but have pointer events disabled. The built-in `fade` transition uses keyframes and, when a fade is interrupted, starts the next fade from the participating layers' current computed opacity so quick back-and-forth navigation stays close to the old opacity-transition behavior.
+
+Participating slide layers receive CSS variables: `--honeydeck-transition-duration`, `--honeydeck-transition-easing`, and `--honeydeck-transition-direction` (`1` forward, `-1` backward). Built-in `slide-left` uses the direction variable so backward navigation reverses direction. Custom transition CSS can use the same variable for opt-in reverse awareness. Reduced-motion preferences disable slide transition animations.
+
 ### Aspect Ratio
 
 Slides render at a fixed 1920px logical width. Height is derived from deck-level `aspectRatio` when it is a string ratio matching `N:N` (default `16:9` → `1080`, `4:3` → `1440`, etc.). Invalid or missing ratios fall back to `16:9`.

package/src/theme/base.css

@@ -531,6 +531,91 @@
 	font-size: var(--honeydeck-font-size-code);
 }
 
+/* ── Slide transitions ───────────────────────────────────────────────────── */
+
+.honeydeck-slide-layer.honeydeck-transition-fade.honeydeck-transition-enter {
+	animation-name: honeydeck-transition-fade-enter;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-fade.honeydeck-transition-exit {
+	animation-name: honeydeck-transition-fade-exit;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+@keyframes honeydeck-transition-fade-enter {
+	from {
+		opacity: var(--honeydeck-transition-enter-from-opacity, 0);
+	}
+
+	to {
+		opacity: 1;
+	}
+}
+
+@keyframes honeydeck-transition-fade-exit {
+	from {
+		opacity: var(--honeydeck-transition-exit-from-opacity, 1);
+	}
+
+	to {
+		opacity: 0;
+	}
+}
+
+.honeydeck-slide-layer.honeydeck-transition-slide-left.honeydeck-transition-enter {
+	animation-name: honeydeck-transition-slide-left-enter;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+.honeydeck-slide-layer.honeydeck-transition-slide-left.honeydeck-transition-exit {
+	animation-name: honeydeck-transition-slide-left-exit;
+	animation-duration: var(--honeydeck-transition-duration, 200ms);
+	animation-timing-function: var(--honeydeck-transition-easing, ease);
+	animation-fill-mode: both;
+}
+
+@keyframes honeydeck-transition-slide-left-enter {
+	from {
+		opacity: 1;
+		transform: translateX(
+			calc(100% * var(--honeydeck-transition-direction, 1))
+		);
+	}
+
+	to {
+		opacity: 1;
+		transform: translateX(0);
+	}
+}
+
+@keyframes honeydeck-transition-slide-left-exit {
+	from {
+		opacity: 1;
+		transform: translateX(0);
+	}
+
+	to {
+		opacity: 1;
+		transform: translateX(
+			calc(-100% * var(--honeydeck-transition-direction, 1))
+		);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.honeydeck-slide-layer.honeydeck-transition-enter,
+	.honeydeck-slide-layer.honeydeck-transition-exit {
+		animation: none;
+	}
+}
+
 /* ── Documentation Markdown typography ──────────────────────────────────────
    Rendered README/docs pages use plain MDX elements. Keep their typography
    here instead of in DocsView so the React view stays structural.             */

package/src/vite-plugin/SPEC.md

@@ -108,7 +108,9 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | `colorMode` | `"system" \| "light" \| "dark"` | `"system"` | Browser color mode |
 | `pdfColorMode` | `"light" \| "dark"` | unset | Optional explicit PDF color mode; when unset, PDF falls back to pinned deck `colorMode`, then `light` |
 | `pdfSteps` | `"final" \| "all"` | `"final"` | Whether PDF includes all steps or final state |
-| `transition` | `boolean` | `true` | Enable crossfade transition between slides |
+| `transition` | `string \| boolean` | `fade` | Default named slide transition (`fade`, `none`, `slide-left`, or a custom CSS name); legacy `true` maps to `fade` and `false` maps to `none` |
+| `transitionDuration` | `number` | `200` | Default slide transition duration in milliseconds |
+| `transitionEasing` | `string` | `ease` | Default slide transition timing function |
 | `magicCodeDuration` | `number` | `800` | Default Magic Code animation duration in milliseconds |
 | `layouts` | `string` | built-in `@honeydeck/honeydeck/layouts` | Layout map module path |
 | `defaultLayout` | `string` | `"Default"` | Layout used when slide has no `layout:` |
@@ -119,6 +121,9 @@ All settings use **camelCase**. No separate config file exists. Frontmatter pars
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `layout` | `string` | (uses `defaultLayout`) | Layout map key to use (PascalCase by convention, not validated) |
+| `transition` | `string \| boolean` | deck default | Named transition into this slide; legacy booleans map to `fade`/`none` |
+| `transitionDuration` | `number` | deck default | Transition duration into this slide in milliseconds |
+| `transitionEasing` | `string` | deck default | Transition easing into this slide |
 | ...layout-specific props | varies | — | Any additional props the layout accepts |
 
 ### Root frontmatter semantics
@@ -127,6 +132,6 @@ The first frontmatter block in the deck entry file is parsed as deck config. Dec
 
 Slide-level frontmatter is a frontmatter-only block after a slide separator and applies to the following slide. Imported MDX files are normal MDX modules and cannot set deck-level properties. `magicCodeDuration` is deck-level only; the same key in slide-level frontmatter is treated as a normal layout prop and does not configure Magic Code.
 
-Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; `transition` is enabled unless literal `false`. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
+Invalid `aspectRatio`, `colorMode`, and `pdfSteps` values fall back to defaults. Invalid `pdfColorMode` is ignored as unset, allowing the pinned `colorMode` fallback. `showSlideNumbers` is enabled only by literal `true`; slide transition values normalize at runtime, with non-empty strings treated as named built-ins or custom CSS hooks. Invalid explicit Magic Code block `duration` values are compile errors; invalid deck-level `magicCodeDuration` falls back to the default Magic Code duration.
 
 During development, changes to deck-level frontmatter invalidate the virtual config and every compiled virtual slide module, because slide compilation can depend on deck settings such as `magicCodeDuration`. Layout-related virtual modules are invalidated as before so layout map and demo previews stay current.

package/src/vite-plugin/splitter.ts

@@ -65,6 +65,8 @@ const DECK_FRONTMATTER_KEYS = new Set([
 	"pdfColorMode",
 	"pdfSteps",
 	"transition",
+	"transitionDuration",
+	"transitionEasing",
 	"magicCodeDuration",
 	"layouts",
 	"defaultLayout",