From d6b2257177a3c60ef8880edfeb6a7e5030eb8b43 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 20:19:12 +0400
Subject: [PATCH 01/37] feat: Refined Popper animation flow and side-based
 unfolding

Separated floating-ui positioning and visual animation by introducing a positioner wrapper.

Reworked menu popper transitions to use side-aware uncollapse behavior with optional animation settings.

Updated React/Vue popper tests for the new DOM structure and animation variables.

Added draft notes with hypotheses, checks, and source references for M3 motion guidance.
---
 .../stylesheets/components/menu/index.scss    |   2 +-
 .../stylesheets/components/popper/index.scss  |  71 ++++++-
 m3-foundation/eslint.config.js                |  14 ++
 m3-foundation/lib/popper/floating.ts          |  38 +++-
 m3-foundation/types/components/popper.d.ts    |   3 +-
 m3-react/eslint.config.js                     |  14 ++
 m3-react/src/components/menu/M3Menu.tsx       |   1 +
 m3-react/src/components/popper/M3Popper.tsx   | 100 ++++++++--
 m3-react/src/components/popper/types.d.ts     |   3 +-
 m3-react/tests/M3Popper.e2e.tsx               | 176 +++++++++++++++---
 m3-react/tests/M3Popper.test.tsx              |  17 +-
 m3-vue/eslint.config.js                       |  14 ++
 m3-vue/src/components/menu/M3Menu.vue         |   3 +-
 m3-vue/src/components/popper/M3Popper.vue     | 107 +++++++++--
 m3-vue/tests/M3Popper.e2e.ts                  | 172 ++++++++++++++---
 15 files changed, 629 insertions(+), 106 deletions(-)

diff --git a/m3-foundation/assets/stylesheets/components/menu/index.scss b/m3-foundation/assets/stylesheets/components/menu/index.scss
index 997f10f..1ac4f58 100644
--- a/m3-foundation/assets/stylesheets/components/menu/index.scss
+++ b/m3-foundation/assets/stylesheets/components/menu/index.scss
@@ -87,4 +87,4 @@
     flex: 1 0 0;
     color: var(--m3-sys-on-surface);
   }
-}
\ No newline at end of file
+}
diff --git a/m3-foundation/assets/stylesheets/components/popper/index.scss b/m3-foundation/assets/stylesheets/components/popper/index.scss
index 5725b6a..200aba4 100644
--- a/m3-foundation/assets/stylesheets/components/popper/index.scss
+++ b/m3-foundation/assets/stylesheets/components/popper/index.scss
@@ -1,22 +1,77 @@
 @use "../../basics/motion" as m3-motion;
 
+.m3-popper-positioner {
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
 .m3-popper {
+  --m3-popper-enter-duration: #{m3-motion.duration('short4')};
+  --m3-popper-exit-duration: #{m3-motion.duration('short2')};
+  --m3-popper-opacity-enter-duration: #{m3-motion.duration('short2')};
+  --m3-popper-opacity-exit-duration: #{m3-motion.duration('short2')};
+  --m3-popper-enter-easing: #{m3-motion.easing('standard-decelerate')};
+  --m3-popper-exit-easing: #{m3-motion.easing('standard-accelerate')};
+  --m3-popper-enter-x: 0px;
+  --m3-popper-enter-y: 0px;
+  --m3-popper-origin-x: center;
+  --m3-popper-origin-y: top;
+  --m3-popper-scale-x-hidden: 0.96;
+  --m3-popper-scale-y-hidden: 0.96;
+
   visibility: hidden;
   opacity: 0;
   transition:
-    m3-motion.timing-standard-decelerate(opacity),
-    m3-motion.timing-standard-decelerate(visibility)
+    opacity var(--m3-popper-opacity-exit-duration) var(--m3-popper-exit-easing),
+    visibility 0s linear var(--m3-popper-exit-duration)
   ;
-  position: absolute;
-  top: 0;
-  left: 0;
+
+  &_animated {
+    transform-origin: var(--m3-popper-origin-x) var(--m3-popper-origin-y);
+    transform: translate(var(--m3-popper-enter-x), var(--m3-popper-enter-y)) scale(var(--m3-popper-scale-x-hidden), var(--m3-popper-scale-y-hidden));
+    will-change: opacity, transform;
+    transition:
+      opacity var(--m3-popper-opacity-exit-duration) var(--m3-popper-exit-easing),
+      transform var(--m3-popper-exit-duration) var(--m3-popper-exit-easing),
+      visibility 0s linear var(--m3-popper-exit-duration)
+    ;
+  }
+
+  &_animated#{&}_shown {
+    transform: translate(0, 0) scale(1);
+    transition:
+      opacity var(--m3-popper-opacity-enter-duration) var(--m3-popper-enter-easing),
+      transform var(--m3-popper-enter-duration) var(--m3-popper-enter-easing),
+      visibility 0s linear 0ms
+    ;
+  }
 
   &_shown {
     visibility: visible;
     opacity: 1;
     transition:
-      m3-motion.timing-standard-accelerate(opacity),
-      m3-motion.timing-standard-accelerate(visibility)
+      opacity var(--m3-popper-opacity-enter-duration) var(--m3-popper-enter-easing),
+      visibility 0s linear 0ms
     ;
   }
-}
\ No newline at end of file
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .m3-popper {
+    &_animated {
+      transform: translate(0, 0) scale(1);
+      transition:
+        opacity 0ms linear,
+        visibility 0s linear 0ms
+      ;
+    }
+
+    &_animated#{&}_shown {
+      transition:
+        opacity 0ms linear,
+        visibility 0s linear 0ms
+      ;
+    }
+  }
+}
diff --git a/m3-foundation/eslint.config.js b/m3-foundation/eslint.config.js
index 930988d..8f49a1c 100644
--- a/m3-foundation/eslint.config.js
+++ b/m3-foundation/eslint.config.js
@@ -92,4 +92,18 @@ export default [
       'max-lines-per-function': 'off',
     },
   },
+  {
+    files: [
+      '**/*.e2e.ts',
+      '**/*.e2e.tsx',
+      '**/*.e2e.test.ts',
+      '**/*.e2e.test.tsx',
+      '**/*.smote.ts',
+      '**/*.smoke.ts',
+    ],
+    rules: {
+      'max-lines': 'off',
+      'max-lines-per-function': 'off',
+    },
+  },
 ]
diff --git a/m3-foundation/lib/popper/floating.ts b/m3-foundation/lib/popper/floating.ts
index 62be158..2201180 100644
--- a/m3-foundation/lib/popper/floating.ts
+++ b/m3-foundation/lib/popper/floating.ts
@@ -9,6 +9,13 @@ import {
   shift,
 } from '@floating-ui/dom'
 
+type PopperSide = 'top' | 'bottom' | 'left' | 'right'
+
+export type PopperPositionResult = {
+  placement: string;
+  side: PopperSide;
+}
+
 const computeMiddleware = (options: Required<FloatingOptions>) => {
   const middleware: Middleware[] = []
 
@@ -34,10 +41,27 @@ const computeMiddleware = (options: Required<FloatingOptions>) => {
   return middleware
 }
 
+const toSide = (placement: string): PopperSide => placement.split('-')[0] as PopperSide
+
+const notifyWhenReferenceHidden = (
+  referenceHidden: boolean | undefined,
+  onReferenceHidden: () => void
+) => {
+  if (referenceHidden) {
+    onReferenceHidden()
+  }
+}
+
 export const computePosition = async (el: HTMLElement, target: Element, options: Required<FloatingOptions> & {
   onReferenceHidden: () => void
-}) => {
-  const { strategy, x, y, middlewareData } = await _compute(target, el, {
+}): Promise<PopperPositionResult> => {
+  const {
+    strategy,
+    x,
+    y,
+    middlewareData,
+    placement,
+  } = await _compute(target, el, {
     middleware: computeMiddleware(options),
     placement: options.placement,
     strategy: options.strategy,
@@ -45,11 +69,7 @@ export const computePosition = async (el: HTMLElement, target: Element, options:
 
   el.style.position = strategy
   el.style.transform = `translate3d(${Math.round(x)}px,${Math.round(y)}px,0)`
+  notifyWhenReferenceHidden(middlewareData.hide?.referenceHidden, options.onReferenceHidden)
 
-  if (middlewareData.hide) {
-    const { referenceHidden } = middlewareData.hide
-    if (referenceHidden) {
-      options.onReferenceHidden()
-    }
-  }
-}
\ No newline at end of file
+  return { placement, side: toSide(placement) }
+}
diff --git a/m3-foundation/types/components/popper.d.ts b/m3-foundation/types/components/popper.d.ts
index 233f286..66a51b2 100644
--- a/m3-foundation/types/components/popper.d.ts
+++ b/m3-foundation/types/components/popper.d.ts
@@ -47,6 +47,7 @@ export type ShowingOptions = {
   shown?: boolean;
   container?: Element | string;
   disabled?: boolean;
+  animated?: boolean;
 }
 
 export type PopperOptions = FloatingOptions
@@ -62,4 +63,4 @@ export type CloserEvent<E extends Event = Event> = E & {
 export type CloserTarget<E extends Element = Element> = E & {
   m3PopperCloseAll?: boolean;
   m3PopperCloserTouch?: Touch;
-}
\ No newline at end of file
+}
diff --git a/m3-react/eslint.config.js b/m3-react/eslint.config.js
index 3d7d997..e2bac2b 100644
--- a/m3-react/eslint.config.js
+++ b/m3-react/eslint.config.js
@@ -111,5 +111,19 @@ export default [
       'max-lines-per-function': 'off',
     },
   },
+  {
+    files: [
+      '**/*.e2e.ts',
+      '**/*.e2e.tsx',
+      '**/*.e2e.test.ts',
+      '**/*.e2e.test.tsx',
+      '**/*.smote.ts',
+      '**/*.smoke.ts',
+    ],
+    rules: {
+      'max-lines': 'off',
+      'max-lines-per-function': 'off',
+    },
+  },
   { ignores: ['dist/*'] },
 ]
diff --git a/m3-react/src/components/menu/M3Menu.tsx b/m3-react/src/components/menu/M3Menu.tsx
index 3aaa202..2fbbfdf 100644
--- a/m3-react/src/components/menu/M3Menu.tsx
+++ b/m3-react/src/components/menu/M3Menu.tsx
@@ -43,6 +43,7 @@ const M3Menu: FC<M3MenuProps> = ({
     offsetCrossAxis={offsetCrossAxis}
     delay={delay}
     disabled={disabled}
+    animated={true}
     detachTimeout={detachTimeout}
     className={toClassName(['m3-menu', className])}
     hideOnMissClick={true}
diff --git a/m3-react/src/components/popper/M3Popper.tsx b/m3-react/src/components/popper/M3Popper.tsx
index 9ada3f0..be7c137 100644
--- a/m3-react/src/components/popper/M3Popper.tsx
+++ b/m3-react/src/components/popper/M3Popper.tsx
@@ -59,6 +59,7 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
   overflow = [],
   delay = 0,
   disabled = false,
+  animated = false,
   detachTimeout = 5000,
   onShow = () => {},
   onHide = (_: HideReason) => {},
@@ -103,8 +104,54 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
   useWatch(onDispose, onDispose => handlers.onDispose = onDispose)
 
   const targetRef = useRef(target)
+  const positionerRef = useRef<HTMLDivElement | null>(null)
   const popperRef = useRef<HTMLDivElement | null>(null)
 
+  const applyAnimationSide = useCallback((side: 'top' | 'bottom' | 'left' | 'right') => {
+    if (!popperRef.current) {
+      return
+    }
+
+    const style = popperRef.current.style
+
+    if (side === 'top') {
+      style.setProperty('--m3-popper-origin-x', 'center')
+      style.setProperty('--m3-popper-origin-y', 'bottom')
+      style.setProperty('--m3-popper-enter-x', '0px')
+      style.setProperty('--m3-popper-enter-y', '-2px')
+      style.setProperty('--m3-popper-scale-x-hidden', '0.995')
+      style.setProperty('--m3-popper-scale-y-hidden', '0.72')
+      return
+    }
+
+    if (side === 'left') {
+      style.setProperty('--m3-popper-origin-x', 'right')
+      style.setProperty('--m3-popper-origin-y', 'center')
+      style.setProperty('--m3-popper-enter-x', '-2px')
+      style.setProperty('--m3-popper-enter-y', '0px')
+      style.setProperty('--m3-popper-scale-x-hidden', '0.72')
+      style.setProperty('--m3-popper-scale-y-hidden', '0.995')
+      return
+    }
+
+    if (side === 'right') {
+      style.setProperty('--m3-popper-origin-x', 'left')
+      style.setProperty('--m3-popper-origin-y', 'center')
+      style.setProperty('--m3-popper-enter-x', '2px')
+      style.setProperty('--m3-popper-enter-y', '0px')
+      style.setProperty('--m3-popper-scale-x-hidden', '0.72')
+      style.setProperty('--m3-popper-scale-y-hidden', '0.995')
+      return
+    }
+
+    style.setProperty('--m3-popper-origin-x', 'center')
+    style.setProperty('--m3-popper-origin-y', 'top')
+    style.setProperty('--m3-popper-enter-x', '0px')
+    style.setProperty('--m3-popper-enter-y', '2px')
+    style.setProperty('--m3-popper-scale-x-hidden', '0.995')
+    style.setProperty('--m3-popper-scale-y-hidden', '0.72')
+  }, [])
+
   const positioning = useMemo(() => ({
     placement,
     strategy,
@@ -122,18 +169,26 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
   ])
 
   const adjustDo = useCallback(async () => {
-    if (targetRef.current && popperRef.current && !state.disposed) {
-      await computePosition(popperRef.current, targetRef.current, {
+    if (targetRef.current && positionerRef.current && !state.disposed) {
+      const result = await computePosition(positionerRef.current, targetRef.current, {
         ...positioning,
         onReferenceHidden: hide,
       })
+
+      if (animated) {
+        applyAnimationSide(result.side)
+      }
     }
-  }, [positioning])
+  }, [
+    animated,
+    applyAnimationSide,
+    positioning,
+  ])
 
   const [
     adjustOn,
     adjustOff,
-  ] = useAutoAdjust(targetRef, popperRef, adjustDo)
+  ] = useAutoAdjust(targetRef, positionerRef, adjustDo)
 
   const adjust = useRecord({
     do: adjustDo,
@@ -185,7 +240,7 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
     }
   }, [])
 
-  const contains = useCallback((el: Element | null): boolean => popperRef.current?.contains(el) ?? false, [])
+  const contains = useCallback((el: Element | null): boolean => positionerRef.current?.contains(el) ?? false, [])
 
   const show = useCallback((immediately = false) => {
     if (state.disposed) {
@@ -253,8 +308,8 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
         listening.target.start(targetRef.current, targetTriggers)
       }
 
-      if (popperRef.current) {
-        listening.popper.start(popperRef.current, popperTriggers)
+      if (positionerRef.current) {
+        listening.popper.start(positionerRef.current, popperTriggers)
       }
     } else {
       state.disposed = true
@@ -328,6 +383,17 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
     }
   })
 
+  useWatch(animated, animated => {
+    if (!animated && popperRef.current) {
+      popperRef.current.style.removeProperty('--m3-popper-origin-x')
+      popperRef.current.style.removeProperty('--m3-popper-origin-y')
+      popperRef.current.style.removeProperty('--m3-popper-enter-x')
+      popperRef.current.style.removeProperty('--m3-popper-enter-y')
+      popperRef.current.style.removeProperty('--m3-popper-scale-x-hidden')
+      popperRef.current.style.removeProperty('--m3-popper-scale-y-hidden')
+    }
+  })
+
   useEffect(() => {
     const onGlobalClick = (event: CloserEvent) => onGlobalTap(event)
     const onGlobalTouch = (event: CloserEvent) => onGlobalTap(event, true)
@@ -358,14 +424,20 @@ const M3Popper: ForwardRefRenderFunction<M3PopperMethods, M3PopperProps> = ({
 
   return state.attached ? createPortal(
     <div
-      ref={popperRef}
-      className={toClassName([className, {
-        'm3-popper': true,
-        'm3-popper_shown': state.shown,
-      }])}
-      {...attrs}
+      ref={positionerRef}
+      className="m3-popper-positioner"
     >
-      {children}
+      <div
+        ref={popperRef}
+        className={toClassName([className, {
+          'm3-popper': true,
+          'm3-popper_animated': animated,
+          'm3-popper_shown': state.shown,
+        }])}
+        {...attrs}
+      >
+        {children}
+      </div>
     </div>,
     (typeof container === 'string' ? document.querySelector(container) : container) ?? document.body
   ) : null
diff --git a/m3-react/src/components/popper/types.d.ts b/m3-react/src/components/popper/types.d.ts
index 7bb14e2..2d681d4 100644
--- a/m3-react/src/components/popper/types.d.ts
+++ b/m3-react/src/components/popper/types.d.ts
@@ -30,6 +30,7 @@ export interface M3PopperProps extends HTMLAttributes<HTMLElement> {
   overflow?: OverflowBehavior[]
   delay?: number | string | Delay;
   disabled?: boolean;
+  animated?: boolean;
   detachTimeout?: null | number | string;
   onShow?: () => void;
   onHide?: (reason: HideReason) => void;
@@ -42,4 +43,4 @@ export interface M3PopperMethods {
   contains (el: Element | null): boolean;
   show (immediately?: boolean): void;
   hide (immediately?: boolean, reason?: HideReason): void;
-}
\ No newline at end of file
+}
diff --git a/m3-react/tests/M3Popper.e2e.tsx b/m3-react/tests/M3Popper.e2e.tsx
index 9516c23..5f789fc 100644
--- a/m3-react/tests/M3Popper.e2e.tsx
+++ b/m3-react/tests/M3Popper.e2e.tsx
@@ -12,6 +12,8 @@ import { createRef } from 'react'
 
 import { M3Popper } from '@/components/popper'
 
+type PopperSide = 'top' | 'bottom' | 'left' | 'right'
+
 const rect = (x: number, y: number, width: number, height: number): DOMRect => (
   DOMRect.fromRect({
     x,
@@ -26,14 +28,59 @@ const expectedX = (popper: HTMLElement, offsetCrossAxis = 0) => {
   return Math.round(100 + 20 - width / 2 + offsetCrossAxis)
 }
 
-const expectTransform = (popper: HTMLElement, x: number, y: number) => {
-  expect(popper.style.transform).toMatch(new RegExp(`^translate3d\\(${x}px,\\s*${y}px,\\s*0px\\)$`))
+const expectTransform = (positioner: HTMLElement, x: number, y: number) => {
+  expect(positioner.style.transform).toMatch(new RegExp(`^translate3d\\(${x}px,\\s*${y}px,\\s*0px\\)$`))
+}
+
+const expectAnimationSide = (popper: HTMLElement, side: PopperSide) => {
+  const expected = {
+    top: {
+      originX: 'center',
+      originY: 'bottom',
+      enterX: '0px',
+      enterY: '-2px',
+      scaleX: '0.995',
+      scaleY: '0.72',
+    },
+    bottom: {
+      originX: 'center',
+      originY: 'top',
+      enterX: '0px',
+      enterY: '2px',
+      scaleX: '0.995',
+      scaleY: '0.72',
+    },
+    left: {
+      originX: 'right',
+      originY: 'center',
+      enterX: '-2px',
+      enterY: '0px',
+      scaleX: '0.72',
+      scaleY: '0.995',
+    },
+    right: {
+      originX: 'left',
+      originY: 'center',
+      enterX: '2px',
+      enterY: '0px',
+      scaleX: '0.72',
+      scaleY: '0.995',
+    },
+  }[side]
+
+  expect(popper.classList.contains('m3-popper_animated')).toBe(true)
+  expect(popper.style.getPropertyValue('--m3-popper-origin-x')).toBe(expected.originX)
+  expect(popper.style.getPropertyValue('--m3-popper-origin-y')).toBe(expected.originY)
+  expect(popper.style.getPropertyValue('--m3-popper-enter-x')).toBe(expected.enterX)
+  expect(popper.style.getPropertyValue('--m3-popper-enter-y')).toBe(expected.enterY)
+  expect(popper.style.getPropertyValue('--m3-popper-scale-x-hidden')).toBe(expected.scaleX)
+  expect(popper.style.getPropertyValue('--m3-popper-scale-y-hidden')).toBe(expected.scaleY)
 }
 
-const parseTransform = (popper: HTMLElement) => {
-  const match = popper.style.transform.match(/translate3d\(([-\d.]+)px,\s*([-\d.]+)px,\s*0px\)/)
+const parseTransform = (positioner: HTMLElement) => {
+  const match = positioner.style.transform.match(/translate3d\(([-\d.]+)px,\s*([-\d.]+)px,\s*0px\)/)
   if (!match) {
-    throw new Error(`Unexpected transform: ${popper.style.transform}`)
+    throw new Error(`Unexpected transform: ${positioner.style.transform}`)
   }
 
   return {
@@ -44,10 +91,14 @@ const parseTransform = (popper: HTMLElement) => {
 
 const waitForPopper = async () => {
   await waitFor(() => {
+    expect(document.body.querySelector('.m3-popper-positioner')).not.toBeNull()
     expect(document.body.querySelector('.m3-popper')).not.toBeNull()
   })
 
-  return document.body.querySelector('.m3-popper') as HTMLElement
+  return {
+    positioner: document.body.querySelector('.m3-popper-positioner') as HTMLElement,
+    popper: document.body.querySelector('.m3-popper') as HTMLElement,
+  }
 }
 
 describe('m3-react/popper e2e', () => {
@@ -86,7 +137,7 @@ describe('m3-react/popper e2e', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const { positioner, popper } = await waitForPopper()
 
     vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
     const x = expectedX(popper)
@@ -96,8 +147,13 @@ describe('m3-react/popper e2e', () => {
     })
 
     await waitFor(() => {
-      expectTransform(popper, x, 80)
-      expect(popper.style.position).toBe('absolute')
+      expectTransform(positioner, x, 80)
+      expect(positioner.style.position).toBe('absolute')
+      expect(popper.classList.contains('m3-popper_animated')).toBe(false)
+      expect(popper.style.getPropertyValue('--m3-popper-enter-x')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-enter-y')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-scale-x-hidden')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-scale-y-hidden')).toBe('')
     })
   })
 
@@ -125,7 +181,7 @@ describe('m3-react/popper e2e', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const { positioner, popper } = await waitForPopper()
 
     vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
     const x = expectedX(popper, 7)
@@ -135,8 +191,8 @@ describe('m3-react/popper e2e', () => {
     })
 
     await waitFor(() => {
-      expectTransform(popper, x, 70)
-      expect(popper.style.position).toBe('absolute')
+      expectTransform(positioner, x, 70)
+      expect(positioner.style.position).toBe('absolute')
     })
   })
 
@@ -155,6 +211,7 @@ describe('m3-react/popper e2e', () => {
         overflow={[]}
         offsetMainAxis={0}
         offsetCrossAxis={0}
+        animated={true}
         detachTimeout={null}
       >
         <div>
@@ -164,7 +221,7 @@ describe('m3-react/popper e2e', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const { positioner, popper } = await waitForPopper()
 
     vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
 
@@ -175,9 +232,10 @@ describe('m3-react/popper e2e', () => {
     let bottomX = 0
     let bottomY = 0
     await waitFor(() => {
-      const point = parseTransform(popper)
+      const point = parseTransform(positioner)
       bottomX = point.x
       bottomY = point.y
+      expectAnimationSide(popper, 'bottom')
     })
 
     mounted.rerender(
@@ -189,6 +247,7 @@ describe('m3-react/popper e2e', () => {
         overflow={[]}
         offsetMainAxis={0}
         offsetCrossAxis={0}
+        animated={true}
         detachTimeout={null}
       >
         <div>
@@ -197,14 +256,11 @@ describe('m3-react/popper e2e', () => {
       </M3Popper>
     )
 
-    await act(async () => {
-      await popperRef.current?.adjust()
-    })
-
     await waitFor(() => {
-      const point = parseTransform(popper)
+      const point = parseTransform(positioner)
       expect(point.x).toBeGreaterThan(bottomX)
       expect(point.y).not.toBe(bottomY)
+      expectAnimationSide(popper, 'right')
     })
   })
 
@@ -223,6 +279,7 @@ describe('m3-react/popper e2e', () => {
         overflow={[]}
         offsetMainAxis={0}
         offsetCrossAxis={0}
+        animated={true}
         detachTimeout={null}
       >
         <div>
@@ -232,7 +289,7 @@ describe('m3-react/popper e2e', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const { positioner, popper } = await waitForPopper()
 
     vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
 
@@ -242,7 +299,7 @@ describe('m3-react/popper e2e', () => {
 
     let y0 = 0
     await waitFor(() => {
-      y0 = parseTransform(popper).y
+      y0 = parseTransform(positioner).y
     })
 
     mounted.rerender(
@@ -254,6 +311,38 @@ describe('m3-react/popper e2e', () => {
         overflow={[]}
         offsetMainAxis={10}
         offsetCrossAxis={0}
+        animated={true}
+        detachTimeout={null}
+      >
+        <div>
+          Popper content
+        </div>
+      </M3Popper>
+    )
+
+    await waitFor(() => {
+      const y1 = parseTransform(positioner).y
+      expect(Math.round(Math.abs(y1 - y0))).toBe(10)
+      expectAnimationSide(popper, 'top')
+    })
+  })
+
+  test('updates animation direction after flip when bottom placement has no space', async () => {
+    target = document.createElement('button')
+    document.body.append(target)
+
+    const popperRef = createRef<M3PopperMethods>()
+
+    const mounted = render(
+      <M3Popper
+        ref={popperRef}
+        target={target}
+        shown={true}
+        placement="bottom"
+        overflow={['flip']}
+        offsetMainAxis={0}
+        offsetCrossAxis={0}
+        animated={true}
         detachTimeout={null}
       >
         <div>
@@ -261,14 +350,55 @@ describe('m3-react/popper e2e', () => {
         </div>
       </M3Popper>
     )
+    unmount = mounted.unmount
+
+    const { popper } = await waitForPopper()
+    const y = window.innerHeight - 12
+    vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, y, 40, 20))
 
     await act(async () => {
       await popperRef.current?.adjust()
     })
 
     await waitFor(() => {
-      const y1 = parseTransform(popper).y
-      expect(Math.round(Math.abs(y1 - y0))).toBe(10)
+      expectAnimationSide(popper, 'top')
+    })
+  })
+
+  test('applies animation vectors for left placement', async () => {
+    target = document.createElement('button')
+    document.body.append(target)
+
+    const popperRef = createRef<M3PopperMethods>()
+
+    const mounted = render(
+      <M3Popper
+        ref={popperRef}
+        target={target}
+        shown={true}
+        placement="left"
+        overflow={[]}
+        offsetMainAxis={0}
+        offsetCrossAxis={0}
+        animated={true}
+        detachTimeout={null}
+      >
+        <div>
+          Popper content
+        </div>
+      </M3Popper>
+    )
+    unmount = mounted.unmount
+
+    const { popper } = await waitForPopper()
+    vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
+
+    await act(async () => {
+      await popperRef.current?.adjust()
+    })
+
+    await waitFor(() => {
+      expectAnimationSide(popper, 'left')
     })
   })
 })
diff --git a/m3-react/tests/M3Popper.test.tsx b/m3-react/tests/M3Popper.test.tsx
index 1eba043..2fc1ca7 100644
--- a/m3-react/tests/M3Popper.test.tsx
+++ b/m3-react/tests/M3Popper.test.tsx
@@ -22,10 +22,14 @@ const rect = (x: number, y: number, width: number, height: number): DOMRect => (
 
 const waitForPopper = async () => {
   await waitFor(() => {
+    expect(document.body.querySelector('.m3-popper-positioner')).not.toBeNull()
     expect(document.body.querySelector('.m3-popper')).not.toBeNull()
   })
 
-  return document.body.querySelector('.m3-popper') as HTMLElement
+  return {
+    positioner: document.body.querySelector('.m3-popper-positioner') as HTMLElement,
+    popper: document.body.querySelector('.m3-popper') as HTMLElement,
+  }
 }
 
 describe('m3-react/popper', () => {
@@ -79,7 +83,7 @@ describe('m3-react/popper', () => {
 
     fireEvent.focus(target)
 
-    const popper = await waitForPopper()
+    const { popper } = await waitForPopper()
     await waitFor(() => {
       expect(popper.classList.contains('m3-popper_shown')).toBe(true)
     })
@@ -107,7 +111,7 @@ describe('m3-react/popper', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const { popper } = await waitForPopper()
     await waitFor(() => {
       expect(popper.classList.contains('m3-popper_shown')).toBe(true)
     })
@@ -142,7 +146,10 @@ describe('m3-react/popper', () => {
     )
     unmount = mounted.unmount
 
-    const popper = await waitForPopper()
+    const {
+      popper,
+      positioner,
+    } = await waitForPopper()
 
     vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(-10000, -10000, 40, 20))
 
@@ -151,7 +158,7 @@ describe('m3-react/popper', () => {
     })
 
     await waitFor(() => {
-      expect(popper.style.position).toBe('absolute')
+      expect(positioner.style.position).toBe('absolute')
       expect(popper.classList.contains('m3-popper_shown')).toBe(false)
     })
   })
diff --git a/m3-vue/eslint.config.js b/m3-vue/eslint.config.js
index de9716d..d1083e4 100644
--- a/m3-vue/eslint.config.js
+++ b/m3-vue/eslint.config.js
@@ -161,5 +161,19 @@ export default [
       'max-lines-per-function': 'off',
     },
   },
+  {
+    files: [
+      '**/*.e2e.ts',
+      '**/*.e2e.tsx',
+      '**/*.e2e.test.ts',
+      '**/*.e2e.test.tsx',
+      '**/*.smote.ts',
+      '**/*.smoke.ts',
+    ],
+    rules: {
+      'max-lines': 'off',
+      'max-lines-per-function': 'off',
+    },
+  },
   { ignores: ['dist/*'] },
 ]
diff --git a/m3-vue/src/components/menu/M3Menu.vue b/m3-vue/src/components/menu/M3Menu.vue
index 4e4d1db..62b0df5 100644
--- a/m3-vue/src/components/menu/M3Menu.vue
+++ b/m3-vue/src/components/menu/M3Menu.vue
@@ -12,6 +12,7 @@
         :offset-cross-axis="offsetCrossAxis"
         :delay="delay"
         :disabled="disabled"
+        animated
         :detach-timeout="detachTimeout"
         v-bind="$attrs"
         class="m3-menu"
@@ -133,4 +134,4 @@ defineEmits([
   'hidden',
   'update:shown',
 ])
-</script>
\ No newline at end of file
+</script>
diff --git a/m3-vue/src/components/popper/M3Popper.vue b/m3-vue/src/components/popper/M3Popper.vue
index edd7e70..77189a5 100644
--- a/m3-vue/src/components/popper/M3Popper.vue
+++ b/m3-vue/src/components/popper/M3Popper.vue
@@ -4,15 +4,21 @@
         :to="container"
     >
         <div
-            ref="popper"
-            :class="{
-                'm3-popper': true,
-                'm3-popper_shown': state.shown,
-            }"
-            v-bind="$attrs"
-            @transitionend="state.shown ? $emit('shown') : $emit('hidden')"
+            ref="positioner"
+            class="m3-popper-positioner"
         >
-            <slot />
+            <div
+                ref="popper"
+                :class="{
+                    'm3-popper': true,
+                    'm3-popper_animated': animated,
+                    'm3-popper_shown': state.shown,
+                }"
+                v-bind="$attrs"
+                @transitionend="state.shown ? $emit('shown') : $emit('hidden')"
+            >
+                <slot />
+            </div>
         </div>
     </Teleport>
 </template>
@@ -155,6 +161,11 @@ const props = defineProps({
     default: false,
   },
 
+  animated: {
+    type: Boolean,
+    default: false,
+  },
+
   detachTimeout: {
     type: null as unknown as PropType<null | number | string>,
     validator: Or(isNull, isNumeric),
@@ -174,6 +185,7 @@ const emit = defineEmits([
 ])
 
 const target = computed(() => typeof props.target === 'function' ? props.target() : props.target?.value)
+const positioner = ref<HTMLElement | null>(null)
 const popper = ref<HTMLElement | null>(null)
 
 const positioning = computed(() => ({
@@ -197,21 +209,75 @@ const state = reactive({
 
 const delay = computed(() => normalizeDelay(props.delay))
 
+const animationBySide = {
+  top: {
+    originX: 'center',
+    originY: 'bottom',
+    enterX: '0px',
+    enterY: '-2px',
+    scaleX: '0.995',
+    scaleY: '0.72',
+  },
+  bottom: {
+    originX: 'center',
+    originY: 'top',
+    enterX: '0px',
+    enterY: '2px',
+    scaleX: '0.995',
+    scaleY: '0.72',
+  },
+  left: {
+    originX: 'right',
+    originY: 'center',
+    enterX: '-2px',
+    enterY: '0px',
+    scaleX: '0.72',
+    scaleY: '0.995',
+  },
+  right: {
+    originX: 'left',
+    originY: 'center',
+    enterX: '2px',
+    enterY: '0px',
+    scaleX: '0.72',
+    scaleY: '0.995',
+  },
+} as const
+
+const applyAnimationSide = (side: 'top' | 'bottom' | 'left' | 'right') => {
+  const style = popper.value?.style
+  if (!style) {
+    return
+  }
+
+  const preset = animationBySide[side]
+  style.setProperty('--m3-popper-origin-x', preset.originX)
+  style.setProperty('--m3-popper-origin-y', preset.originY)
+  style.setProperty('--m3-popper-enter-x', preset.enterX)
+  style.setProperty('--m3-popper-enter-y', preset.enterY)
+  style.setProperty('--m3-popper-scale-x-hidden', preset.scaleX)
+  style.setProperty('--m3-popper-scale-y-hidden', preset.scaleY)
+}
+
 const adjust = async () => {
-  if (target.value && popper.value && !state.disposed) {
-    await computePosition(popper.value, target.value, {
+  if (target.value && positioner.value && !state.disposed) {
+    const result = await computePosition(positioner.value, target.value, {
       ...positioning.value,
       onReferenceHidden: hide,
     })
+
+    if (props.animated) {
+      applyAnimationSide(result.side)
+    }
   }
 }
 
-const contains = (el: Element | null): boolean => popper.value?.contains(el) ?? false
+const contains = (el: Element | null): boolean => positioner.value?.contains(el) ?? false
 
 const {
   autoAdjustOn,
   autoAdjustOff,
-} = useAutoUpdate(target, popper, adjust)
+} = useAutoUpdate(target, positioner, adjust)
 
 const showingScheduler = new Scheduler()
 const detachScheduler = new Scheduler()
@@ -332,8 +398,8 @@ const initialize = (disposed = false): void => {
       targetListener.start(target.value, props.targetTriggers)
     }
 
-    if (popper.value) {
-      popperListener.start(popper.value, props.popperTriggers)
+    if (positioner.value) {
+      popperListener.start(positioner.value, props.popperTriggers)
     }
   } else {
     state.disposed = true
@@ -400,6 +466,17 @@ watch(() => props.disabled, disabled => {
   }
 })
 
+watch(() => props.animated, animated => {
+  if (!animated && popper.value) {
+    popper.value.style.removeProperty('--m3-popper-origin-x')
+    popper.value.style.removeProperty('--m3-popper-origin-y')
+    popper.value.style.removeProperty('--m3-popper-enter-x')
+    popper.value.style.removeProperty('--m3-popper-enter-y')
+    popper.value.style.removeProperty('--m3-popper-scale-x-hidden')
+    popper.value.style.removeProperty('--m3-popper-scale-y-hidden')
+  }
+})
+
 onMounted(() => {
   globalEvents.on('click', onGlobalClick)
   globalEvents.on('mousedown', onGlobalMousedown)
@@ -425,4 +502,4 @@ onBeforeUnmount(() => {
 
   dispose()
 })
-</script>
\ No newline at end of file
+</script>
diff --git a/m3-vue/tests/M3Popper.e2e.ts b/m3-vue/tests/M3Popper.e2e.ts
index f36008c..dc82726 100644
--- a/m3-vue/tests/M3Popper.e2e.ts
+++ b/m3-vue/tests/M3Popper.e2e.ts
@@ -16,6 +16,8 @@ import {
   vM3PopperCloser,
 } from '@/components/popper'
 
+type PopperSide = 'top' | 'bottom' | 'left' | 'right'
+
 const rect = (x: number, y: number, width: number, height: number): DOMRect => (
   DOMRect.fromRect({
     x,
@@ -25,10 +27,10 @@ const rect = (x: number, y: number, width: number, height: number): DOMRect => (
   })
 )
 
-const parseTransform = (popper: HTMLElement) => {
-  const match = popper.style.transform.match(/translate3d\(([-\d.]+)px,\s*([-\d.]+)px,\s*0px\)/)
+const parseTransform = (positioner: HTMLElement) => {
+  const match = positioner.style.transform.match(/translate3d\(([-\d.]+)px,\s*([-\d.]+)px,\s*0px\)/)
   if (!match) {
-    throw new Error(`Unexpected transform: ${popper.style.transform}`)
+    throw new Error(`Unexpected transform: ${positioner.style.transform}`)
   }
 
   return {
@@ -37,11 +39,56 @@ const parseTransform = (popper: HTMLElement) => {
   }
 }
 
-const expectY = (popper: HTMLElement, expectedY: number) => {
-  const { y } = parseTransform(popper)
+const expectY = (positioner: HTMLElement, expectedY: number) => {
+  const { y } = parseTransform(positioner)
   expect(y).toBe(expectedY)
 }
 
+const expectAnimationSide = (popper: HTMLElement, side: PopperSide) => {
+  const expected = {
+    top: {
+      originX: 'center',
+      originY: 'bottom',
+      enterX: '0px',
+      enterY: '-2px',
+      scaleX: '0.995',
+      scaleY: '0.72',
+    },
+    bottom: {
+      originX: 'center',
+      originY: 'top',
+      enterX: '0px',
+      enterY: '2px',
+      scaleX: '0.995',
+      scaleY: '0.72',
+    },
+    left: {
+      originX: 'right',
+      originY: 'center',
+      enterX: '-2px',
+      enterY: '0px',
+      scaleX: '0.72',
+      scaleY: '0.995',
+    },
+    right: {
+      originX: 'left',
+      originY: 'center',
+      enterX: '2px',
+      enterY: '0px',
+      scaleX: '0.72',
+      scaleY: '0.995',
+    },
+  }[side]
+
+  expect(popper.classList.contains('m3-popper_animated')).toBe(true)
+  expect(popper.style.getPropertyValue('--m3-popper-origin-x')).toBe(expected.originX)
+  expect(popper.style.getPropertyValue('--m3-popper-origin-y')).toBe(expected.originY)
+  expect(popper.style.getPropertyValue('--m3-popper-enter-x')).toBe(expected.enterX)
+  expect(popper.style.getPropertyValue('--m3-popper-enter-y')).toBe(expected.enterY)
+  expect(popper.style.getPropertyValue('--m3-popper-scale-x-hidden')).toBe(expected.scaleX)
+  expect(popper.style.getPropertyValue('--m3-popper-scale-y-hidden')).toBe(expected.scaleY)
+}
+
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
 
 const waitFor = async (assertion: () => void, timeoutMs = 1200) => {
@@ -62,14 +109,20 @@ const waitFor = async (assertion: () => void, timeoutMs = 1200) => {
 }
 
 const waitForPopper = async () => {
+  let positioner: HTMLElement | null = null
   let popper: HTMLElement | null = null
 
   await waitFor(() => {
+    positioner = document.body.querySelector('.m3-popper-positioner') as HTMLElement | null
     popper = document.body.querySelector('.m3-popper') as HTMLElement | null
+    expect(positioner).not.toBeNull()
     expect(popper).not.toBeNull()
   })
 
-  return popper as HTMLElement
+  return {
+    positioner: positioner as HTMLElement,
+    popper: popper as HTMLElement,
+  }
 }
 
 type MountResult = {
@@ -139,10 +192,10 @@ const createTarget = () => {
 }
 
 const setupGeometryCase = async (target: HTMLButtonElement) => {
-  const popper = await waitForPopper()
+  const elements = await waitForPopper()
 
   vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
-  return popper
+  return elements
 }
 
 const waitForShown = async (popper: HTMLElement, shown: boolean) => {
@@ -151,7 +204,6 @@ const waitForShown = async (popper: HTMLElement, shown: boolean) => {
   })
 }
 
-// eslint-disable-next-line max-lines-per-function
 describe('m3-vue/popper e2e', () => {
   let target: HTMLButtonElement | null = null
   let mounted: MountResult | null = null
@@ -178,19 +230,30 @@ describe('m3-vue/popper e2e', () => {
     vi.restoreAllMocks()
   })
   test('applies bottom placement geometry with main axis offset', async () => {
-    const popper = await setupGeometryCase(target as HTMLButtonElement)
+    const {
+      popper,
+      positioner,
+    } = await setupGeometryCase(target as HTMLButtonElement)
 
     await (mounted as MountResult).setProps({
       offsetMainAxis: 10,
     })
 
     await waitFor(() => {
-      expectY(popper, 80)
-      expect(popper.style.position).toBe('absolute')
+      expectY(positioner, 80)
+      expect(positioner.style.position).toBe('absolute')
+      expect(popper.classList.contains('m3-popper_animated')).toBe(false)
+      expect(popper.style.getPropertyValue('--m3-popper-enter-x')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-enter-y')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-scale-x-hidden')).toBe('')
+      expect(popper.style.getPropertyValue('--m3-popper-scale-y-hidden')).toBe('')
     })
   })
   test('applies cross axis offset for bottom placement', async () => {
-    const popper = await setupGeometryCase(target as HTMLButtonElement)
+    const {
+      popper,
+      positioner,
+    } = await setupGeometryCase(target as HTMLButtonElement)
 
     await (mounted as MountResult).setProps({
       offsetCrossAxis: 0,
@@ -198,8 +261,8 @@ describe('m3-vue/popper e2e', () => {
 
     let x0 = 0
     await waitFor(() => {
-      x0 = parseTransform(popper).x
-      expectY(popper, 70)
+      x0 = parseTransform(positioner).x
+      expectY(positioner, 70)
     })
 
     await (mounted as MountResult).setProps({
@@ -207,56 +270,66 @@ describe('m3-vue/popper e2e', () => {
     })
 
     await waitFor(() => {
-      const { x, y } = parseTransform(popper)
+      const { x, y } = parseTransform(positioner)
       expect(y).toBe(70)
       expect(Math.round(x - x0)).toBe(7)
-      expect(popper.style.position).toBe('absolute')
+      expect(positioner.style.position).toBe('absolute')
     })
   })
 
   test('changes geometry when placement switches from bottom to right', async () => {
-    const popper = await setupGeometryCase(target as HTMLButtonElement)
+    const {
+      popper,
+      positioner,
+    } = await setupGeometryCase(target as HTMLButtonElement)
 
     await (mounted as MountResult).setProps({
       placement: 'bottom',
       offsetMainAxis: 0,
       offsetCrossAxis: 0,
+      animated: true,
     })
 
     let bottomX = 0
     let bottomY = 0
     await waitFor(() => {
-      const point = parseTransform(popper)
+      const point = parseTransform(positioner)
       bottomX = point.x
       bottomY = point.y
+      expectAnimationSide(popper, 'bottom')
     })
 
     await (mounted as MountResult).setProps({
       placement: 'right',
       offsetMainAxis: 0,
       offsetCrossAxis: 0,
+      animated: true,
     })
 
     await waitFor(() => {
-      const point = parseTransform(popper)
+      const point = parseTransform(positioner)
       expect(point.x).toBeGreaterThan(bottomX)
       expect(point.y).not.toBe(bottomY)
-      expect(popper.style.position).toBe('absolute')
+      expectAnimationSide(popper, 'right')
     })
   })
 
   test('applies main axis offset delta for top placement', async () => {
-    const popper = await setupGeometryCase(target as HTMLButtonElement)
+    const {
+      popper,
+      positioner,
+    } = await setupGeometryCase(target as HTMLButtonElement)
 
     await (mounted as MountResult).setProps({
       placement: 'top',
       offsetMainAxis: 0,
       offsetCrossAxis: 0,
+      animated: true,
     })
 
     let y0 = 0
     await waitFor(() => {
-      y0 = parseTransform(popper).y
+      y0 = parseTransform(positioner).y
     })
 
     await (mounted as MountResult).setProps({
@@ -266,9 +339,52 @@ describe('m3-vue/popper e2e', () => {
     })
 
     await waitFor(() => {
-      const { y } = parseTransform(popper)
+      const { y } = parseTransform(positioner)
       expect(Math.round(Math.abs(y - y0))).toBe(10)
-      expect(popper.style.position).toBe('absolute')
+      expect(positioner.style.position).toBe('absolute')
+      expectAnimationSide(popper, 'top')
+    })
+  })
+
+  test('updates animation direction after flip when bottom placement has no space', async () => {
+    const { popper } = await setupGeometryCase(target as HTMLButtonElement)
+
+    await (mounted as MountResult).setProps({
+      placement: 'bottom',
+      overflow: ['flip'],
+      offsetMainAxis: 0,
+      offsetCrossAxis: 0,
+      animated: true,
+    })
+
+    vi.spyOn(target as HTMLButtonElement, 'getBoundingClientRect').mockReturnValue(rect(100, window.innerHeight - 12, 40, 20))
+
+    await (mounted as MountResult).setProps({
+      placement: 'bottom',
+      overflow: ['flip'],
+      offsetMainAxis: 0,
+      offsetCrossAxis: 0,
+      animated: true,
+    })
+
+    await waitFor(() => {
+      expectAnimationSide(popper, 'top')
+    })
+  })
+
+  test('applies animation vectors for left placement', async () => {
+    const { popper } = await setupGeometryCase(target as HTMLButtonElement)
+
+    await (mounted as MountResult).setProps({
+      placement: 'left',
+      overflow: [],
+      offsetMainAxis: 0,
+      offsetCrossAxis: 0,
+      animated: true,
+    })
+
+    await waitFor(() => {
+      expectAnimationSide(popper, 'left')
     })
   })
 
@@ -280,7 +396,7 @@ describe('m3-vue/popper e2e', () => {
       }, 'Close'), [[vM3PopperCloser]]),
     })
 
-    const popper = await waitForPopper()
+    const { popper } = await waitForPopper()
     await waitForShown(popper, true)
 
     const button = document.body.querySelector('[data-testid="closer-button"]') as HTMLButtonElement
@@ -300,7 +416,7 @@ describe('m3-vue/popper e2e', () => {
       }, 'Menu item'), [[vM3PopperCloser, true, undefined, { all: true }]]),
     })
 
-    const popper = await waitForPopper()
+    const { popper } = await waitForPopper()
     await waitForShown(popper, true)
 
     const menuItem = document.body.querySelector('[data-testid="menu-item-closer"]') as HTMLDivElement
@@ -319,7 +435,7 @@ describe('m3-vue/popper e2e', () => {
       }, 'No close'), [[vM3PopperCloser, false]]),
     })
 
-    const popper = await waitForPopper()
+    const { popper } = await waitForPopper()
     await waitForShown(popper, true)
 
     const button = document.body.querySelector('[data-testid="disabled-closer-button"]') as HTMLButtonElement

From 85cbddf273a1b5e026d461040b6d638f1d997dc7 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 20:47:01 +0400
Subject: [PATCH 02/37] feat(m3-react): Added Select and Slider parity with
 Storybook updates

Added M3Select and M3Slider components with public exports for React.

Added Storybook stories/docs for both components and country flag assets for M3Select.

Updated story sorting and reworked M3Link stories to show custom controls based on M3Link, including target=_blank for example.com links.
---
 m3-react/src/components/select/M3Select.tsx   | 258 +++++++
 m3-react/src/components/select/index.ts       |   6 +
 m3-react/src/components/slider/M3Slider.tsx   | 725 ++++++++++++++++++
 m3-react/src/components/slider/index.ts       |   7 +
 m3-react/src/index.ts                         |  19 +
 .../storybook/components/M3Link.stories.tsx   | 192 ++++-
 m3-react/storybook/components/M3Select.mdx    |   8 +
 .../storybook/components/M3Select.stories.tsx | 126 +++
 m3-react/storybook/components/M3Slider.mdx    |   8 +
 .../storybook/components/M3Slider.stories.tsx |  81 ++
 m3-react/storybook/countries/CountryFlag.tsx  |  32 +
 .../countries/CountryFlagProvider.ts          |  68 ++
 m3-react/storybook/countries/codes.ts         |  49 ++
 m3-react/storybook/countries/names.json       |  17 +
 m3-react/storybook/preview.ts                 |  26 +-
 15 files changed, 1600 insertions(+), 22 deletions(-)
 create mode 100644 m3-react/src/components/select/M3Select.tsx
 create mode 100644 m3-react/src/components/select/index.ts
 create mode 100644 m3-react/src/components/slider/M3Slider.tsx
 create mode 100644 m3-react/src/components/slider/index.ts
 create mode 100644 m3-react/storybook/components/M3Select.mdx
 create mode 100644 m3-react/storybook/components/M3Select.stories.tsx
 create mode 100644 m3-react/storybook/components/M3Slider.mdx
 create mode 100644 m3-react/storybook/components/M3Slider.stories.tsx
 create mode 100644 m3-react/storybook/countries/CountryFlag.tsx
 create mode 100644 m3-react/storybook/countries/CountryFlagProvider.ts
 create mode 100644 m3-react/storybook/countries/codes.ts
 create mode 100644 m3-react/storybook/countries/names.json

diff --git a/m3-react/src/components/select/M3Select.tsx b/m3-react/src/components/select/M3Select.tsx
new file mode 100644
index 0000000..fa56363
--- /dev/null
+++ b/m3-react/src/components/select/M3Select.tsx
@@ -0,0 +1,258 @@
+import type {
+  FC,
+  HTMLAttributes,
+  ReactElement,
+  ReactNode,
+  SVGAttributes,
+} from 'react'
+
+import type { Placement } from '@floating-ui/dom'
+
+import {
+  M3Menu,
+  M3MenuItem,
+} from '@/components/menu'
+import { M3ScrollRail } from '@/components/scroll-rail'
+import { M3TextField } from '@/components/text-field'
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import {
+  useId,
+} from '@/hooks'
+
+import { distinct } from '@/utils/content'
+import { toClassName } from '@/utils/styling'
+
+export type M3SelectOption<Value = unknown> = {
+  value: Value;
+  label: string;
+}
+
+type SelectValue<Value> = Value | null
+type SlotContext<Value> = {
+  active: boolean;
+  option: M3SelectOption<Value>;
+}
+
+export interface M3SelectProps<Value = unknown> extends HTMLAttributes<HTMLElement> {
+  id?: string;
+  value?: SelectValue<Value>;
+  label?: string;
+  options?: Array<M3SelectOption<Value>>;
+  equalPredicate?: (a: SelectValue<Value>, b: SelectValue<Value>) => boolean;
+  invalid?: boolean;
+  placeholder?: string;
+  placement?: Placement;
+  disabled?: boolean;
+  readonly?: boolean;
+  outlined?: boolean;
+  onUpdate?: (value: Value) => void;
+}
+
+const CaretIcon: FC<SVGAttributes<SVGSVGElement>> = (attrs) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="24"
+    height="24"
+    viewBox="0 0 24 24"
+    {...attrs}
+  >
+    <path d="M9.5 17L14.5 12L9.5 7V17Z" fill="currentColor" />
+  </svg>
+)
+
+const Leading: FC<{ children: ReactNode }> = props => <>{props.children}</>
+const OptionLeading: FC<{ children: ReactNode }> = props => <>{props.children}</>
+const OptionContent: FC<{ children: ReactNode }> = props => <>{props.children}</>
+
+const asRenderProp = <Context,>(value: unknown): null | ((context: Context) => ReactNode) => {
+  return typeof value === 'function' ? value as (context: Context) => ReactNode : null
+}
+
+const renderSlot = <Context,>(slot: ReactElement | null, context: Context): ReactNode => {
+  if (!slot) {
+    return null
+  }
+
+  const child = (slot.props as { children?: unknown }).children
+  const renderProp = asRenderProp<Context>(child)
+
+  return renderProp ? renderProp(context) : child as ReactNode
+}
+
+const M3Select = <Value,>({
+  id,
+  value = null,
+  label = '',
+  options = [],
+  equalPredicate = (a, b) => a === b,
+  invalid = false,
+  placeholder = '',
+  placement = 'bottom-start',
+  disabled = false,
+  readonly = false,
+  outlined = false,
+  className = '',
+  children = [],
+  onUpdate = (_: Value) => {},
+  ...attrs
+}: M3SelectProps<Value>) => {
+  const _id = useId(id, 'm3-select')
+
+  const [expanded, setExpanded] = useState(false)
+  const [shouldBeExpanded, setShouldBeExpanded] = useState(false)
+  const [rootWidth, setRootWidth] = useState(0)
+
+  const root = useRef<HTMLDivElement | null>(null)
+
+  const [slots] = useMemo(() => distinct(children, {
+    leading: Leading,
+    optionLeading: OptionLeading,
+    optionContent: OptionContent,
+  }), [children])
+
+  const text = useMemo(() => {
+    return options.find(option => equalPredicate(option.value, value))?.label ?? ''
+  }, [
+    options,
+    value,
+    equalPredicate,
+  ])
+
+  const pick = useCallback((option: M3SelectOption<Value>) => {
+    onUpdate(option.value)
+    setShouldBeExpanded(false)
+  }, [
+    onUpdate,
+  ])
+
+  useEffect(() => {
+    const _root = root.current
+    if (!_root) {
+      return
+    }
+
+    setRootWidth(_root.offsetWidth)
+
+    let frameId: number | null = null
+    const observer = new ResizeObserver(([entry]) => {
+      if (!entry) {
+        return
+      }
+
+      if (frameId !== null) {
+        cancelAnimationFrame(frameId)
+      }
+
+      frameId = requestAnimationFrame(() => setRootWidth(entry.contentRect.width))
+    })
+
+    observer.observe(_root)
+
+    return () => {
+      observer.disconnect()
+
+      if (frameId !== null) {
+        cancelAnimationFrame(frameId)
+      }
+    }
+  }, [])
+
+  return (
+    <div
+      ref={root}
+      aria-controls={_id + '-menu'}
+      aria-expanded={expanded ? 'true' : 'false'}
+      aria-disabled={disabled ? 'true' : 'false'}
+      aria-readonly={readonly ? 'true' : 'false'}
+      aria-haspopup="listbox"
+      role="combobox"
+      className={toClassName([className, {
+        'm3-select': true,
+        'm3-select_expanded': shouldBeExpanded,
+      }])}
+      {...attrs}
+    >
+      <M3TextField
+        id={_id}
+        value={text}
+        label={label}
+        placeholder={placeholder}
+        invalid={invalid}
+        readonly={readonly}
+        outlined={outlined}
+        className="m3-select__field"
+      >
+        {slots.leading ? (
+          <M3TextField.LeadingIcon>
+            {renderSlot(slots.leading, { active: shouldBeExpanded })}
+          </M3TextField.LeadingIcon>
+        ) : null}
+
+        <M3TextField.TrailingIcon>
+          <CaretIcon
+            aria-hidden="true"
+            className="m3-select__caret"
+          />
+        </M3TextField.TrailingIcon>
+      </M3TextField>
+
+      <M3Menu
+        id={_id + '-menu'}
+        shown={shouldBeExpanded}
+        target={root.current}
+        placement={placement}
+        aria-hidden={expanded ? 'false' : 'true'}
+        disabled={disabled || readonly}
+        style={{ width: rootWidth + 'px' }}
+        role="listbox"
+        onToggle={(shown) => {
+          setExpanded(shown)
+          setShouldBeExpanded(shown)
+        }}
+      >
+        <div className="m3-select__scroll-box">
+          <M3ScrollRail />
+
+          {options.map((option, index) => (
+            <M3MenuItem
+              key={index}
+              selected={equalPredicate(option.value, value)}
+              role="option"
+              onClick={() => pick(option)}
+            >
+              {slots.optionLeading ? (
+                <M3MenuItem.Leading>
+                  {renderSlot<SlotContext<Value>>(slots.optionLeading, {
+                    option,
+                    active: shouldBeExpanded,
+                  })}
+                </M3MenuItem.Leading>
+              ) : null}
+
+              {slots.optionContent ? (
+                renderSlot<SlotContext<Value>>(slots.optionContent, {
+                  option,
+                  active: shouldBeExpanded,
+                })
+              ) : option.label}
+            </M3MenuItem>
+          ))}
+        </div>
+      </M3Menu>
+    </div>
+  )
+}
+
+export default Object.assign(M3Select, {
+  Leading,
+  OptionLeading,
+  OptionContent,
+})
diff --git a/m3-react/src/components/select/index.ts b/m3-react/src/components/select/index.ts
new file mode 100644
index 0000000..0ecbae8
--- /dev/null
+++ b/m3-react/src/components/select/index.ts
@@ -0,0 +1,6 @@
+export type {
+  M3SelectProps,
+  M3SelectOption,
+} from './M3Select'
+
+export { default as M3Select } from './M3Select'
diff --git a/m3-react/src/components/slider/M3Slider.tsx b/m3-react/src/components/slider/M3Slider.tsx
new file mode 100644
index 0000000..d90ddb6
--- /dev/null
+++ b/m3-react/src/components/slider/M3Slider.tsx
@@ -0,0 +1,725 @@
+import type {
+  CSSProperties,
+  FC,
+  HTMLAttributes,
+  KeyboardEvent as ReactKeyboardEvent,
+} from 'react'
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import { compose } from '@/utils/events'
+import { toClassName } from '@/utils/styling'
+
+type AriaOptions = {
+  label?: string;
+  labelledBy?: string;
+}
+
+type DraggingHandle = 'max' | 'min'
+
+export type M3SliderType = 'single' | 'range'
+export type M3SliderValue = number | [number, number] | null
+
+export interface M3SliderProps extends HTMLAttributes<HTMLElement> {
+  type?: M3SliderType;
+  value?: M3SliderValue;
+  max?: number;
+  min?: number;
+  step?: number;
+  disabled?: boolean;
+  ariaHandle?: AriaOptions;
+  ariaHandleMax?: AriaOptions;
+  ariaHandleMin?: AriaOptions;
+  onUpdate?: (value: number | [number, number]) => void;
+}
+
+const ariaOptionsToAttrs = (options: AriaOptions): {
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+} => {
+  return {
+    ...(options.label ? { 'aria-label': options.label } : {}),
+    ...(options.labelledBy ? { 'aria-labelledby': options.labelledBy } : {}),
+  }
+}
+
+const restrict = (value: number, [min, max]: [number, number]): number => {
+  return Math.max(Math.min(max, value), min)
+}
+
+const distance = (a: number, b: number): number => Math.abs(a - b)
+const inRange = (value: number, [min, max]: [number, number]): boolean => min <= value && value <= max
+const toGap = ({ left, right }: DOMRect): [number, number] => [left, right]
+
+const withPercentage = (value: number): CSSProperties => {
+  return { '--percentage': `${value}%` } as CSSProperties
+}
+
+const getEventX = (event: globalThis.MouseEvent | globalThis.TouchEvent): number => {
+  return 'clientX' in event ? event.clientX : event.touches[0].clientX
+}
+
+const M3Slider: FC<M3SliderProps> = ({
+  type = 'single',
+  value = null,
+  max = 100,
+  min = 0,
+  step = 0,
+  disabled = false,
+  ariaHandle = {},
+  ariaHandleMax = {},
+  ariaHandleMin = {},
+  className = '',
+  onKeyDown = () => {},
+  onKeyUp = () => {},
+  onUpdate = (_value) => {},
+  ...attrs
+}) => {
+  const [dragging, setDragging] = useState<{
+    max: number | null;
+    min: number | null;
+  }>({
+    max: null,
+    min: null,
+  })
+  const [draggingHandle, setDraggingHandle] = useState<DraggingHandle | null>(null)
+
+  const keys = useRef({
+    space: false,
+  })
+
+  const track = useRef<HTMLDivElement | null>(null)
+  const fillerActive = useRef<HTMLDivElement | null>(null)
+  const handleMax = useRef<HTMLDivElement | null>(null)
+  const handleMin = useRef<HTMLDivElement | null>(null)
+  const notches = useRef<Array<HTMLDivElement | null>>([])
+  const draggingResetId = useRef<number | null>(null)
+
+  const safeStep = Math.max(step, 0)
+
+  const current = useMemo<[number, number]>(() => {
+    if (Array.isArray(value)) {
+      return value
+    }
+
+    return value === null ? [min, max] : [value, value]
+  }, [
+    max,
+    min,
+    value,
+  ])
+
+  const percentageOf = useCallback((value: number): number => {
+    const denominator = max - min
+
+    if (denominator === 0) {
+      return 0
+    }
+
+    return 100 * Math.abs(restrict(value, [min, max]) / denominator)
+  }, [
+    max,
+    min,
+  ])
+
+  const percentage = useMemo(() => {
+    const [valueMin, valueMax] = current
+
+    return {
+      max: dragging.max ?? percentageOf(valueMax),
+      min: dragging.min ?? percentageOf(valueMin),
+    }
+  }, [
+    current,
+    dragging.max,
+    dragging.min,
+    percentageOf,
+  ])
+
+  const steps = useMemo(() => {
+    const steps: number[] = []
+
+    if (safeStep > 0) {
+      let next = min + safeStep
+
+      while (next < max) {
+        steps.push(next)
+        next += safeStep
+      }
+    }
+
+    return steps
+  }, [
+    max,
+    min,
+    safeStep,
+  ])
+
+  const nearest = useCallback((value: number) => {
+    if (safeStep > 0) {
+      let prev = min
+
+      while (prev + safeStep < value) {
+        prev += safeStep
+      }
+
+      const next = prev + safeStep
+
+      return distance(value, prev) < distance(value, next) ? prev : next
+    }
+
+    return value
+  }, [
+    min,
+    safeStep,
+  ])
+
+  const getEventShare = useCallback((event: globalThis.MouseEvent | globalThis.TouchEvent): number | null => {
+    const _track = track.current
+
+    if (!_track) {
+      return null
+    }
+
+    const width = _track.offsetWidth
+    const { left, right } = _track.getBoundingClientRect()
+
+    return width > 0
+      ? (restrict(getEventX(event), [left, right]) - left) / width
+      : null
+  }, [])
+
+  const getEventValue = useCallback((event: globalThis.MouseEvent | globalThis.TouchEvent): number | null => {
+    const share = getEventShare(event)
+
+    if (share === null) {
+      return null
+    }
+
+    return nearest(min + (max - min) * share)
+  }, [
+    getEventShare,
+    max,
+    min,
+    nearest,
+  ])
+
+  const stepFor = useCallback((leap: boolean): number => {
+    const step = distance(min, max) / 100
+
+    return safeStep > 0 ? safeStep : leap ? 10 * step : step
+  }, [
+    max,
+    min,
+    safeStep,
+  ])
+
+  const nextFor = useCallback((value: number, stepOrLeap: number | boolean = false): number => {
+    const step = typeof stepOrLeap === 'boolean' ? stepFor(stepOrLeap) : stepOrLeap
+    const next = value + step
+
+    return distance(next, max) < step ? max : next
+  }, [
+    max,
+    stepFor,
+  ])
+
+  const rangeBy = useCallback((value: number, step: number): [number, number] => {
+    const restricted = restrict(value, [min, max])
+
+    if (step > 0) {
+      let prev = min
+
+      while (prev + step < restricted) {
+        prev += step
+      }
+
+      return [prev, nextFor(prev, step)]
+    }
+
+    return [restricted, restricted]
+  }, [
+    max,
+    min,
+    nextFor,
+  ])
+
+  const resetDragging = useCallback((handle: DraggingHandle) => {
+    if (draggingResetId.current !== null) {
+      cancelAnimationFrame(draggingResetId.current)
+    }
+
+    draggingResetId.current = requestAnimationFrame(() => {
+      setDragging(current => ({
+        ...current,
+        [handle]: null,
+      }))
+      draggingResetId.current = null
+    })
+  }, [])
+
+  const setValueMax = useCallback((value: number) => {
+    if (type === 'range') {
+      const [valueMin] = current
+
+      onUpdate([valueMin, Math.max(valueMin, value)])
+
+      return
+    }
+
+    onUpdate(value)
+  }, [
+    current,
+    onUpdate,
+    type,
+  ])
+
+  const setValueMin = useCallback((value: number) => {
+    if (type === 'range') {
+      const [, valueMax] = current
+
+      onUpdate([Math.min(value, valueMax), valueMax])
+    }
+  }, [
+    current,
+    onUpdate,
+    type,
+  ])
+
+  const onNotchMaxClick = useCallback(() => {
+    if (disabled) {
+      return
+    }
+
+    if (type === 'single') {
+      onUpdate(max)
+      return
+    }
+
+    onUpdate([current[0], max])
+  }, [
+    current,
+    disabled,
+    max,
+    onUpdate,
+    type,
+  ])
+
+  const onNotchMinClick = useCallback(() => {
+    if (disabled) {
+      return
+    }
+
+    if (type === 'single') {
+      onUpdate(min)
+      return
+    }
+
+    onUpdate([min, current[1]])
+  }, [
+    current,
+    disabled,
+    min,
+    onUpdate,
+    type,
+  ])
+
+  const onNotchClick = useCallback((value: number, index: number) => {
+    if (disabled || notches.current[index]?.classList.contains('m3-slider__notch_hidden')) {
+      return
+    }
+
+    if (type === 'single') {
+      onUpdate(value)
+      return
+    }
+
+    const [valueMin, valueMax] = current
+
+    onUpdate(distance(value, valueMin) < distance(value, valueMax)
+      ? [value, valueMax]
+      : [valueMin, value])
+  }, [
+    current,
+    disabled,
+    onUpdate,
+    type,
+  ])
+
+  const onKeyDownForMax = useCallback((event: ReactKeyboardEvent<HTMLElement>) => {
+    if (disabled) {
+      return
+    }
+
+    const [, valueMax] = current
+    const [rangeMin, rangeMax] = rangeBy(valueMax, stepFor(keys.current.space))
+
+    switch (event.code) {
+      case 'ArrowLeft':
+        setValueMax(rangeMin)
+        break
+      case 'ArrowRight':
+        setValueMax(rangeMax === valueMax ? nextFor(rangeMax, keys.current.space) : rangeMax)
+        break
+      case 'End':
+        setValueMax(max)
+        break
+      case 'Home':
+        setValueMax(min)
+        break
+      default:
+        break
+    }
+  }, [
+    current,
+    disabled,
+    max,
+    min,
+    nextFor,
+    rangeBy,
+    setValueMax,
+    stepFor,
+  ])
+
+  const onKeyDownForMin = useCallback((event: ReactKeyboardEvent<HTMLElement>) => {
+    if (disabled) {
+      return
+    }
+
+    const [valueMin] = current
+    const [rangeMin, rangeMax] = rangeBy(valueMin, stepFor(keys.current.space))
+
+    switch (event.code) {
+      case 'ArrowLeft':
+        setValueMin(rangeMin)
+        break
+      case 'ArrowRight':
+        setValueMin(rangeMax === valueMin ? nextFor(rangeMax, keys.current.space) : rangeMax)
+        break
+      case 'End':
+        setValueMin(max)
+        break
+      case 'Home':
+        setValueMin(min)
+        break
+      default:
+        break
+    }
+  }, [
+    current,
+    disabled,
+    max,
+    min,
+    nextFor,
+    rangeBy,
+    setValueMin,
+    stepFor,
+  ])
+
+  const onMoveMax = useCallback((event: globalThis.MouseEvent | globalThis.TouchEvent) => {
+    const value = getEventValue(event)
+    const [valueMin] = current
+
+    if (value === null) {
+      return
+    }
+
+    if (type === 'single') {
+      setDragging(current => ({
+        ...current,
+        max: percentageOf(value),
+      }))
+      setValueMax(value)
+    } else {
+      setDragging(current => ({
+        ...current,
+        max: percentageOf(Math.max(valueMin, value)),
+      }))
+      setValueMax(value)
+    }
+
+    resetDragging('max')
+  }, [
+    current,
+    getEventValue,
+    percentageOf,
+    resetDragging,
+    setValueMax,
+    type,
+  ])
+
+  const onMoveMin = useCallback((event: globalThis.MouseEvent | globalThis.TouchEvent) => {
+    if (type === 'single') {
+      return
+    }
+
+    const value = getEventValue(event)
+    const [, valueMax] = current
+
+    if (value === null) {
+      return
+    }
+
+    setDragging(current => ({
+      ...current,
+      min: percentageOf(Math.min(value, valueMax)),
+    }))
+    setValueMin(value)
+    resetDragging('min')
+  }, [
+    current,
+    getEventValue,
+    percentageOf,
+    resetDragging,
+    setValueMin,
+    type,
+  ])
+
+  const updateNotches = useCallback(() => {
+    const _active = fillerActive.current?.getBoundingClientRect()
+    const _max = handleMax.current?.getBoundingClientRect()
+    const _min = handleMin.current?.getBoundingClientRect()
+
+    notches.current.forEach((notch) => {
+      if (!notch) {
+        return
+      }
+
+      const { left: x } = notch.getBoundingClientRect()
+
+      const hidden = _max && (inRange(x - 2, toGap(_max)) || inRange(x + 2, toGap(_max))) ||
+        _min && (inRange(x - 2, toGap(_min)) || inRange(x + 2, toGap(_min)))
+
+      notch.classList.toggle('m3-slider__notch_active', !!_active && inRange(x, toGap(_active)))
+      notch.classList.toggle('m3-slider__notch_hidden', !!hidden)
+
+      notch.setAttribute('aria-hidden', hidden ? 'true' : 'false')
+    })
+  }, [])
+
+  const setNotchAt = useCallback((index: number, notch: HTMLDivElement | null) => {
+    notches.current[index] = notch
+  }, [])
+
+  useEffect(() => {
+    if (!draggingHandle || disabled) {
+      return
+    }
+
+    const onMove = (event: globalThis.MouseEvent | globalThis.TouchEvent) => {
+      draggingHandle === 'max' ? onMoveMax(event) : onMoveMin(event)
+    }
+
+    const stop = () => setDraggingHandle(null)
+
+    window.addEventListener('mousemove', onMove)
+    window.addEventListener('mouseup', stop)
+    window.addEventListener('touchmove', onMove)
+    window.addEventListener('touchcancel', stop)
+    window.addEventListener('touchend', stop)
+
+    return () => {
+      window.removeEventListener('mousemove', onMove)
+      window.removeEventListener('mouseup', stop)
+      window.removeEventListener('touchmove', onMove)
+      window.removeEventListener('touchcancel', stop)
+      window.removeEventListener('touchend', stop)
+    }
+  }, [
+    disabled,
+    draggingHandle,
+    onMoveMax,
+    onMoveMin,
+  ])
+
+  useEffect(() => {
+    if (disabled) {
+      setDraggingHandle(null)
+    }
+  }, [disabled])
+
+  useEffect(() => {
+    const updateId = requestAnimationFrame(updateNotches)
+
+    return () => cancelAnimationFrame(updateId)
+  }, [
+    current,
+    dragging.max,
+    dragging.min,
+    steps,
+    updateNotches,
+  ])
+
+  useEffect(() => {
+    const observer = new ResizeObserver(() => requestAnimationFrame(updateNotches))
+
+    if (fillerActive.current) {
+      observer.observe(fillerActive.current)
+    }
+
+    if (handleMax.current) {
+      observer.observe(handleMax.current)
+    }
+
+    if (handleMin.current) {
+      observer.observe(handleMin.current)
+    }
+
+    return () => observer.disconnect()
+  }, [
+    type,
+    updateNotches,
+  ])
+
+  useEffect(() => {
+    return () => {
+      if (draggingResetId.current !== null) {
+        cancelAnimationFrame(draggingResetId.current)
+      }
+    }
+  }, [])
+
+  return (
+    <div
+      className={toClassName([className, {
+        'm3-slider': true,
+        'm3-slider_range': type === 'range',
+        'm3-slider_stepped': steps.length > 0,
+        'm3-slider_disabled': disabled,
+      }])}
+      role="group"
+      onKeyDown={compose((event) => {
+        if (event.code === 'Space') {
+          keys.current.space = true
+        }
+      }, onKeyDown)}
+      onKeyUp={compose((event) => {
+        if (event.code === 'Space') {
+          keys.current.space = false
+        }
+      }, onKeyUp)}
+      {...attrs}
+    >
+      <div ref={track} className="m3-slider__track">
+        <div className="m3-slider__scale">
+          <div
+            ref={(el) => setNotchAt(0, el)}
+            aria-label={String(min)}
+            className="m3-slider__notch"
+            style={withPercentage(0)}
+            role="button"
+            onClick={onNotchMinClick}
+          >
+            <div className="m3-slider__notch-control" />
+          </div>
+
+          {steps.map((p, i) => (
+            <div
+              key={p}
+              ref={(el) => setNotchAt(i + 1, el)}
+              aria-label={String(p)}
+              className="m3-slider__notch"
+              style={withPercentage(percentageOf(p))}
+              role="button"
+              onClick={() => onNotchClick(p, i + 1)}
+            >
+              <div className="m3-slider__notch-control" />
+            </div>
+          ))}
+
+          <div
+            ref={(el) => setNotchAt(steps.length + 1, el)}
+            aria-label={String(max)}
+            className="m3-slider__notch"
+            style={withPercentage(100)}
+            role="button"
+            onClick={onNotchMaxClick}
+          >
+            <div className="m3-slider__notch-control" />
+          </div>
+        </div>
+
+        {type === 'range' ? (
+          <div
+            className="m3-slider__value m3-slider__value_min"
+            style={withPercentage(percentage.min)}
+            onTransitionEnd={updateNotches}
+          >
+            <div
+              ref={handleMin}
+              aria-valuemax={current[1]}
+              aria-valuemin={min}
+              aria-valuenow={current[0]}
+              aria-disabled={disabled ? 'true' : 'false'}
+              className="m3-slider__handle"
+              role="slider"
+              tabIndex={0}
+              {...ariaOptionsToAttrs(ariaHandleMin)}
+              onKeyDown={onKeyDownForMin}
+              onMouseDown={(event) => {
+                if (!disabled && event.button === 0) {
+                  setDraggingHandle('min')
+                }
+              }}
+            />
+          </div>
+        ) : null}
+
+        <div
+          className="m3-slider__value m3-slider__value_max"
+          style={withPercentage(percentage.max)}
+          onTransitionEnd={updateNotches}
+        >
+          <div
+            ref={handleMax}
+            aria-valuemax={max}
+            aria-valuemin={type === 'range' ? current[0] : min}
+            aria-valuenow={current[1]}
+            aria-disabled={disabled ? 'true' : 'false'}
+            className="m3-slider__handle"
+            role="slider"
+            tabIndex={0}
+            {...ariaOptionsToAttrs({
+              ...ariaHandle,
+              ...ariaHandleMax,
+            })}
+            onKeyDown={onKeyDownForMax}
+            onMouseDown={(event) => {
+              if (!disabled && event.button === 0) {
+                setDraggingHandle('max')
+              }
+            }}
+          />
+        </div>
+
+        {type === 'range' ? (
+          <div
+            style={withPercentage(percentage.min)}
+            className="m3-slider__filler m3-slider__filler_min"
+          />
+        ) : null}
+
+        <div
+          ref={fillerActive}
+          style={withPercentage(type === 'range'
+            ? percentage.max - percentage.min
+            : percentage.max)}
+          className="m3-slider__filler m3-slider__filler_active"
+        />
+
+        <div
+          style={withPercentage(100 - percentage.max)}
+          className="m3-slider__filler m3-slider__filler_max"
+        />
+      </div>
+    </div>
+  )
+}
+
+export default M3Slider
diff --git a/m3-react/src/components/slider/index.ts b/m3-react/src/components/slider/index.ts
new file mode 100644
index 0000000..22c0eb8
--- /dev/null
+++ b/m3-react/src/components/slider/index.ts
@@ -0,0 +1,7 @@
+export type {
+  M3SliderProps,
+  M3SliderType,
+  M3SliderValue,
+} from './M3Slider'
+
+export { default as M3Slider } from './M3Slider'
diff --git a/m3-react/src/index.ts b/m3-react/src/index.ts
index b8dcdac..05606e1 100644
--- a/m3-react/src/index.ts
+++ b/m3-react/src/index.ts
@@ -61,6 +61,17 @@ export type {
   M3ScrollRailProps,
 } from '@/components/scroll-rail'
 
+export type {
+  M3SelectOption,
+  M3SelectProps,
+} from '@/components/select'
+
+export type {
+  M3SliderProps,
+  M3SliderType,
+  M3SliderValue,
+} from '@/components/slider'
+
 export type {
   M3SwitchMethods,
   M3SwitchProps,
@@ -139,6 +150,14 @@ export {
   M3SideSheet,
 } from '@/components/side-sheet'
 
+export {
+  M3Select,
+} from '@/components/select'
+
+export {
+  M3Slider,
+} from '@/components/slider'
+
 export {
   M3Switch,
   M3SwitchScope,
diff --git a/m3-react/storybook/components/M3Link.stories.tsx b/m3-react/storybook/components/M3Link.stories.tsx
index 30ab11f..962cfb4 100644
--- a/m3-react/storybook/components/M3Link.stories.tsx
+++ b/m3-react/storybook/components/M3Link.stories.tsx
@@ -1,7 +1,181 @@
+import type {
+  CSSProperties,
+  FC,
+} from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
+import type { M3LinkProps } from '@/components/link'
 
 import { M3Link } from '@/components/link'
 
+const styles = {
+  stack: {
+    display: 'grid',
+    gap: '16px',
+    minWidth: '360px',
+  } as CSSProperties,
+  row: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: '12px',
+  } as CSSProperties,
+  section: {
+    display: 'grid',
+    gap: '8px',
+  } as CSSProperties,
+  title: {
+    margin: 0,
+    fontWeight: 600,
+    fontSize: '14px',
+  } as CSSProperties,
+  description: {
+    margin: 0,
+    color: '#5f6368',
+    fontSize: '13px',
+    lineHeight: 1.4,
+  } as CSSProperties,
+  solidButton: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '38px',
+    border: 0,
+    borderRadius: '10px',
+    padding: '0 14px',
+    fontWeight: 600,
+    fontSize: '14px',
+    color: '#ffffff',
+    background: '#0f6adf',
+    textDecoration: 'none',
+    cursor: 'pointer',
+  } as CSSProperties,
+  ghostButton: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: '38px',
+    borderRadius: '10px',
+    border: '1px solid #c4d1e0',
+    padding: '0 14px',
+    fontWeight: 600,
+    fontSize: '14px',
+    color: '#243447',
+    background: '#ffffff',
+    textDecoration: 'none',
+    cursor: 'pointer',
+  } as CSSProperties,
+  textLink: {
+    color: '#0f6adf',
+    textDecoration: 'underline',
+    textUnderlineOffset: '2px',
+    fontWeight: 500,
+  } as CSSProperties,
+  tileLink: {
+    display: 'grid',
+    gap: '4px',
+    borderRadius: '12px',
+    border: '1px solid #dbe5ef',
+    padding: '12px',
+    textDecoration: 'none',
+    color: '#1f2d3a',
+    background: '#f8fbff',
+    minWidth: '220px',
+  } as CSSProperties,
+  tileTitle: {
+    fontWeight: 600,
+    fontSize: '14px',
+  } as CSSProperties,
+  tileMeta: {
+    fontSize: '12px',
+    color: '#5f6368',
+  } as CSSProperties,
+} as const
+
+const PrimaryAction: FC<Omit<M3LinkProps, 'children'>> = (props) => {
+  return (
+    <M3Link
+      {...props}
+      style={styles.solidButton}
+    >
+      Save changes
+    </M3Link>
+  )
+}
+
+const SecondaryAction: FC<Omit<M3LinkProps, 'children'>> = (props) => {
+  return (
+    <M3Link
+      {...props}
+      style={styles.ghostButton}
+    >
+      Cancel
+    </M3Link>
+  )
+}
+
+const DocumentationLink: FC<Omit<M3LinkProps, 'children'>> = (props) => {
+  return (
+    <M3Link
+      {...props}
+      style={styles.textLink}
+    >
+      Read API reference
+    </M3Link>
+  )
+}
+
+const ResourceCardLink: FC<Omit<M3LinkProps, 'children'>> = (props) => {
+  return (
+    <M3Link
+      {...props}
+      style={styles.tileLink}
+    >
+      <span style={styles.tileTitle}>Deploy checklist</span>
+      <span style={styles.tileMeta}>8 items • 5 minutes</span>
+    </M3Link>
+  )
+}
+
+const M3LinkAsBaseStory = () => {
+  return (
+    <div style={styles.stack}>
+      <div style={styles.section}>
+        <p style={styles.title}>Custom button controls on top of `M3Link`</p>
+        <p style={styles.description}>
+          Same primitive, different presentation and semantics:
+          one remains a button, another becomes an anchor.
+        </p>
+        <div style={styles.row}>
+          <PrimaryAction />
+          <SecondaryAction />
+          <PrimaryAction href="//example.com" target="_blank" rel="noopener noreferrer" />
+        </div>
+      </div>
+
+      <div style={styles.section}>
+        <p style={styles.title}>Custom link controls on top of `M3Link`</p>
+        <p style={styles.description}>
+          Inline text-link and card-link are also built from the same base element.
+        </p>
+        <div style={styles.row}>
+          <DocumentationLink href="//example.com" target="_blank" rel="noopener noreferrer" />
+          <ResourceCardLink href="//example.com" target="_blank" rel="noopener noreferrer" />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+const PrimitiveShapeStory = (args: M3LinkProps) => {
+  const sharedStyle = args.href.length > 0 ? styles.ghostButton : styles.solidButton
+
+  return (
+    <M3Link {...args} style={sharedStyle}>
+      {args.href.length > 0 ? 'I am rendered as <a>' : 'I am rendered as <button>'}
+    </M3Link>
+  )
+}
+
 const meta = {
   title: 'Components/M3Link',
 
@@ -23,12 +197,6 @@ const meta = {
     href: '',
   },
 
-  render: (args) => (
-    <M3Link {...args} className="m3-button m3-button_filled">
-      Open
-    </M3Link>
-  ),
-
   parameters: {
     layout: 'centered',
   },
@@ -38,14 +206,10 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const AsButton: Story = {
-  args: {
-    href: '',
-  },
+export const PrimitiveShape: Story = {
+  render: (args) => <PrimitiveShapeStory {...args} />,
 }
 
-export const AsAnchor: Story = {
-  args: {
-    href: '//example.com',
-  },
+export const AsBaseForCustomControls: Story = {
+  render: () => <M3LinkAsBaseStory />,
 }
diff --git a/m3-react/storybook/components/M3Select.mdx b/m3-react/storybook/components/M3Select.mdx
new file mode 100644
index 0000000..134429c
--- /dev/null
+++ b/m3-react/storybook/components/M3Select.mdx
@@ -0,0 +1,8 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SelectStories from './M3Select.stories'
+
+<Meta of={M3SelectStories} />
+
+# M3Select
+
+Text field augmented with dropdown menu
diff --git a/m3-react/storybook/components/M3Select.stories.tsx b/m3-react/storybook/components/M3Select.stories.tsx
new file mode 100644
index 0000000..0bf4e5a
--- /dev/null
+++ b/m3-react/storybook/components/M3Select.stories.tsx
@@ -0,0 +1,126 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import type { Code } from '../countries/codes'
+import type {
+  M3SelectOption,
+  M3SelectProps,
+} from '@/components/select'
+
+import CountryFlag from '../countries/CountryFlag'
+import { M3Icon } from '@/components/icon'
+import { M3Select } from '@/components/select'
+
+import {
+  useMemo,
+  useState,
+} from 'react'
+
+import codes from '../countries/codes'
+import countries from '../countries/names.json'
+
+type CountryOption = {
+  value: Code;
+  label: string;
+}
+
+type M3SelectStoryProps<Value> = Omit<
+  M3SelectProps<Value>,
+  'value' | 'options' | 'onUpdate'
+>
+
+const M3SelectStory = (args: M3SelectStoryProps<number>) => {
+  const [value, setValue] = useState<number | null>(null)
+  const options = useMemo<Array<M3SelectOption<number>>>(() => [{
+    label: 'Option 1',
+    value: 1,
+  }, {
+    label: 'Option 2',
+    value: 2,
+  }, {
+    label: 'Option 3',
+    value: 3,
+  }], [])
+
+  return (
+    <M3Select<number>
+      value={value}
+      options={options}
+      onUpdate={(value) => setValue(value)}
+      {...args}
+    />
+  )
+}
+
+const M3SelectWithIconsStory = (args: M3SelectStoryProps<Code>) => {
+  const [countryCode, setCountryCode] = useState<Code | null>(null)
+  const countryOptions = useMemo(() => (codes.map(code => ({
+    value: code,
+    label: (countries as Record<Code, string>)[code],
+  })) as Array<CountryOption>).sort((a, b) => a.label.localeCompare(b.label)), [])
+
+  return (
+    <M3Select<Code>
+      value={countryCode}
+      options={countryOptions}
+      onUpdate={(value) => setCountryCode(value)}
+      {...args}
+    >
+      <M3Select.Leading>
+        {() => countryCode
+          ? (
+            <CountryFlag
+              code={countryCode}
+              aria-hidden="true"
+            />
+          )
+          : <M3Icon name="flag" />
+        }
+      </M3Select.Leading>
+
+      <M3Select.OptionLeading>
+        {({ option }: { option: CountryOption }) => (
+          <CountryFlag
+            code={option.value}
+            aria-hidden="true"
+          />
+        )}
+      </M3Select.OptionLeading>
+    </M3Select>
+  )
+}
+
+const meta = {
+  title: 'Components/M3Select',
+
+  component: M3Select,
+
+  argTypes: {
+    value: { control: false },
+    options: { control: false },
+    equalPredicate: { control: false },
+    onUpdate: { control: false },
+  },
+
+  render: (args) => <M3SelectStory {...args} />,
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Select>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {
+  args: {
+    label: 'Choose',
+  },
+}
+
+export const WithIcons: Story = {
+  args: {
+    label: 'Country',
+  },
+
+  render: (args) => <M3SelectWithIconsStory {...args} />,
+}
diff --git a/m3-react/storybook/components/M3Slider.mdx b/m3-react/storybook/components/M3Slider.mdx
new file mode 100644
index 0000000..8c0592f
--- /dev/null
+++ b/m3-react/storybook/components/M3Slider.mdx
@@ -0,0 +1,8 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SliderStories from './M3Slider.stories'
+
+<Meta of={M3SliderStories} />
+
+# M3Slider
+
+Sliders let users make selections from a range of values
diff --git a/m3-react/storybook/components/M3Slider.stories.tsx b/m3-react/storybook/components/M3Slider.stories.tsx
new file mode 100644
index 0000000..815694d
--- /dev/null
+++ b/m3-react/storybook/components/M3Slider.stories.tsx
@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import type {
+  M3SliderProps,
+  M3SliderValue,
+} from '@/components/slider'
+
+import { M3Slider } from '@/components/slider'
+
+import {
+  useEffect,
+  useState,
+} from 'react'
+
+const M3SliderStory = (args: M3SliderProps) => {
+  const [value, setValue] = useState<M3SliderValue>(
+    args.type === 'single' ? 50 : [25, 75]
+  )
+
+  useEffect(() => {
+    setValue(args.type === 'single' ? 50 : [25, 75])
+  }, [args.type])
+
+  return (
+    <M3Slider
+      {...args}
+      value={value}
+      onUpdate={(value) => setValue(value)}
+      style={{ width: '320px' }}
+    />
+  )
+}
+
+const meta = {
+  title: 'Components/M3Slider',
+
+  component: M3Slider,
+
+  argTypes: {
+    type: { control: false },
+    value: { control: false },
+    step: { control: 'number' },
+    onUpdate: { control: false },
+  },
+
+  args: {
+    type: 'single',
+    step: 0,
+    ariaHandleMax: {
+      label: 'Maximum',
+    },
+    ariaHandleMin: {
+      label: 'Minimum',
+    },
+  },
+
+  render: (args) => <M3SliderStory {...args} />,
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Slider>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Single: Story = {
+  args: {
+    type: 'single',
+    ariaHandle: {
+      label: 'Value',
+    },
+    ariaHandleMax: {},
+  },
+}
+
+export const Range: Story = {
+  args: {
+    type: 'range',
+  },
+}
diff --git a/m3-react/storybook/countries/CountryFlag.tsx b/m3-react/storybook/countries/CountryFlag.tsx
new file mode 100644
index 0000000..256fc2f
--- /dev/null
+++ b/m3-react/storybook/countries/CountryFlag.tsx
@@ -0,0 +1,32 @@
+import type {
+  FC,
+  SVGAttributes,
+} from 'react'
+
+import type { Code } from './codes'
+
+import provider from './CountryFlagProvider'
+
+export interface CountryFlagProps extends SVGAttributes<SVGSVGElement> {
+  code: Code;
+}
+
+const CountryFlag: FC<CountryFlagProps> = ({
+  code,
+  style,
+  ...attrs
+}) => {
+  const Sprite = provider.get(code)
+
+  return (
+    <Sprite
+      {...attrs}
+      style={{
+        ...style,
+        borderRadius: '50%',
+      }}
+    />
+  )
+}
+
+export default CountryFlag
diff --git a/m3-react/storybook/countries/CountryFlagProvider.ts b/m3-react/storybook/countries/CountryFlagProvider.ts
new file mode 100644
index 0000000..6470a65
--- /dev/null
+++ b/m3-react/storybook/countries/CountryFlagProvider.ts
@@ -0,0 +1,68 @@
+import type {
+  FC,
+  SVGProps,
+} from 'react'
+
+import type { Code } from './codes'
+
+import ad from 'flag-icons/flags/1x1/ad.svg?react'
+import am from 'flag-icons/flags/1x1/am.svg?react'
+import by from 'flag-icons/flags/1x1/by.svg?react'
+import ch from 'flag-icons/flags/1x1/ch.svg?react'
+import cn from 'flag-icons/flags/1x1/cn.svg?react'
+import de from 'flag-icons/flags/1x1/de.svg?react'
+import fi from 'flag-icons/flags/1x1/fi.svg?react'
+import fr from 'flag-icons/flags/1x1/fr.svg?react'
+import gb from 'flag-icons/flags/1x1/gb.svg?react'
+import ge from 'flag-icons/flags/1x1/ge.svg?react'
+import kg from 'flag-icons/flags/1x1/kg.svg?react'
+import kz from 'flag-icons/flags/1x1/kz.svg?react'
+import ru from 'flag-icons/flags/1x1/ru.svg?react'
+import ua from 'flag-icons/flags/1x1/ua.svg?react'
+import us from 'flag-icons/flags/1x1/us.svg?react'
+
+type FlagSprite = FC<SVGProps<SVGSVGElement>>
+
+export class CountryFlagProvider {
+  private _sprites: Map<Code, FlagSprite> = new Map()
+
+  has (code: Code): boolean {
+    return this._sprites.has(code)
+  }
+
+  get (code: Code): FlagSprite {
+    if (!this.has(code)) {
+      throw new Error('Code ' + code + ' has not been registered yet')
+    }
+
+    return this._sprites.get(code) as FlagSprite
+  }
+
+  add (code: Code, sprite: FlagSprite): void {
+    if (this.has(code)) {
+      throw new Error('Code ' + code + ' has been already registered')
+    }
+
+    this._sprites.set(code, sprite)
+  }
+}
+
+const provider = new CountryFlagProvider()
+
+provider.add('ad', ad)
+provider.add('am', am)
+provider.add('by', by)
+provider.add('ch', ch)
+provider.add('cn', cn)
+provider.add('de', de)
+provider.add('fi', fi)
+provider.add('fr', fr)
+provider.add('gb', gb)
+provider.add('ge', ge)
+provider.add('kg', kg)
+provider.add('kz', kz)
+provider.add('ru', ru)
+provider.add('ua', ua)
+provider.add('us', us)
+
+export default provider
diff --git a/m3-react/storybook/countries/codes.ts b/m3-react/storybook/countries/codes.ts
new file mode 100644
index 0000000..6766d43
--- /dev/null
+++ b/m3-react/storybook/countries/codes.ts
@@ -0,0 +1,49 @@
+export type ad = 'ad' // Andorra
+export type am = 'am' // Armenia / Հայաստան
+export type by = 'by' // Belarus / Беларусь
+export type ch = 'ch' // Switzerland
+export type cn = 'cn' // China / 中國
+export type de = 'de' // Germany / Deutschland
+export type fi = 'fi' // Finland / Suomi
+export type fr = 'fr' // France
+export type gb = 'gb' // Britain
+export type ge = 'ge' // Georgia / საქართველო
+export type kg = 'kg' // Kyrgyzstan / Кыргызстан
+export type kz = 'kz' // Kazakhstan / Қазақстан
+export type ru = 'ru' // Russia / Россия
+export type ua = 'ua' // Ukraine / Україна
+export type us = 'us' // United States of America
+
+export type Code = ad
+  | am
+  | by
+  | ch
+  | cn
+  | de
+  | fi
+  | fr
+  | gb
+  | ge
+  | kg
+  | kz
+  | ru
+  | ua
+  | us
+
+export default [
+  'ad',
+  'am',
+  'by',
+  'ch',
+  'cn',
+  'de',
+  'fi',
+  'fr',
+  'gb',
+  'ge',
+  'kg',
+  'kz',
+  'ru',
+  'ua',
+  'us',
+] as Code[]
diff --git a/m3-react/storybook/countries/names.json b/m3-react/storybook/countries/names.json
new file mode 100644
index 0000000..1348bb4
--- /dev/null
+++ b/m3-react/storybook/countries/names.json
@@ -0,0 +1,17 @@
+{
+  "ad": "Andorra",
+  "am": "Armenia",
+  "by": "Belarus",
+  "ch": "Switzerland",
+  "cn": "China",
+  "de": "Germany",
+  "fi": "Finland",
+  "fr": "France",
+  "gb": "Great Britain",
+  "ge": "Georgia",
+  "kg": "Kyrgyzstan",
+  "kz": "Kazakhstan",
+  "ru": "Russia",
+  "ua": "Ukraine",
+  "us": "United States of America"
+}
diff --git a/m3-react/storybook/preview.ts b/m3-react/storybook/preview.ts
index b613a5c..1cd3b81 100644
--- a/m3-react/storybook/preview.ts
+++ b/m3-react/storybook/preview.ts
@@ -100,14 +100,24 @@ export default {
       },
     },
     options: {
-      storySort: (a, b) => {
-        return a.id.endsWith('docs') && !b.id.endsWith('docs')
-          ? -1
-          : !a.id.endsWith('docs') && b.id.endsWith('docs')
-            ? 1
-            : a.id === b.id
-              ? 0
-              : a.id.localeCompare(b.id, undefined, { numeric: true })
+      storySort: (left, right) => {
+        const withFallback = (story, key) => typeof story[key] === 'string' ? story[key] : ''
+        const normalize = (entry) => entry && typeof entry === 'object' ? entry : {}
+        const docsRank = (story) => {
+          const id = withFallback(story, 'id')
+          const name = withFallback(story, 'name').toLowerCase()
+          return story.type === 'docs' || name === 'docs' || id.endsWith('--docs') || id.endsWith('-docs')
+            ? 0
+            : 1
+        }
+
+        const a = normalize(left)
+        const b = normalize(right)
+
+        return withFallback(a, 'title').localeCompare(withFallback(b, 'title'), undefined, { numeric: true }) ||
+          docsRank(a) - docsRank(b) ||
+          withFallback(a, 'name').localeCompare(withFallback(b, 'name'), undefined, { numeric: true }) ||
+          withFallback(a, 'id').localeCompare(withFallback(b, 'id'), undefined, { numeric: true })
       },
     },
   },

From a2bac759e23ed70833712429af9182e75150993f Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 20:55:11 +0400
Subject: [PATCH 03/37] chore: Redirected Vitest attachments to artifacts
 directories

Configured Vitest attachmentsDir for m3-react and m3-vue to write into artifacts workspace folders.

Aligned e2e projects to store attachments alongside Playwright traces and screenshots under artifacts.
---
 m3-react/vitest.config.e2e.ts |  1 +
 m3-react/vitest.config.ts     | 21 ++++++++++++++-------
 m3-vue/vitest.config.e2e.ts   |  1 +
 m3-vue/vitest.config.ts       |  7 +++++++
 4 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/m3-react/vitest.config.e2e.ts b/m3-react/vitest.config.e2e.ts
index 7e60021..ce0869c 100644
--- a/m3-react/vitest.config.e2e.ts
+++ b/m3-react/vitest.config.e2e.ts
@@ -19,6 +19,7 @@ export default mergeConfig(viteConfig, defineConfig({
   test: {
     name: 'm3-react-e2e',
     globals: true,
+    attachmentsDir: join(__artifacts, 'playwright', 'attachments'),
     include: [
       'tests/**/*.e2e.tsx',
     ],
diff --git a/m3-react/vitest.config.ts b/m3-react/vitest.config.ts
index be1257b..12e14df 100644
--- a/m3-react/vitest.config.ts
+++ b/m3-react/vitest.config.ts
@@ -1,14 +1,21 @@
 import {
-    defineConfig,
-    mergeConfig,
+  defineConfig,
+  mergeConfig,
 } from 'vitest/config'
 
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import viteConfig from './vite.config'
 
+const __parent = fileURLToPath(new URL('../', import.meta.url))
+const __artifacts = join(__parent, 'artifacts', 'm3-react')
+
 export default mergeConfig(viteConfig, defineConfig({
-    test: {
-        name: 'm3-react',
-        globals: true,
-        environment: 'jsdom',
-    },
+  test: {
+    name: 'm3-react',
+    globals: true,
+    environment: 'jsdom',
+    attachmentsDir: join(__artifacts, 'vitest', 'attachments'),
+  },
 }))
diff --git a/m3-vue/vitest.config.e2e.ts b/m3-vue/vitest.config.e2e.ts
index a16a15d..2026427 100644
--- a/m3-vue/vitest.config.e2e.ts
+++ b/m3-vue/vitest.config.e2e.ts
@@ -19,6 +19,7 @@ export default mergeConfig(viteConfig, defineConfig({
   test: {
     name: 'm3-vue-e2e',
     globals: true,
+    attachmentsDir: join(__artifacts, 'playwright', 'attachments'),
     include: [
       'tests/**/*.e2e.ts',
     ],
diff --git a/m3-vue/vitest.config.ts b/m3-vue/vitest.config.ts
index c2e866c..c668260 100644
--- a/m3-vue/vitest.config.ts
+++ b/m3-vue/vitest.config.ts
@@ -3,12 +3,19 @@ import {
   mergeConfig,
 } from 'vitest/config'
 
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import viteConfig from './vite.config'
 
+const __parent = fileURLToPath(new URL('../', import.meta.url))
+const __artifacts = join(__parent, 'artifacts', 'm3-vue')
+
 export default mergeConfig(viteConfig, defineProject({
   test: {
     name: 'm3-vue',
     globals: true,
     environment: 'jsdom',
+    attachmentsDir: join(__artifacts, 'vitest', 'attachments'),
   },
 }))

From 8ff73ca4c890d6292035ba3c775f2317e7b07d84 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 21:14:56 +0400
Subject: [PATCH 04/37] chore: Added popper evidence notes and ignored .env

Added evidence/popper.md with collected popper animation sources and extracted facts for future work.

Ignored .env in .gitignore to prevent accidental token leakage.
---
 .gitignore         |  1 +
 evidence/popper.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 evidence/popper.md

diff --git a/.gitignore b/.gitignore
index e3009e6..7e65074 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,4 @@ node_modules/
 .pnp.loader.mjs
 .yarnrc.yml
 *storybook.log
+.env
diff --git a/evidence/popper.md b/evidence/popper.md
new file mode 100644
index 0000000..b0468ac
--- /dev/null
+++ b/evidence/popper.md
@@ -0,0 +1,70 @@
+# Popper Animation Evidence
+Date: 2026-02-22
+
+## Sources
+### Primary references
+- User-provided design reference video:
+  - https://firebasestorage.googleapis.com/v0/b/design-spec/o/projects%2Fgoogle-material-3%2Fimages%2Fmhlk1jwz-GM3_Menus_Guidelines%2001_IA_v01.mp4?alt=media&token=2e7dfcc9-2447-4808-8234-83c313d82df8
+- Material 3 motion pages:
+  - https://m3.material.io/styles/motion/overview
+  - https://m3.material.io/foundations/motion/applying-easing-and-duration
+  - https://m3.material.io/styles/motion/easing-and-duration/tokens-specs
+
+### Token/easing references used as practical source of truth
+- Flutter generated motion tokens:
+  - https://flutter.googlesource.com/mirrors/packages/+/refs/tags/google_maps_flutter-v2.7.0/packages/flutter/lib/src/material/motion.dart
+- Flutter API docs for durations and easing:
+  - https://api.flutter.dev/flutter/material/Durations-class.html
+  - https://api.flutter.dev/flutter/material/Easing/standard-constant.html
+  - https://api.flutter.dev/flutter/material/Easing/standardAccelerate-constant.html
+  - https://api.flutter.dev/flutter/material/Easing/standardDecelerate-constant.html
+  - https://api.flutter.dev/flutter/material/Easing/emphasizedAccelerate-constant.html
+  - https://api.flutter.dev/flutter/material/Easing/emphasizedDecelerate-constant.html
+
+### Internal empirical source
+- Implementation and local validation log in `draft.txt`:
+  - wrapper split (`.m3-popper-positioner` + `.m3-popper`)
+  - updated E2E assertions
+  - local check commands and outcomes
+
+## Extracted Facts
+### Direct facts
+1. Positioning and animation transforms conflict if both are applied to the same element.
+2. Splitting responsibilities into two elements is technically viable:
+   - outer element handles geometry (`absolute/top/left/transform` from floating-ui),
+   - inner element handles visual animation (`transform/opacity/visibility`).
+3. Show ordering matters: first position (`await adjust`), then reveal content.
+4. Animation direction must use the effective side after flip (actual placement), not requested placement.
+5. Headless access to `m3.material.io` pages may be limited (JS-required shell), so token tables were taken from official generated/tokenized sources.
+6. Local verification was reported as green after stabilization:
+   - `tsc` for foundation/react/vue,
+   - `eslint`,
+   - unit and e2e checks for popper,
+   - combined coverage run (`80.11%`).
+
+### Motion token facts (from token references)
+1. Duration token scale:
+   - short: 50/100/150/200 ms,
+   - medium: 250/300/350/400 ms,
+   - long: 450/500/550/600 ms,
+   - extra long: 700/800/900/1000 ms.
+2. Easing token curves:
+   - standard: `cubic-bezier(0.2, 0.0, 0.0, 1.0)`,
+   - standardAccelerate: `cubic-bezier(0.3, 0.0, 1.0, 1.0)`,
+   - standardDecelerate: `cubic-bezier(0.0, 0.0, 0.0, 1.0)`,
+   - emphasizedAccelerate: `cubic-bezier(0.3, 0.0, 0.8, 0.15)`,
+   - emphasizedDecelerate: `cubic-bezier(0.05, 0.7, 0.1, 1.0)`,
+   - linear: `cubic-bezier(0.0, 0.0, 1.0, 1.0)`.
+
+### Inferences used for implementation tuning
+1. Enter animation should prefer decelerate-family easing, exit should prefer accelerate-family easing.
+2. Perceived "menu unfolding from anchor point" depends on:
+   - side-aware `transform-origin`,
+   - axis-dominant scale (uncollapse) with small translation offset.
+3. Candidate presets for iterative tuning:
+   - `short3/short1` or `short4/short2`,
+   - decelerate for enter + accelerate for exit.
+
+## Notes for future work
+- Keep parity of popper behavior checks in React and Vue E2E.
+- Freeze chosen duration/easing pair in tests via computed-style assertions to prevent regressions.

From 56fff7fc4cbbb92bee373276e681c11fc5eef222 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 21:57:48 +0400
Subject: [PATCH 05/37] docs: Storybook MDX resources and navigation docs were
 aligned

---
 m3-react/storybook/components/M3Button.mdx    | 12 +++++++++
 m3-react/storybook/components/M3Card.mdx      | 13 +++++++++-
 m3-react/storybook/components/M3Checkbox.mdx  | 13 ++++++++--
 m3-react/storybook/components/M3Dialog.mdx    | 17 ++++++++++++-
 m3-react/storybook/components/M3FabButton.mdx | 19 ++++++++++----
 .../storybook/components/M3IconButton.mdx     | 25 ++++++++++++++++---
 .../storybook/components/M3Navigation.mdx     | 17 +++++++++++++
 .../storybook/components/M3RichTooltip.mdx    | 14 +++++++++++
 m3-react/storybook/components/M3Select.mdx    | 20 ++++++++++++++-
 m3-react/storybook/components/M3Slider.mdx    | 20 ++++++++++++++-
 m3-react/storybook/components/M3Switch.mdx    | 12 ++++++++-
 m3-react/storybook/components/M3TextField.mdx | 13 +++++++++-
 .../examples/dialog/DialogConfirmation.tsx    | 12 ++++++---
 .../examples/rich-tooltip/DeleteTooltip.tsx   |  5 ++--
 m3-vue/storybook/components/M3Button.mdx      | 12 +++++++++
 m3-vue/storybook/components/M3Card.mdx        | 13 +++++++++-
 m3-vue/storybook/components/M3Checkbox.mdx    | 13 ++++++++--
 m3-vue/storybook/components/M3Dialog.mdx      | 17 ++++++++++++-
 m3-vue/storybook/components/M3FabButton.mdx   | 19 ++++++++++----
 m3-vue/storybook/components/M3IconButton.mdx  | 20 +++++++++++++--
 m3-vue/storybook/components/M3Navigation.mdx  | 17 +++++++++++++
 m3-vue/storybook/components/M3RichTooltip.mdx | 14 +++++++++++
 m3-vue/storybook/components/M3Select.mdx      | 20 ++++++++++++++-
 m3-vue/storybook/components/M3Slider.mdx      | 20 ++++++++++++++-
 m3-vue/storybook/components/M3Switch.mdx      | 12 ++++++++-
 m3-vue/storybook/components/M3TextField.mdx   | 13 +++++++++-
 .../examples/dialog/DialogConfirmation.vue    | 12 ++++++---
 .../examples/rich-tooltip/DeleteTooltip.vue   |  5 ++--
 28 files changed, 378 insertions(+), 41 deletions(-)

diff --git a/m3-react/storybook/components/M3Button.mdx b/m3-react/storybook/components/M3Button.mdx
index 62b448a..866a658 100644
--- a/m3-react/storybook/components/M3Button.mdx
+++ b/m3-react/storybook/components/M3Button.mdx
@@ -10,6 +10,12 @@ import * as M3ButtonStories from './M3Button.stories'
 
 Common buttons prompt most actions in a UI
 
+## Accessibility semantics
+
+- Use a clear text label for action buttons.
+- For icon-only actions, provide `aria-label`.
+- Keep disabled actions unavailable through the `disabled` state.
+
 <Unstyled>
   <p style={{ display: 'flex', gap: '16px' }}>
     <M3Button>Edit</M3Button>
@@ -27,3 +33,9 @@ Common buttons prompt most actions in a UI
     <M3Button appearance={'tonal'}><M3Icon name={'edit'} /> Edit</M3Button>
   </p>
 </Unstyled>
+
+## Resources
+
+- [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
+- [M3 Buttons guidelines](https://m3.material.io/components/buttons/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Card.mdx b/m3-react/storybook/components/M3Card.mdx
index eb1265a..eefef04 100644
--- a/m3-react/storybook/components/M3Card.mdx
+++ b/m3-react/storybook/components/M3Card.mdx
@@ -10,9 +10,20 @@ import * as M3CardStories from './M3Card.stories'
 
 Cards display content and actions about a single subject
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Use non-interactive cards as plain content containers.
+- For interactive cards, expose actions with semantic controls (`button` / `link`).
+- Keep a clear heading hierarchy inside cards for screen reader navigation.
 
 <Unstyled style={{ display: 'flex', flexWrap: 'wrap', gap: '16px' }}>
   <LiveMusic1 interactive={true} />
   <LiveMusic2 interactive={true} />
 </Unstyled>
+
+## Resources
+
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Cards guidelines](https://m3.material.io/components/cards/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Checkbox.mdx b/m3-react/storybook/components/M3Checkbox.mdx
index b1cbe34..3746709 100644
--- a/m3-react/storybook/components/M3Checkbox.mdx
+++ b/m3-react/storybook/components/M3Checkbox.mdx
@@ -9,9 +9,11 @@ import * as M3CheckboxStories from './M3Checkbox.stories'
 
 Checkboxes let users select one or more items from a list, or turn an item on or off
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
 
-[Guidelines](https://m3.material.io/components/checkbox/guidelines)
+- Every checkbox needs a visible text label.
+- Group related checkboxes under a shared group label (`fieldset/legend` or `aria-labelledby`).
+- Use indeterminate state only for partial parent-selection states.
 
 ### Regular list
 
@@ -50,3 +52,10 @@ Checkboxes let users select one or more items from a list, or turn an item on or
     }]}
   />
 </Unstyled>
+
+## Resources
+
+- [M3 Checkbox overview](https://m3.material.io/components/checkbox/overview)
+- [M3 Checkbox guidelines](https://m3.material.io/components/checkbox/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
diff --git a/m3-react/storybook/components/M3Dialog.mdx b/m3-react/storybook/components/M3Dialog.mdx
index 5051a17..ce7d43c 100644
--- a/m3-react/storybook/components/M3Dialog.mdx
+++ b/m3-react/storybook/components/M3Dialog.mdx
@@ -3,8 +3,23 @@ import DialogConfirmation from '../examples/dialog/DialogConfirmation'
 
 # Dialogs
 
+Dialogs communicate important information and block the underlying interface until the user responds.
+
+## Accessibility semantics
+
+- Set `role="dialog"` (or `alertdialog` for urgent confirmations).
+- Provide `aria-modal="true"` for modal flows.
+- Connect title and description with `aria-labelledby` and `aria-describedby`.
+- Keep focus inside the dialog while it is opened.
+
 <Unstyled>
   <div className="mb-3">
     <DialogConfirmation />
   </div>
-</Unstyled>
\ No newline at end of file
+</Unstyled>
+
+## Resources
+
+- [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
+- [M3 Dialogs guidelines](https://m3.material.io/components/dialogs/guidelines)
+- [WAI-ARIA APG: Modal Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
diff --git a/m3-react/storybook/components/M3FabButton.mdx b/m3-react/storybook/components/M3FabButton.mdx
index 70a9400..8862943 100644
--- a/m3-react/storybook/components/M3FabButton.mdx
+++ b/m3-react/storybook/components/M3FabButton.mdx
@@ -10,11 +10,13 @@ import * as M3FabButtonStories from './M3FabButton.stories'
 
 Floating action buttons (FABs) help people take primary actions
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
 
-### Standard FABs
+- Icon-only FABs require an accessible name via `aria-label`.
+- Keep FAB usage focused on the primary action on a given surface.
+- Extended FABs should keep a short visible label.
 
-[Guidelines](https://m3.material.io/components/floating-action-button/guidelines)
+### Standard FABs
 
 <Unstyled>
   <p style={{ display: 'flex', gap: '16px' }}>
@@ -27,8 +29,6 @@ Floating action buttons (FABs) help people take primary actions
 
 ### Extended FABs
 
-[Guidelines](https://m3.material.io/components/extended-fab/guidelines)
-
 <Unstyled>
   <p style={{ display: 'flex', gap: '16px' }}>
     <M3FabButton variant={'surface'}><M3Icon name={'edit'} /> New task</M3FabButton>
@@ -37,3 +37,12 @@ Floating action buttons (FABs) help people take primary actions
     <M3FabButton variant={'tertiary'}><M3Icon name={'edit'} /> New task</M3FabButton>
   </p>
 </Unstyled>
+
+## Resources
+
+- [M3 FAB overview](https://m3.material.io/components/floating-action-button/overview)
+- [M3 FAB guidelines](https://m3.material.io/components/floating-action-button/guidelines)
+- [M3 Extended FAB overview](https://m3.material.io/components/extended-fab/overview)
+- [M3 Extended FAB guidelines](https://m3.material.io/components/extended-fab/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3IconButton.mdx b/m3-react/storybook/components/M3IconButton.mdx
index deb322b..824d5ba 100644
--- a/m3-react/storybook/components/M3IconButton.mdx
+++ b/m3-react/storybook/components/M3IconButton.mdx
@@ -10,11 +10,30 @@ import * as M3IconButtonStories from './M3IconButton.stories'
 
 Icon buttons help people take minor actions with one tap
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Icon-only controls must include an accessible name (`aria-label`).
+- Toggleable icon buttons should expose state with `aria-pressed`.
+- Use icon buttons for minor actions, not for primary destructive actions.
 
 <Unstyled>
   <p style={{ display: 'flex', gap: '16px' }}>
-    <M3IconButton appearance="filled"><M3Icon name="favorite" /></M3IconButton>
-    <M3IconButton appearance="filled" toggleable={true}><M3Icon name="favorite" /></M3IconButton>
+    <M3IconButton appearance="filled" aria-label="Mark as favorite"><M3Icon name="favorite" /></M3IconButton>
+    <M3IconButton
+      appearance="filled"
+      toggleable={true}
+      selected={true}
+      aria-label="Toggle favorite"
+      aria-pressed="true"
+    >
+      <M3Icon name="favorite" />
+    </M3IconButton>
   </p>
 </Unstyled>
+
+## Resources
+
+- [M3 Icon Buttons overview](https://m3.material.io/components/icon-buttons/overview)
+- [M3 Icon Buttons guidelines](https://m3.material.io/components/icon-buttons/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Navigation.mdx b/m3-react/storybook/components/M3Navigation.mdx
index 856bd5a..d6f4660 100644
--- a/m3-react/storybook/components/M3Navigation.mdx
+++ b/m3-react/storybook/components/M3Navigation.mdx
@@ -4,3 +4,20 @@ import * as M3NavigationStories from './M3Navigation.stories'
 <Meta of={M3NavigationStories} />
 
 # Navigation
+
+Navigation components help users move between top-level destinations.
+
+## Accessibility semantics
+
+- Treat the container as a navigation landmark and provide a clear label when needed.
+- Keep destination labels concise and unique.
+- Expose active destination state consistently in routed integrations.
+
+## Resources
+
+- [M3 Navigation bar overview](https://m3.material.io/components/navigation-bar/overview)
+- [M3 Navigation rail overview](https://m3.material.io/components/navigation-rail/overview)
+- [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
+- [Storybook: NavigationDrawer](?path=/story/components-m3navigation--navigation-drawer)
+- [Storybook: NavigationRail](?path=/story/components-m3navigation--navigation-rail)
+- [WAI-ARIA APG: Landmark Regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)
diff --git a/m3-react/storybook/components/M3RichTooltip.mdx b/m3-react/storybook/components/M3RichTooltip.mdx
index 1bab341..8ff5b73 100644
--- a/m3-react/storybook/components/M3RichTooltip.mdx
+++ b/m3-react/storybook/components/M3RichTooltip.mdx
@@ -4,8 +4,22 @@ import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip'
 
 # Rich tooltip
 
+Rich tooltips provide contextual, supplementary information near a trigger element.
+
+## Accessibility semantics
+
+- Link trigger and tooltip with `aria-describedby`.
+- Keep tooltip text concise and task-relevant.
+- Avoid using tooltips as the only way to convey critical information.
+
 <Unstyled>
   <div className="m3-panel m3-panel_elevated-1 my-4" style={{ maxWidth: '360px' }}>
     <DeleteTooltip />
   </div>
 </Unstyled>
+
+## Resources
+
+- [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
+- [M3 Tooltips guidelines](https://m3.material.io/components/tooltips/guidelines)
+- [WAI-ARIA APG: Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
diff --git a/m3-react/storybook/components/M3Select.mdx b/m3-react/storybook/components/M3Select.mdx
index 134429c..b16b8f6 100644
--- a/m3-react/storybook/components/M3Select.mdx
+++ b/m3-react/storybook/components/M3Select.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
 import * as M3SelectStories from './M3Select.stories'
 
 <Meta of={M3SelectStories} />
@@ -6,3 +6,21 @@ import * as M3SelectStories from './M3Select.stories'
 # M3Select
 
 Text field augmented with dropdown menu
+
+## Accessibility semantics
+
+- `M3Select` exposes combobox semantics with a listbox popup and option items.
+- Provide a visible label through `label` or an explicit aria-label/aria-labelledby strategy.
+- Keep option labels unique and meaningful for screen readers.
+
+## Demo
+
+<Canvas of={M3SelectStories.Standard} />
+<Canvas of={M3SelectStories.WithIcons} />
+
+## Resources
+
+- [M3 Menus overview](https://m3.material.io/components/menus/overview)
+- [M3 Menus guidelines](https://m3.material.io/components/menus/guidelines)
+- [WAI-ARIA APG: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [WAI-ARIA APG: Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)
diff --git a/m3-react/storybook/components/M3Slider.mdx b/m3-react/storybook/components/M3Slider.mdx
index 8c0592f..f055726 100644
--- a/m3-react/storybook/components/M3Slider.mdx
+++ b/m3-react/storybook/components/M3Slider.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
 import * as M3SliderStories from './M3Slider.stories'
 
 <Meta of={M3SliderStories} />
@@ -6,3 +6,21 @@ import * as M3SliderStories from './M3Slider.stories'
 # M3Slider
 
 Sliders let users make selections from a range of values
+
+## Accessibility semantics
+
+- Each slider handle must have an accessible name (`ariaHandle`, `ariaHandleMin`, `ariaHandleMax`).
+- Keep numeric ranges and steps predictable and documented for users.
+- Support keyboard adjustments (Arrow, Home, End) for all handles.
+
+## Demo
+
+<Canvas of={M3SliderStories.Single} />
+<Canvas of={M3SliderStories.Range} />
+
+## Resources
+
+- [M3 Sliders overview](https://m3.material.io/components/sliders/overview)
+- [M3 Sliders guidelines](https://m3.material.io/components/sliders/guidelines)
+- [WAI-ARIA APG: Slider Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)
+- [WAI-ARIA APG: Multi-Thumb Slider Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)
diff --git a/m3-react/storybook/components/M3Switch.mdx b/m3-react/storybook/components/M3Switch.mdx
index 5c50ca7..e878f4e 100644
--- a/m3-react/storybook/components/M3Switch.mdx
+++ b/m3-react/storybook/components/M3Switch.mdx
@@ -15,6 +15,14 @@ import * as M3SwitchStories from './M3Switch.stories'
   * Make sure the switch’s selection (on or off) is visible at a glance
 </Unstyled>
 
+## Accessibility semantics
+
+<Unstyled>
+  * Keep a visible label next to each switch control.
+  * Expose checked state via `role="switch"` and `aria-checked`.
+  * Use switches for immediate on/off state changes, not for multi-choice selections.
+</Unstyled>
+
 ### Demo
 
 <Unstyled>
@@ -24,9 +32,11 @@ import * as M3SwitchStories from './M3Switch.stories'
   </div>
 </Unstyled>
 
-### Resources
+## Resources
 
 <Unstyled>
   * [Guidelines](https://m3.material.io/components/switch/guidelines)
+  * [M3 Switch overview](https://m3.material.io/components/switch/overview)
   * [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+  * [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
 </Unstyled>
diff --git a/m3-react/storybook/components/M3TextField.mdx b/m3-react/storybook/components/M3TextField.mdx
index f746e38..be61cc9 100644
--- a/m3-react/storybook/components/M3TextField.mdx
+++ b/m3-react/storybook/components/M3TextField.mdx
@@ -10,7 +10,18 @@ import * as M3TextFieldStories from './M3TextField.stories'
 
 Text fields let users enter text into a UI.
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Provide a persistent text label (`label` prop or explicit aria-labelledby).
+- Use `aria-invalid` together with helper/support text for validation feedback.
+- For long-form input, prefer multiline mode (`textarea`) with the same labeling strategy.
 
 <TextFieldExamples />
 </Unstyled>
+
+## Resources
+
+- [M3 Text Fields overview](https://m3.material.io/components/text-fields/overview)
+- [M3 Text Fields guidelines](https://m3.material.io/components/text-fields/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI Tutorials: Form Labels](https://www.w3.org/WAI/tutorials/forms/labels/)
diff --git a/m3-react/storybook/examples/dialog/DialogConfirmation.tsx b/m3-react/storybook/examples/dialog/DialogConfirmation.tsx
index 1c5a5f1..83c88c5 100644
--- a/m3-react/storybook/examples/dialog/DialogConfirmation.tsx
+++ b/m3-react/storybook/examples/dialog/DialogConfirmation.tsx
@@ -8,6 +8,8 @@ import { useState } from 'react'
 
 const DialogConfirmation: FC = () => {
   const [opened, setOpened] = useState(false)
+  const dialogTitleId = 'dialog-confirmation-title'
+  const dialogDescriptionId = 'dialog-confirmation-description'
 
   return (
     <>
@@ -21,7 +23,9 @@ const DialogConfirmation: FC = () => {
       <M3Dialog
         opened={opened}
         role="dialog"
-        aria-live="assertive"
+        aria-modal="true"
+        aria-labelledby={dialogTitleId}
+        aria-describedby={dialogDescriptionId}
         onToggle={setOpened}
       >
         <M3Dialog.Icon>
@@ -29,10 +33,12 @@ const DialogConfirmation: FC = () => {
         </M3Dialog.Icon>
 
         <M3Dialog.Header>
-          <h3>Permanently delete?</h3>
+          <h3 id={dialogTitleId}>Permanently delete?</h3>
         </M3Dialog.Header>
 
-        Deleting the selected messages will also remove them from all synced devices.
+        <p id={dialogDescriptionId}>
+          Deleting the selected messages will also remove them from all synced devices.
+        </p>
 
         <M3Dialog.Footer>
           <M3Button
diff --git a/m3-react/storybook/examples/rich-tooltip/DeleteTooltip.tsx b/m3-react/storybook/examples/rich-tooltip/DeleteTooltip.tsx
index ee51cd9..e244940 100644
--- a/m3-react/storybook/examples/rich-tooltip/DeleteTooltip.tsx
+++ b/m3-react/storybook/examples/rich-tooltip/DeleteTooltip.tsx
@@ -8,14 +8,15 @@ import { useTarget } from '@/hooks'
 
 const DeleteTooltip: FC = () => {
   const [target, setTarget] = useTarget()
+  const tooltipId = 'delete-tooltip-description'
 
   return (
     <>
-      <M3Button effects={[setTarget]}>
+      <M3Button effects={[setTarget]} aria-describedby={tooltipId}>
         Delete
       </M3Button>
 
-      <M3RichTooltip target={target} hideOnMissClick={true}>
+      <M3RichTooltip id={tooltipId} target={target} hideOnMissClick={true}>
         <M3RichTooltip.Heading>
           Deleting item
         </M3RichTooltip.Heading>
diff --git a/m3-vue/storybook/components/M3Button.mdx b/m3-vue/storybook/components/M3Button.mdx
index 13c6818..da1b2eb 100644
--- a/m3-vue/storybook/components/M3Button.mdx
+++ b/m3-vue/storybook/components/M3Button.mdx
@@ -9,6 +9,12 @@ import * as M3ButtonStories from './M3Button.stories'
 
 Common buttons prompt most actions in a UI
 
+## Accessibility semantics
+
+- Use a clear text label for action buttons.
+- For icon-only actions, provide `aria-label`.
+- Keep disabled actions unavailable through the `disabled` state.
+
 <p style={{ display: 'flex', gap: '16px' }}>
   <Inline tag={'span'} is={M3Button} label={'Edit'} />
   <Inline tag={'span'} is={M3Button} label={'Edit'} appearance={'elevated'} />
@@ -24,3 +30,9 @@ Common buttons prompt most actions in a UI
   <Inline tag={'span'} is={M3Button} icon={'edit'} label={'Edit'} appearance={'text'} />
   <Inline tag={'span'} is={M3Button} icon={'edit'} label={'Edit'} appearance={'tonal'} />
 </p>
+
+## Resources
+
+- [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
+- [M3 Buttons guidelines](https://m3.material.io/components/buttons/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Card.mdx b/m3-vue/storybook/components/M3Card.mdx
index a458dad..51b4af4 100644
--- a/m3-vue/storybook/components/M3Card.mdx
+++ b/m3-vue/storybook/components/M3Card.mdx
@@ -12,7 +12,11 @@ import { defineComponent, h } from 'vue'
 
 Cards display content and actions about a single subject
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Use non-interactive cards as plain content containers.
+- For interactive cards, expose actions with semantic controls (`button` / `link`).
+- Keep a clear heading hierarchy inside cards for screen reader navigation.
 
 <Inline is={defineComponent({
   render: () => h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: '16px' } }, [
@@ -20,3 +24,10 @@ Cards display content and actions about a single subject
     h(LiveMusic2),
   ]),
 })} />
+
+## Resources
+
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Cards guidelines](https://m3.material.io/components/cards/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Checkbox.mdx b/m3-vue/storybook/components/M3Checkbox.mdx
index 459511e..59c08f1 100644
--- a/m3-vue/storybook/components/M3Checkbox.mdx
+++ b/m3-vue/storybook/components/M3Checkbox.mdx
@@ -9,9 +9,11 @@ import * as M3CheckboxStories from './M3Checkbox.stories'
 
 Checkboxes let users select one or more items from a list, or turn an item on or off
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
 
-[Guidelines](https://m3.material.io/components/checkbox/guidelines)
+- Every checkbox needs a visible text label.
+- Group related checkboxes under a shared group label (`fieldset/legend` or `aria-labelledby`).
+- Use indeterminate state only for partial parent-selection states.
 
 ### Regular list
 
@@ -42,3 +44,10 @@ Checkboxes let users select one or more items from a list, or turn an item on or
     value: 'monthly',
   }],
 }]} />
+
+## Resources
+
+- [M3 Checkbox overview](https://m3.material.io/components/checkbox/overview)
+- [M3 Checkbox guidelines](https://m3.material.io/components/checkbox/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
diff --git a/m3-vue/storybook/components/M3Dialog.mdx b/m3-vue/storybook/components/M3Dialog.mdx
index c7b63f8..26731a0 100644
--- a/m3-vue/storybook/components/M3Dialog.mdx
+++ b/m3-vue/storybook/components/M3Dialog.mdx
@@ -5,8 +5,23 @@ import DialogConfirmation from '../examples/dialog/DialogConfirmation.vue'
 
 # Dialogs
 
+Dialogs communicate important information and block the underlying interface until the user responds.
+
+## Accessibility semantics
+
+- Set `role="dialog"` (or `alertdialog` for urgent confirmations).
+- Provide `aria-modal="true"` for modal flows.
+- Connect title and description with `aria-labelledby` and `aria-describedby`.
+- Keep focus inside the dialog while it is opened.
+
 <Unstyled>
   <div className="mb-3">
     <Inline is={DialogConfirmation} />
   </div>
-</Unstyled>
\ No newline at end of file
+</Unstyled>
+
+## Resources
+
+- [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
+- [M3 Dialogs guidelines](https://m3.material.io/components/dialogs/guidelines)
+- [WAI-ARIA APG: Modal Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
diff --git a/m3-vue/storybook/components/M3FabButton.mdx b/m3-vue/storybook/components/M3FabButton.mdx
index 02b7e0f..aa2a8a6 100644
--- a/m3-vue/storybook/components/M3FabButton.mdx
+++ b/m3-vue/storybook/components/M3FabButton.mdx
@@ -9,11 +9,13 @@ import * as M3FabButtonStories from './M3FabButton.stories'
 
 Floating action buttons (FABs) help people take primary actions
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
 
-### Standard FABs
+- Icon-only FABs require an accessible name via `aria-label`.
+- Keep FAB usage focused on the primary action on a given surface.
+- Extended FABs should keep a short visible label.
 
-[Guidelines](https://m3.material.io/components/floating-action-button/guidelines)
+### Standard FABs
 
 <p style={{ display: 'flex', gap: '16px' }}>
   <Inline tag={'span'} is={ButtonExample} icon={'edit'} aria-label={'Edit'} variant={'surface'} />
@@ -24,11 +26,18 @@ Floating action buttons (FABs) help people take primary actions
 
 ### Extended FABs
 
-[Guidelines](https://m3.material.io/components/extended-fab/guidelines)
-
 <p style={{ display: 'flex', gap: '16px' }}>
   <Inline tag={'span'} is={ButtonExample} icon={'add'} label={'New task'} variant={'surface'} />
   <Inline tag={'span'} is={ButtonExample} icon={'add'} label={'New task'} />
   <Inline tag={'span'} is={ButtonExample} icon={'add'} label={'New task'} variant={'secondary'} />
   <Inline tag={'span'} is={ButtonExample} icon={'add'} label={'New task'} variant={'tertiary'} />
 </p>
+
+## Resources
+
+- [M3 FAB overview](https://m3.material.io/components/floating-action-button/overview)
+- [M3 FAB guidelines](https://m3.material.io/components/floating-action-button/guidelines)
+- [M3 Extended FAB overview](https://m3.material.io/components/extended-fab/overview)
+- [M3 Extended FAB guidelines](https://m3.material.io/components/extended-fab/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3IconButton.mdx b/m3-vue/storybook/components/M3IconButton.mdx
index 8bbafb0..17b8c71 100644
--- a/m3-vue/storybook/components/M3IconButton.mdx
+++ b/m3-vue/storybook/components/M3IconButton.mdx
@@ -12,7 +12,11 @@ import { M3IconButton } from '@/components/icon-button'
 
 Icon buttons help people take minor actions with one tap
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Icon-only controls must include an accessible name (`aria-label`).
+- Toggleable icon buttons should expose state with `aria-pressed`.
+- Use icon buttons for minor actions, not for primary destructive actions.
 
 <Inline tag={'p'} is={defineComponent({
   setup () {
@@ -22,13 +26,25 @@ Icon buttons help people take minor actions with one tap
     }
 
     return () => [
-      h(M3IconButton, { appearance: 'filled' }, icon),
+      h(M3IconButton, {
+        appearance: 'filled',
+        'aria-label': 'Mark as favorite',
+      }, icon),
       h(M3IconButton, {
         appearance: 'filled',
         selected: selected.value,
         toggleable: true,
+        'aria-label': 'Toggle favorite',
+        'aria-pressed': selected.value ? 'true' : 'false',
         onClick: () => selected.value = !selected.value,
       }, icon)
     ]
   },
 })} />
+
+## Resources
+
+- [M3 Icon Buttons overview](https://m3.material.io/components/icon-buttons/overview)
+- [M3 Icon Buttons guidelines](https://m3.material.io/components/icon-buttons/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Navigation.mdx b/m3-vue/storybook/components/M3Navigation.mdx
index 856bd5a..d6f4660 100644
--- a/m3-vue/storybook/components/M3Navigation.mdx
+++ b/m3-vue/storybook/components/M3Navigation.mdx
@@ -4,3 +4,20 @@ import * as M3NavigationStories from './M3Navigation.stories'
 <Meta of={M3NavigationStories} />
 
 # Navigation
+
+Navigation components help users move between top-level destinations.
+
+## Accessibility semantics
+
+- Treat the container as a navigation landmark and provide a clear label when needed.
+- Keep destination labels concise and unique.
+- Expose active destination state consistently in routed integrations.
+
+## Resources
+
+- [M3 Navigation bar overview](https://m3.material.io/components/navigation-bar/overview)
+- [M3 Navigation rail overview](https://m3.material.io/components/navigation-rail/overview)
+- [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
+- [Storybook: NavigationDrawer](?path=/story/components-m3navigation--navigation-drawer)
+- [Storybook: NavigationRail](?path=/story/components-m3navigation--navigation-rail)
+- [WAI-ARIA APG: Landmark Regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)
diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index 8579073..8d02f3a 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -5,8 +5,22 @@ import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip.vue'
 
 # Rich tooltip
 
+Rich tooltips provide contextual, supplementary information near a trigger element.
+
+## Accessibility semantics
+
+- Link trigger and tooltip with `aria-describedby`.
+- Keep tooltip text concise and task-relevant.
+- Avoid using tooltips as the only way to convey critical information.
+
 <Unstyled>
   <div className="m3-panel m3-panel_elevated-1 my-4" style={{ maxWidth: '360px' }}>
     <Inline is={DeleteTooltip} />
   </div>
 </Unstyled>
+
+## Resources
+
+- [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
+- [M3 Tooltips guidelines](https://m3.material.io/components/tooltips/guidelines)
+- [WAI-ARIA APG: Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
diff --git a/m3-vue/storybook/components/M3Select.mdx b/m3-vue/storybook/components/M3Select.mdx
index 134429c..b16b8f6 100644
--- a/m3-vue/storybook/components/M3Select.mdx
+++ b/m3-vue/storybook/components/M3Select.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
 import * as M3SelectStories from './M3Select.stories'
 
 <Meta of={M3SelectStories} />
@@ -6,3 +6,21 @@ import * as M3SelectStories from './M3Select.stories'
 # M3Select
 
 Text field augmented with dropdown menu
+
+## Accessibility semantics
+
+- `M3Select` exposes combobox semantics with a listbox popup and option items.
+- Provide a visible label through `label` or an explicit aria-label/aria-labelledby strategy.
+- Keep option labels unique and meaningful for screen readers.
+
+## Demo
+
+<Canvas of={M3SelectStories.Standard} />
+<Canvas of={M3SelectStories.WithIcons} />
+
+## Resources
+
+- [M3 Menus overview](https://m3.material.io/components/menus/overview)
+- [M3 Menus guidelines](https://m3.material.io/components/menus/guidelines)
+- [WAI-ARIA APG: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [WAI-ARIA APG: Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)
diff --git a/m3-vue/storybook/components/M3Slider.mdx b/m3-vue/storybook/components/M3Slider.mdx
index 8c0592f..f055726 100644
--- a/m3-vue/storybook/components/M3Slider.mdx
+++ b/m3-vue/storybook/components/M3Slider.mdx
@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
 import * as M3SliderStories from './M3Slider.stories'
 
 <Meta of={M3SliderStories} />
@@ -6,3 +6,21 @@ import * as M3SliderStories from './M3Slider.stories'
 # M3Slider
 
 Sliders let users make selections from a range of values
+
+## Accessibility semantics
+
+- Each slider handle must have an accessible name (`ariaHandle`, `ariaHandleMin`, `ariaHandleMax`).
+- Keep numeric ranges and steps predictable and documented for users.
+- Support keyboard adjustments (Arrow, Home, End) for all handles.
+
+## Demo
+
+<Canvas of={M3SliderStories.Single} />
+<Canvas of={M3SliderStories.Range} />
+
+## Resources
+
+- [M3 Sliders overview](https://m3.material.io/components/sliders/overview)
+- [M3 Sliders guidelines](https://m3.material.io/components/sliders/guidelines)
+- [WAI-ARIA APG: Slider Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/)
+- [WAI-ARIA APG: Multi-Thumb Slider Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multithumb/)
diff --git a/m3-vue/storybook/components/M3Switch.mdx b/m3-vue/storybook/components/M3Switch.mdx
index 0e22f38..9ced597 100644
--- a/m3-vue/storybook/components/M3Switch.mdx
+++ b/m3-vue/storybook/components/M3Switch.mdx
@@ -16,6 +16,14 @@ import * as M3SwitchStories from './M3Switch.stories'
   * Make sure the switch’s selection (on or off) is visible at a glance
 </Unstyled>
 
+## Accessibility semantics
+
+<Unstyled>
+  * Keep a visible label next to each switch control.
+  * Expose checked state via `role="switch"` and `aria-checked`.
+  * Use switches for immediate on/off state changes, not for multi-choice selections.
+</Unstyled>
+
 ### Demo
 
 <Unstyled>
@@ -25,9 +33,11 @@ import * as M3SwitchStories from './M3Switch.stories'
   </div>
 </Unstyled>
 
-### Resources
+## Resources
 
 <Unstyled>
   * [Guidelines](https://m3.material.io/components/switch/guidelines)
+  * [M3 Switch overview](https://m3.material.io/components/switch/overview)
   * [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+  * [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
 </Unstyled>
diff --git a/m3-vue/storybook/components/M3TextField.mdx b/m3-vue/storybook/components/M3TextField.mdx
index 0fdf76c..900260b 100644
--- a/m3-vue/storybook/components/M3TextField.mdx
+++ b/m3-vue/storybook/components/M3TextField.mdx
@@ -14,7 +14,11 @@ import { M3TextField } from '@/components/text-field'
 
 Text fields let users enter text into a UI
 
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## Accessibility semantics
+
+- Provide a persistent text label (`label` prop or explicit aria-labelledby).
+- Use `aria-invalid` together with helper/support text for validation feedback.
+- For long-form input, prefer multiline mode (`textarea`) with the same labeling strategy.
 
 <Inline tag={'p'} is={defineComponent({
   setup () {
@@ -76,3 +80,10 @@ Outlined text field:
   },
 })} />
 </Unstyled>
+
+## Resources
+
+- [M3 Text Fields overview](https://m3.material.io/components/text-fields/overview)
+- [M3 Text Fields guidelines](https://m3.material.io/components/text-fields/guidelines)
+- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [WAI Tutorials: Form Labels](https://www.w3.org/WAI/tutorials/forms/labels/)
diff --git a/m3-vue/storybook/examples/dialog/DialogConfirmation.vue b/m3-vue/storybook/examples/dialog/DialogConfirmation.vue
index e309f6b..7f356d9 100644
--- a/m3-vue/storybook/examples/dialog/DialogConfirmation.vue
+++ b/m3-vue/storybook/examples/dialog/DialogConfirmation.vue
@@ -9,17 +9,23 @@
     <M3Dialog
         v-model:opened="opened"
         role="dialog"
-        aria-live="assertive"
+        aria-modal="true"
+        aria-labelledby="dialog-confirmation-title"
+        aria-describedby="dialog-confirmation-description"
     >
         <template #icon>
             <M3Icon name="delete" appearance="outlined" />
         </template>
 
         <template #header>
-            <h3>Permanently delete?</h3>
+            <h3 id="dialog-confirmation-title">
+                Permanently delete?
+            </h3>
         </template>
 
-        Deleting the selected messages will also remove them from all synced devices.
+        <p id="dialog-confirmation-description">
+            Deleting the selected messages will also remove them from all synced devices.
+        </p>
 
         <template #footer>
             <M3Button
diff --git a/m3-vue/storybook/examples/rich-tooltip/DeleteTooltip.vue b/m3-vue/storybook/examples/rich-tooltip/DeleteTooltip.vue
index 337bf1c..07f1b3b 100644
--- a/m3-vue/storybook/examples/rich-tooltip/DeleteTooltip.vue
+++ b/m3-vue/storybook/examples/rich-tooltip/DeleteTooltip.vue
@@ -1,10 +1,10 @@
 <template>
     <span ref="target" :style="{ display: 'inline-block' }">
-        <M3Button>
+        <M3Button :aria-describedby="tooltipId">
             Delete
         </M3Button>
 
-        <M3RichTooltip :target="() => target" hide-on-miss-click>
+        <M3RichTooltip :id="tooltipId" :target="() => target" hide-on-miss-click>
             <template #heading>
                 Deleting item
             </template>
@@ -33,4 +33,5 @@ import { vM3PopperCloser } from '@/components/popper'
 import { ref } from 'vue'
 
 const target = ref<HTMLElement | null>(null)
+const tooltipId = 'delete-tooltip-description'
 </script>

From 3fc42e10b53d3f470a2acc6540cf4ec7e65c091d Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 22:20:22 +0400
Subject: [PATCH 06/37] docs: Storybook code snippets were adapted for M3 docs
 themes

---
 m3-react/package.json                         |   1 +
 m3-react/storybook/components/M3Button.mdx    |  10 +
 m3-react/storybook/preview.ts                 |  19 +
 .../storybook/stylesheets/mdxCodeBlock.scss   | 128 ++++++
 m3-react/storybook/utils/mdxCodeBlock.ts      | 434 ++++++++++++++++++
 m3-vue/package.json                           |   1 +
 m3-vue/storybook/components/M3Button.mdx      |   8 +
 m3-vue/storybook/preview.ts                   |  19 +
 .../storybook/stylesheets/mdxCodeBlock.scss   | 128 ++++++
 m3-vue/storybook/utils/mdxCodeBlock.ts        | 434 ++++++++++++++++++
 yarn.lock                                     |   9 +
 11 files changed, 1191 insertions(+)
 create mode 100644 m3-react/storybook/stylesheets/mdxCodeBlock.scss
 create mode 100644 m3-react/storybook/utils/mdxCodeBlock.ts
 create mode 100644 m3-vue/storybook/stylesheets/mdxCodeBlock.scss
 create mode 100644 m3-vue/storybook/utils/mdxCodeBlock.ts

diff --git a/m3-react/package.json b/m3-react/package.json
index 4f2df8e..337a555 100644
--- a/m3-react/package.json
+++ b/m3-react/package.json
@@ -75,6 +75,7 @@
     "eslint-plugin-unused-imports": "^4.4.1",
     "flag-icons": "^7.5.0",
     "globals": "^17.3.0",
+    "highlight.js": "^11.11.1",
     "jsdom": "^28.1.0",
     "playwright": "^1.55.0",
     "react": "^18.2.0",
diff --git a/m3-react/storybook/components/M3Button.mdx b/m3-react/storybook/components/M3Button.mdx
index 866a658..5374a45 100644
--- a/m3-react/storybook/components/M3Button.mdx
+++ b/m3-react/storybook/components/M3Button.mdx
@@ -34,6 +34,16 @@ Common buttons prompt most actions in a UI
   </p>
 </Unstyled>
 
+## Code example
+
+```tsx
+export const EditButton = () => (
+  <M3Button appearance={'tonal'}>
+    <M3Icon name={'edit'} /> Edit
+  </M3Button>
+)
+```
+
 ## Resources
 
 - [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
diff --git a/m3-react/storybook/preview.ts b/m3-react/storybook/preview.ts
index 1cd3b81..0759b6d 100644
--- a/m3-react/storybook/preview.ts
+++ b/m3-react/storybook/preview.ts
@@ -7,6 +7,14 @@ import './stylesheets/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
+import { MdxCodeBlock, MdxCodePreBlock } from './utils/mdxCodeBlock'
+
+type DocsParameter = NonNullable<NonNullable<Preview['parameters']>['docs']> & {
+  components?: {
+    code: typeof MdxCodeBlock
+    pre: typeof MdxCodePreBlock
+  }
+}
 
 const themeClassByName = {
   light: 'm3-theme-light',
@@ -15,6 +23,16 @@ const themeClassByName = {
 
 const themeClasses = Object.values(themeClassByName)
 
+const docsParameter: DocsParameter = {
+  components: {
+    code: MdxCodeBlock,
+    pre: MdxCodePreBlock,
+  },
+  source: {
+    language: 'text',
+  },
+}
+
 const applyThemeClass = (themeName?: unknown): void => {
   const rootElement = document.documentElement
 
@@ -93,6 +111,7 @@ export default {
       },
     },
     backgrounds: { disable: true },
+    docs: docsParameter,
     controls: {
       matchers: {
         color: /(background|color)$/i,
diff --git a/m3-react/storybook/stylesheets/mdxCodeBlock.scss b/m3-react/storybook/stylesheets/mdxCodeBlock.scss
new file mode 100644
index 0000000..e15c8a0
--- /dev/null
+++ b/m3-react/storybook/stylesheets/mdxCodeBlock.scss
@@ -0,0 +1,128 @@
+html {
+  --m3-docs-code-background: var(--m3-sys-surface-container);
+  --m3-docs-code-chip-background: var(--m3-sys-surface-container-high);
+  --m3-docs-code-copy-background: var(--m3-sys-secondary-container);
+  --m3-docs-code-copy-color: var(--m3-sys-on-secondary-container);
+  --m3-docs-code-divider: var(--m3-state-layers-on-surface-opacity-020);
+  --m3-docs-code-focus: var(--m3-sys-primary);
+  --m3-docs-code-plain: var(--m3-sys-on-surface);
+  --m3-docs-code-token-accent: #7b2cbf;
+  --m3-docs-code-token-comment: #6b7280;
+  --m3-docs-code-token-keyword: #0047b3;
+  --m3-docs-code-token-string: #8f3b1f;
+}
+
+html.m3-theme-dark {
+  --m3-docs-code-chip-background: var(--m3-sys-surface-container-highest);
+  --m3-docs-code-token-accent: #c99eff;
+  --m3-docs-code-token-comment: #9ca3af;
+  --m3-docs-code-token-keyword: #8fb8ff;
+  --m3-docs-code-token-string: #ffb59e;
+}
+
+pre.m3-docs-code-block {
+  margin: 16px 0 !important;
+  padding: 0 !important;
+  background: var(--m3-docs-code-background) !important;
+  border-radius: 16px !important;
+  box-shadow: inset 0 0 0 1px var(--m3-docs-code-divider);
+  overflow: hidden;
+  position: relative;
+}
+
+pre.m3-docs-code-block > code.hljs {
+  display: block;
+  overflow-x: auto;
+  margin: 0;
+  padding: 52px 16px 16px;
+  background: transparent;
+  color: var(--m3-docs-code-plain);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace !important;
+  font-size: 13px !important;
+  line-height: 1.5;
+  tab-size: 2;
+  white-space: pre !important;
+}
+
+pre.m3-docs-code-block > code.hljs * {
+  font-family: inherit !important;
+  font-size: inherit !important;
+  line-height: inherit;
+}
+
+pre.m3-docs-code-block .m3-docs-code-language {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  border-radius: 999px;
+  padding: 4px 10px;
+  background: var(--m3-docs-code-chip-background);
+  color: var(--m3-docs-code-plain);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
+  text-transform: uppercase;
+  user-select: none;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  border: 0;
+  border-radius: 999px;
+  min-height: 32px;
+  min-width: 92px;
+  padding: 0 14px;
+  background: var(--m3-docs-code-copy-background);
+  color: var(--m3-docs-code-copy-color);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1;
+  cursor: pointer;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:hover {
+  opacity: 0.92;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:active {
+  transform: translateY(1px);
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:focus-visible {
+  outline: 2px solid var(--m3-docs-code-focus);
+  outline-offset: 2px;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy[data-copied='true'] {
+  min-width: 82px;
+}
+
+pre.m3-docs-code-block .hljs-comment,
+pre.m3-docs-code-block .hljs-quote {
+  color: var(--m3-docs-code-token-comment);
+}
+
+pre.m3-docs-code-block .hljs-keyword,
+pre.m3-docs-code-block .hljs-selector-tag,
+pre.m3-docs-code-block .hljs-literal,
+pre.m3-docs-code-block .hljs-name {
+  color: var(--m3-docs-code-token-keyword);
+}
+
+pre.m3-docs-code-block .hljs-string,
+pre.m3-docs-code-block .hljs-attr,
+pre.m3-docs-code-block .hljs-template-tag,
+pre.m3-docs-code-block .hljs-template-variable {
+  color: var(--m3-docs-code-token-string);
+}
+
+pre.m3-docs-code-block .hljs-title,
+pre.m3-docs-code-block .hljs-section,
+pre.m3-docs-code-block .hljs-number,
+pre.m3-docs-code-block .hljs-symbol,
+pre.m3-docs-code-block .hljs-type,
+pre.m3-docs-code-block .hljs-variable {
+  color: var(--m3-docs-code-token-accent);
+}
diff --git a/m3-react/storybook/utils/mdxCodeBlock.ts b/m3-react/storybook/utils/mdxCodeBlock.ts
new file mode 100644
index 0000000..e705618
--- /dev/null
+++ b/m3-react/storybook/utils/mdxCodeBlock.ts
@@ -0,0 +1,434 @@
+import '../stylesheets/mdxCodeBlock.scss'
+
+import React from 'react'
+
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react'
+
+import bash from 'highlight.js/lib/languages/bash'
+import css from 'highlight.js/lib/languages/css'
+import hljs from 'highlight.js/lib/core'
+import javascript from 'highlight.js/lib/languages/javascript'
+import json from 'highlight.js/lib/languages/json'
+import typescript from 'highlight.js/lib/languages/typescript'
+import xml from 'highlight.js/lib/languages/xml'
+
+type MdxCodeBlockProps = ComponentPropsWithoutRef<'code'>
+type MdxPreBlockProps = ComponentPropsWithoutRef<'pre'>
+type CodeElementProps = ComponentPropsWithoutRef<'code'> & {
+  'data-language'?: string
+}
+
+type HighlightPayload = {
+  html: string
+  language: string | null
+}
+
+type CodePayload = {
+  badgeLanguage: string | null
+  highlightLanguage: string | null
+  source: string
+}
+
+type RenderCodeBlockProps = {
+  badgeLanguage: string | null
+  className?: string
+  codeLanguage: string | null
+  copied: boolean
+  html: string
+  onCopy: () => void
+  restProps: Omit<MdxPreBlockProps, 'children' | 'className'>
+}
+
+const AUTO_DETECT_MAX_LENGTH = 5000
+const CODE_BLOCK_CLASS = 'm3-docs-code-block'
+const COPY_BUTTON_CLASS = 'm3-docs-code-copy'
+const COPY_RESET_DELAY_MS = 1500
+const COPY_STATE_ATTRIBUTE = 'data-copied'
+const COPY_SUCCESS_TEXT = 'Copied'
+const COPY_TEXT = 'Copy code'
+const LANGUAGE_BADGE_CLASS = 'm3-docs-code-language'
+const LANGUAGE_PREFIXES = ['language-', 'lang-']
+const PANEL_CLASS = 'm3-panel m3-panel_elevated-1'
+const NON_SPECIFIC_LANGUAGES = new Set(['plain', 'plaintext', 'text', 'txt'])
+
+const HIGHLIGHT_LANGUAGE_ALIASES: Record<string, string> = {
+  cjs: 'javascript',
+  html: 'xml',
+  js: 'javascript',
+  jsx: 'javascript',
+  markup: 'xml',
+  sh: 'bash',
+  shell: 'bash',
+  ts: 'typescript',
+  tsx: 'typescript',
+  vue: 'xml',
+}
+
+const BADGE_LANGUAGE_ALIASES: Record<string, string> = {
+  atom: 'html',
+  html: 'html',
+  js: 'javascript',
+  jsx: 'jsx',
+  json: 'json',
+  markup: 'html',
+  rss: 'html',
+  sh: 'bash',
+  shell: 'bash',
+  svg: 'html',
+  ts: 'typescript',
+  tsx: 'tsx',
+  vue: 'html',
+  xhtml: 'html',
+  xml: 'html',
+}
+
+const SUPPORTED_HIGHLIGHT_LANGUAGES = new Set([
+  'atom',
+  'bash',
+  'css',
+  'html',
+  'javascript',
+  'json',
+  'rss',
+  'svg',
+  'typescript',
+  'xhtml',
+  'xml',
+])
+
+let languagesRegistered = false
+
+const highlightRegistrations = [
+  ['bash', bash],
+  ['css', css],
+  ['javascript', javascript],
+  ['json', json],
+  ['typescript', typescript],
+  ['xml', xml],
+] as const
+
+function ensureLanguagesRegistered (): void {
+  if (languagesRegistered) return
+
+  highlightRegistrations.forEach(([name, definition]) => {
+    hljs.registerLanguage(name, definition)
+  })
+
+  languagesRegistered = true
+}
+
+function escapeHtml (value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('\'', '&#39;')
+}
+
+function normalizeLanguageFromClass (className?: string | null): string | null {
+  if (!className) return null
+
+  const tokens = className.split(/\s+/u)
+  for (const token of tokens) {
+    for (const prefix of LANGUAGE_PREFIXES) {
+      if (token.startsWith(prefix)) {
+        return token.slice(prefix.length)
+      }
+    }
+  }
+
+  return null
+}
+
+function normalizeLanguageToken (value?: string | null): string | null {
+  const normalized = value?.trim().toLowerCase()
+  return normalized || null
+}
+
+function isSpecificLanguage (language: string | null): language is string {
+  return Boolean(language && !NON_SPECIFIC_LANGUAGES.has(language))
+}
+
+function resolveHighlightLanguage (value?: string | null): string | null {
+  const normalized = normalizeLanguageToken(value)
+  if (!isSpecificLanguage(normalized)) return null
+
+  const aliasResolved = HIGHLIGHT_LANGUAGE_ALIASES[normalized] || normalized
+
+  return SUPPORTED_HIGHLIGHT_LANGUAGES.has(aliasResolved) ? aliasResolved : null
+}
+
+function resolveBadgeLanguage (value?: string | null): string | null {
+  const normalized = normalizeLanguageToken(value)
+  if (!isSpecificLanguage(normalized)) return null
+
+  return BADGE_LANGUAGE_ALIASES[normalized] || normalized
+}
+
+function inferBadgeLanguageFromSource (source: string): string | null {
+  if (!source.trim()) return null
+
+  const containsMarkup = /<[^>]+>/u.test(source)
+  const containsJsxComponent = /<[A-Z][A-Za-z0-9_.:-]*/u.test(source)
+  const containsJsxExpression = /\{[^}]+\}/u.test(source)
+
+  if (containsJsxComponent && containsJsxExpression) return 'tsx'
+  if (containsMarkup) return 'html'
+  return null
+}
+
+function extractText (node: ReactNode): string {
+  if (typeof node === 'string') return node
+  if (typeof node === 'number' || typeof node === 'boolean') return String(node)
+  if (Array.isArray(node)) return node.map(extractText).join('')
+
+  if (React.isValidElement<{ children?: ReactNode }>(node)) {
+    return extractText(node.props.children)
+  }
+
+  return ''
+}
+
+function findCodeElement (node: ReactNode): ReactElement<CodeElementProps> | null {
+  if (React.isValidElement<CodeElementProps>(node) && node.type === 'code') {
+    return node
+  }
+
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const codeElement = findCodeElement(child)
+      if (codeElement) return codeElement
+    }
+  }
+
+  if (React.isValidElement<{ children?: ReactNode }>(node)) {
+    return findCodeElement(node.props.children)
+  }
+
+  return null
+}
+
+function trimTrailingNewline (source: string): string {
+  return source.replace(/\r?\n$/u, '')
+}
+
+function highlightKnownLanguage (source: string, language: string): HighlightPayload {
+  return {
+    html: hljs.highlight(source, {
+      ignoreIllegals: true,
+      language,
+    }).value,
+    language,
+  }
+}
+
+function highlightAutoLanguage (source: string): HighlightPayload {
+  const autoResult = hljs.highlightAuto(source)
+
+  return {
+    html: autoResult.value,
+    language: autoResult.language || null,
+  }
+}
+
+function highlightSource (source: string, language: string | null): HighlightPayload {
+  ensureLanguagesRegistered()
+
+  if (source.trim() === '') {
+    return { html: '', language }
+  }
+
+  try {
+    if (language) return highlightKnownLanguage(source, language)
+    if (source.length > AUTO_DETECT_MAX_LENGTH) return { html: escapeHtml(source), language: null }
+    return highlightAutoLanguage(source)
+  } catch {
+    return { html: escapeHtml(source), language }
+  }
+}
+
+async function copyTextToClipboard (value: string): Promise<boolean> {
+  if (!value) return false
+
+  if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value)
+      return true
+    } catch {
+      // Fallback below for restricted clipboard contexts.
+    }
+  }
+
+  if (!document.body || typeof document.execCommand !== 'function') return false
+
+  const textarea = document.createElement('textarea')
+  textarea.value = value
+  textarea.setAttribute('readonly', 'true')
+  textarea.style.left = '-9999px'
+  textarea.style.opacity = '0'
+  textarea.style.pointerEvents = 'none'
+  textarea.style.position = 'fixed'
+  document.body.appendChild(textarea)
+  textarea.select()
+
+  try {
+    return document.execCommand('copy')
+  } finally {
+    textarea.remove()
+  }
+}
+
+function joinClassNames (...parts: Array<string | null | undefined>): string {
+  return parts.filter(Boolean).join(' ')
+}
+
+function pickRawLanguageToken (children: ReactNode, className?: string): string | null {
+  const codeElement = findCodeElement(children)
+  const codeProps = codeElement?.props
+
+  return normalizeLanguageToken(
+    codeProps?.['data-language'] ||
+      normalizeLanguageFromClass(codeProps?.className) ||
+      normalizeLanguageFromClass(className)
+  )
+}
+
+function resolveCodePayload (children: ReactNode, className?: string): CodePayload {
+  const codeElement = findCodeElement(children)
+  const source = trimTrailingNewline(extractText(codeElement?.props?.children ?? children))
+  const rawLanguage = pickRawLanguageToken(children, className)
+  const inferredBadgeLanguage = inferBadgeLanguageFromSource(source)
+  const badgeLanguage = inferredBadgeLanguage || resolveBadgeLanguage(rawLanguage)
+  const highlightLanguage = resolveHighlightLanguage(badgeLanguage || rawLanguage)
+
+  return {
+    badgeLanguage,
+    highlightLanguage,
+    source,
+  }
+}
+
+function useCopyState (source: string): { copied: boolean; onCopy: () => void } {
+  const [copied, setCopied] = React.useState(false)
+  const resetTimerRef = React.useRef<number | null>(null)
+
+  React.useEffect(() => () => {
+    if (resetTimerRef.current) {
+      window.clearTimeout(resetTimerRef.current)
+    }
+  }, [])
+
+  const onCopy = React.useCallback(() => {
+    void copyTextToClipboard(source).then((success) => {
+      if (!success) return
+
+      setCopied(true)
+      if (resetTimerRef.current) window.clearTimeout(resetTimerRef.current)
+
+      resetTimerRef.current = window.setTimeout(() => {
+        setCopied(false)
+        resetTimerRef.current = null
+      }, COPY_RESET_DELAY_MS)
+    })
+  }, [source])
+
+  return { copied, onCopy }
+}
+
+function getCodeClassName (codeLanguage: string | null): string {
+  return codeLanguage ? `hljs language-${codeLanguage}` : 'hljs'
+}
+
+function renderLanguageBadge (badgeLanguage: string | null): React.ReactElement {
+  return React.createElement(
+    'span',
+    {
+      className: LANGUAGE_BADGE_CLASS,
+    },
+    badgeLanguage || 'text'
+  )
+}
+
+function renderCopyButton (copied: boolean, onCopy: () => void): React.ReactElement {
+  return React.createElement(
+    'button',
+    {
+      type: 'button',
+      className: COPY_BUTTON_CLASS,
+      'aria-label': 'Copy code block',
+      [COPY_STATE_ATTRIBUTE]: copied ? 'true' : 'false',
+      onClick: onCopy,
+    },
+    copied ? COPY_SUCCESS_TEXT : COPY_TEXT
+  )
+}
+
+function renderCodeContent (codeHtml: string, codeLanguage: string | null): React.ReactElement {
+  return React.createElement('code', {
+    className: getCodeClassName(codeLanguage),
+    'data-language': codeLanguage || undefined,
+    dangerouslySetInnerHTML: {
+      __html: codeHtml,
+    },
+  })
+}
+
+function renderCodeBlock ({
+  badgeLanguage,
+  className,
+  codeLanguage,
+  copied,
+  html,
+  onCopy,
+  restProps,
+}: RenderCodeBlockProps): React.ReactElement {
+  return React.createElement(
+    'pre',
+    {
+      ...restProps,
+      className: joinClassNames(PANEL_CLASS, CODE_BLOCK_CLASS, className),
+      'data-language': codeLanguage || undefined,
+    },
+    renderLanguageBadge(badgeLanguage),
+    renderCopyButton(copied, onCopy),
+    renderCodeContent(html, codeLanguage)
+  )
+}
+
+export function MdxCodeBlock (props: MdxCodeBlockProps): React.ReactElement {
+  const { children, ...restProps } = props
+  return React.createElement('code', restProps, children)
+}
+
+export function MdxCodePreBlock (props: MdxPreBlockProps): React.ReactElement {
+  const { children, className, ...restProps } = props
+  const payload = React.useMemo(
+    () => resolveCodePayload(children, className),
+    [children, className]
+  )
+  const highlight = React.useMemo(
+    () => highlightSource(payload.source, payload.highlightLanguage),
+    [payload.highlightLanguage, payload.source]
+  )
+  const { copied, onCopy } = useCopyState(payload.source)
+  const resolvedCodeLanguage = highlight.language || payload.highlightLanguage
+  const resolvedBadgeLanguage =
+    payload.badgeLanguage ||
+    resolveBadgeLanguage(resolvedCodeLanguage) ||
+    inferBadgeLanguageFromSource(payload.source)
+
+  if (payload.source.trim() === '') {
+    return React.createElement('pre', { className, ...restProps }, children)
+  }
+
+  return renderCodeBlock({
+    badgeLanguage: resolvedBadgeLanguage,
+    className,
+    codeLanguage: resolvedCodeLanguage,
+    copied,
+    html: highlight.html || escapeHtml(payload.source),
+    onCopy,
+    restProps,
+  })
+}
diff --git a/m3-vue/package.json b/m3-vue/package.json
index 94c7355..d5d62da 100644
--- a/m3-vue/package.json
+++ b/m3-vue/package.json
@@ -70,6 +70,7 @@
     "eslint-plugin-vue": "^10.8.0",
     "flag-icons": "^7.5.0",
     "globals": "^17.3.0",
+    "highlight.js": "^11.11.1",
     "jsdom": "^28.1.0",
     "playwright": "^1.55.0",
     "react": "^18.3.1",
diff --git a/m3-vue/storybook/components/M3Button.mdx b/m3-vue/storybook/components/M3Button.mdx
index da1b2eb..f838aa3 100644
--- a/m3-vue/storybook/components/M3Button.mdx
+++ b/m3-vue/storybook/components/M3Button.mdx
@@ -31,6 +31,14 @@ Common buttons prompt most actions in a UI
   <Inline tag={'span'} is={M3Button} icon={'edit'} label={'Edit'} appearance={'tonal'} />
 </p>
 
+## Code example
+
+```html
+<M3Button appearance="tonal">
+    <M3Icon name="edit" /> Edit
+</M3Button>
+```
+
 ## Resources
 
 - [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
diff --git a/m3-vue/storybook/preview.ts b/m3-vue/storybook/preview.ts
index 3d7f251..75fcebb 100644
--- a/m3-vue/storybook/preview.ts
+++ b/m3-vue/storybook/preview.ts
@@ -7,6 +7,14 @@ import './stylesheets/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
+import { MdxCodeBlock, MdxCodePreBlock } from './utils/mdxCodeBlock'
+
+type DocsParameter = NonNullable<NonNullable<Preview['parameters']>['docs']> & {
+  components?: {
+    code: typeof MdxCodeBlock
+    pre: typeof MdxCodePreBlock
+  }
+}
 
 const themeClassByName = {
   light: 'm3-theme-light',
@@ -15,6 +23,16 @@ const themeClassByName = {
 
 const themeClasses = Object.values(themeClassByName)
 
+const docsParameter: DocsParameter = {
+  components: {
+    code: MdxCodeBlock,
+    pre: MdxCodePreBlock,
+  },
+  source: {
+    language: 'text',
+  },
+}
+
 const applyThemeClass = (themeName?: unknown): void => {
   const rootElement = document.documentElement
 
@@ -93,6 +111,7 @@ export default {
       },
     },
     backgrounds: { disable: true },
+    docs: docsParameter,
     controls: {
       matchers: {
         color: /(background|color)$/i,
diff --git a/m3-vue/storybook/stylesheets/mdxCodeBlock.scss b/m3-vue/storybook/stylesheets/mdxCodeBlock.scss
new file mode 100644
index 0000000..e15c8a0
--- /dev/null
+++ b/m3-vue/storybook/stylesheets/mdxCodeBlock.scss
@@ -0,0 +1,128 @@
+html {
+  --m3-docs-code-background: var(--m3-sys-surface-container);
+  --m3-docs-code-chip-background: var(--m3-sys-surface-container-high);
+  --m3-docs-code-copy-background: var(--m3-sys-secondary-container);
+  --m3-docs-code-copy-color: var(--m3-sys-on-secondary-container);
+  --m3-docs-code-divider: var(--m3-state-layers-on-surface-opacity-020);
+  --m3-docs-code-focus: var(--m3-sys-primary);
+  --m3-docs-code-plain: var(--m3-sys-on-surface);
+  --m3-docs-code-token-accent: #7b2cbf;
+  --m3-docs-code-token-comment: #6b7280;
+  --m3-docs-code-token-keyword: #0047b3;
+  --m3-docs-code-token-string: #8f3b1f;
+}
+
+html.m3-theme-dark {
+  --m3-docs-code-chip-background: var(--m3-sys-surface-container-highest);
+  --m3-docs-code-token-accent: #c99eff;
+  --m3-docs-code-token-comment: #9ca3af;
+  --m3-docs-code-token-keyword: #8fb8ff;
+  --m3-docs-code-token-string: #ffb59e;
+}
+
+pre.m3-docs-code-block {
+  margin: 16px 0 !important;
+  padding: 0 !important;
+  background: var(--m3-docs-code-background) !important;
+  border-radius: 16px !important;
+  box-shadow: inset 0 0 0 1px var(--m3-docs-code-divider);
+  overflow: hidden;
+  position: relative;
+}
+
+pre.m3-docs-code-block > code.hljs {
+  display: block;
+  overflow-x: auto;
+  margin: 0;
+  padding: 52px 16px 16px;
+  background: transparent;
+  color: var(--m3-docs-code-plain);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace !important;
+  font-size: 13px !important;
+  line-height: 1.5;
+  tab-size: 2;
+  white-space: pre !important;
+}
+
+pre.m3-docs-code-block > code.hljs * {
+  font-family: inherit !important;
+  font-size: inherit !important;
+  line-height: inherit;
+}
+
+pre.m3-docs-code-block .m3-docs-code-language {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  border-radius: 999px;
+  padding: 4px 10px;
+  background: var(--m3-docs-code-chip-background);
+  color: var(--m3-docs-code-plain);
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
+  text-transform: uppercase;
+  user-select: none;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  border: 0;
+  border-radius: 999px;
+  min-height: 32px;
+  min-width: 92px;
+  padding: 0 14px;
+  background: var(--m3-docs-code-copy-background);
+  color: var(--m3-docs-code-copy-color);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1;
+  cursor: pointer;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:hover {
+  opacity: 0.92;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:active {
+  transform: translateY(1px);
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy:focus-visible {
+  outline: 2px solid var(--m3-docs-code-focus);
+  outline-offset: 2px;
+}
+
+pre.m3-docs-code-block .m3-docs-code-copy[data-copied='true'] {
+  min-width: 82px;
+}
+
+pre.m3-docs-code-block .hljs-comment,
+pre.m3-docs-code-block .hljs-quote {
+  color: var(--m3-docs-code-token-comment);
+}
+
+pre.m3-docs-code-block .hljs-keyword,
+pre.m3-docs-code-block .hljs-selector-tag,
+pre.m3-docs-code-block .hljs-literal,
+pre.m3-docs-code-block .hljs-name {
+  color: var(--m3-docs-code-token-keyword);
+}
+
+pre.m3-docs-code-block .hljs-string,
+pre.m3-docs-code-block .hljs-attr,
+pre.m3-docs-code-block .hljs-template-tag,
+pre.m3-docs-code-block .hljs-template-variable {
+  color: var(--m3-docs-code-token-string);
+}
+
+pre.m3-docs-code-block .hljs-title,
+pre.m3-docs-code-block .hljs-section,
+pre.m3-docs-code-block .hljs-number,
+pre.m3-docs-code-block .hljs-symbol,
+pre.m3-docs-code-block .hljs-type,
+pre.m3-docs-code-block .hljs-variable {
+  color: var(--m3-docs-code-token-accent);
+}
diff --git a/m3-vue/storybook/utils/mdxCodeBlock.ts b/m3-vue/storybook/utils/mdxCodeBlock.ts
new file mode 100644
index 0000000..e705618
--- /dev/null
+++ b/m3-vue/storybook/utils/mdxCodeBlock.ts
@@ -0,0 +1,434 @@
+import '../stylesheets/mdxCodeBlock.scss'
+
+import React from 'react'
+
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react'
+
+import bash from 'highlight.js/lib/languages/bash'
+import css from 'highlight.js/lib/languages/css'
+import hljs from 'highlight.js/lib/core'
+import javascript from 'highlight.js/lib/languages/javascript'
+import json from 'highlight.js/lib/languages/json'
+import typescript from 'highlight.js/lib/languages/typescript'
+import xml from 'highlight.js/lib/languages/xml'
+
+type MdxCodeBlockProps = ComponentPropsWithoutRef<'code'>
+type MdxPreBlockProps = ComponentPropsWithoutRef<'pre'>
+type CodeElementProps = ComponentPropsWithoutRef<'code'> & {
+  'data-language'?: string
+}
+
+type HighlightPayload = {
+  html: string
+  language: string | null
+}
+
+type CodePayload = {
+  badgeLanguage: string | null
+  highlightLanguage: string | null
+  source: string
+}
+
+type RenderCodeBlockProps = {
+  badgeLanguage: string | null
+  className?: string
+  codeLanguage: string | null
+  copied: boolean
+  html: string
+  onCopy: () => void
+  restProps: Omit<MdxPreBlockProps, 'children' | 'className'>
+}
+
+const AUTO_DETECT_MAX_LENGTH = 5000
+const CODE_BLOCK_CLASS = 'm3-docs-code-block'
+const COPY_BUTTON_CLASS = 'm3-docs-code-copy'
+const COPY_RESET_DELAY_MS = 1500
+const COPY_STATE_ATTRIBUTE = 'data-copied'
+const COPY_SUCCESS_TEXT = 'Copied'
+const COPY_TEXT = 'Copy code'
+const LANGUAGE_BADGE_CLASS = 'm3-docs-code-language'
+const LANGUAGE_PREFIXES = ['language-', 'lang-']
+const PANEL_CLASS = 'm3-panel m3-panel_elevated-1'
+const NON_SPECIFIC_LANGUAGES = new Set(['plain', 'plaintext', 'text', 'txt'])
+
+const HIGHLIGHT_LANGUAGE_ALIASES: Record<string, string> = {
+  cjs: 'javascript',
+  html: 'xml',
+  js: 'javascript',
+  jsx: 'javascript',
+  markup: 'xml',
+  sh: 'bash',
+  shell: 'bash',
+  ts: 'typescript',
+  tsx: 'typescript',
+  vue: 'xml',
+}
+
+const BADGE_LANGUAGE_ALIASES: Record<string, string> = {
+  atom: 'html',
+  html: 'html',
+  js: 'javascript',
+  jsx: 'jsx',
+  json: 'json',
+  markup: 'html',
+  rss: 'html',
+  sh: 'bash',
+  shell: 'bash',
+  svg: 'html',
+  ts: 'typescript',
+  tsx: 'tsx',
+  vue: 'html',
+  xhtml: 'html',
+  xml: 'html',
+}
+
+const SUPPORTED_HIGHLIGHT_LANGUAGES = new Set([
+  'atom',
+  'bash',
+  'css',
+  'html',
+  'javascript',
+  'json',
+  'rss',
+  'svg',
+  'typescript',
+  'xhtml',
+  'xml',
+])
+
+let languagesRegistered = false
+
+const highlightRegistrations = [
+  ['bash', bash],
+  ['css', css],
+  ['javascript', javascript],
+  ['json', json],
+  ['typescript', typescript],
+  ['xml', xml],
+] as const
+
+function ensureLanguagesRegistered (): void {
+  if (languagesRegistered) return
+
+  highlightRegistrations.forEach(([name, definition]) => {
+    hljs.registerLanguage(name, definition)
+  })
+
+  languagesRegistered = true
+}
+
+function escapeHtml (value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('\'', '&#39;')
+}
+
+function normalizeLanguageFromClass (className?: string | null): string | null {
+  if (!className) return null
+
+  const tokens = className.split(/\s+/u)
+  for (const token of tokens) {
+    for (const prefix of LANGUAGE_PREFIXES) {
+      if (token.startsWith(prefix)) {
+        return token.slice(prefix.length)
+      }
+    }
+  }
+
+  return null
+}
+
+function normalizeLanguageToken (value?: string | null): string | null {
+  const normalized = value?.trim().toLowerCase()
+  return normalized || null
+}
+
+function isSpecificLanguage (language: string | null): language is string {
+  return Boolean(language && !NON_SPECIFIC_LANGUAGES.has(language))
+}
+
+function resolveHighlightLanguage (value?: string | null): string | null {
+  const normalized = normalizeLanguageToken(value)
+  if (!isSpecificLanguage(normalized)) return null
+
+  const aliasResolved = HIGHLIGHT_LANGUAGE_ALIASES[normalized] || normalized
+
+  return SUPPORTED_HIGHLIGHT_LANGUAGES.has(aliasResolved) ? aliasResolved : null
+}
+
+function resolveBadgeLanguage (value?: string | null): string | null {
+  const normalized = normalizeLanguageToken(value)
+  if (!isSpecificLanguage(normalized)) return null
+
+  return BADGE_LANGUAGE_ALIASES[normalized] || normalized
+}
+
+function inferBadgeLanguageFromSource (source: string): string | null {
+  if (!source.trim()) return null
+
+  const containsMarkup = /<[^>]+>/u.test(source)
+  const containsJsxComponent = /<[A-Z][A-Za-z0-9_.:-]*/u.test(source)
+  const containsJsxExpression = /\{[^}]+\}/u.test(source)
+
+  if (containsJsxComponent && containsJsxExpression) return 'tsx'
+  if (containsMarkup) return 'html'
+  return null
+}
+
+function extractText (node: ReactNode): string {
+  if (typeof node === 'string') return node
+  if (typeof node === 'number' || typeof node === 'boolean') return String(node)
+  if (Array.isArray(node)) return node.map(extractText).join('')
+
+  if (React.isValidElement<{ children?: ReactNode }>(node)) {
+    return extractText(node.props.children)
+  }
+
+  return ''
+}
+
+function findCodeElement (node: ReactNode): ReactElement<CodeElementProps> | null {
+  if (React.isValidElement<CodeElementProps>(node) && node.type === 'code') {
+    return node
+  }
+
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const codeElement = findCodeElement(child)
+      if (codeElement) return codeElement
+    }
+  }
+
+  if (React.isValidElement<{ children?: ReactNode }>(node)) {
+    return findCodeElement(node.props.children)
+  }
+
+  return null
+}
+
+function trimTrailingNewline (source: string): string {
+  return source.replace(/\r?\n$/u, '')
+}
+
+function highlightKnownLanguage (source: string, language: string): HighlightPayload {
+  return {
+    html: hljs.highlight(source, {
+      ignoreIllegals: true,
+      language,
+    }).value,
+    language,
+  }
+}
+
+function highlightAutoLanguage (source: string): HighlightPayload {
+  const autoResult = hljs.highlightAuto(source)
+
+  return {
+    html: autoResult.value,
+    language: autoResult.language || null,
+  }
+}
+
+function highlightSource (source: string, language: string | null): HighlightPayload {
+  ensureLanguagesRegistered()
+
+  if (source.trim() === '') {
+    return { html: '', language }
+  }
+
+  try {
+    if (language) return highlightKnownLanguage(source, language)
+    if (source.length > AUTO_DETECT_MAX_LENGTH) return { html: escapeHtml(source), language: null }
+    return highlightAutoLanguage(source)
+  } catch {
+    return { html: escapeHtml(source), language }
+  }
+}
+
+async function copyTextToClipboard (value: string): Promise<boolean> {
+  if (!value) return false
+
+  if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value)
+      return true
+    } catch {
+      // Fallback below for restricted clipboard contexts.
+    }
+  }
+
+  if (!document.body || typeof document.execCommand !== 'function') return false
+
+  const textarea = document.createElement('textarea')
+  textarea.value = value
+  textarea.setAttribute('readonly', 'true')
+  textarea.style.left = '-9999px'
+  textarea.style.opacity = '0'
+  textarea.style.pointerEvents = 'none'
+  textarea.style.position = 'fixed'
+  document.body.appendChild(textarea)
+  textarea.select()
+
+  try {
+    return document.execCommand('copy')
+  } finally {
+    textarea.remove()
+  }
+}
+
+function joinClassNames (...parts: Array<string | null | undefined>): string {
+  return parts.filter(Boolean).join(' ')
+}
+
+function pickRawLanguageToken (children: ReactNode, className?: string): string | null {
+  const codeElement = findCodeElement(children)
+  const codeProps = codeElement?.props
+
+  return normalizeLanguageToken(
+    codeProps?.['data-language'] ||
+      normalizeLanguageFromClass(codeProps?.className) ||
+      normalizeLanguageFromClass(className)
+  )
+}
+
+function resolveCodePayload (children: ReactNode, className?: string): CodePayload {
+  const codeElement = findCodeElement(children)
+  const source = trimTrailingNewline(extractText(codeElement?.props?.children ?? children))
+  const rawLanguage = pickRawLanguageToken(children, className)
+  const inferredBadgeLanguage = inferBadgeLanguageFromSource(source)
+  const badgeLanguage = inferredBadgeLanguage || resolveBadgeLanguage(rawLanguage)
+  const highlightLanguage = resolveHighlightLanguage(badgeLanguage || rawLanguage)
+
+  return {
+    badgeLanguage,
+    highlightLanguage,
+    source,
+  }
+}
+
+function useCopyState (source: string): { copied: boolean; onCopy: () => void } {
+  const [copied, setCopied] = React.useState(false)
+  const resetTimerRef = React.useRef<number | null>(null)
+
+  React.useEffect(() => () => {
+    if (resetTimerRef.current) {
+      window.clearTimeout(resetTimerRef.current)
+    }
+  }, [])
+
+  const onCopy = React.useCallback(() => {
+    void copyTextToClipboard(source).then((success) => {
+      if (!success) return
+
+      setCopied(true)
+      if (resetTimerRef.current) window.clearTimeout(resetTimerRef.current)
+
+      resetTimerRef.current = window.setTimeout(() => {
+        setCopied(false)
+        resetTimerRef.current = null
+      }, COPY_RESET_DELAY_MS)
+    })
+  }, [source])
+
+  return { copied, onCopy }
+}
+
+function getCodeClassName (codeLanguage: string | null): string {
+  return codeLanguage ? `hljs language-${codeLanguage}` : 'hljs'
+}
+
+function renderLanguageBadge (badgeLanguage: string | null): React.ReactElement {
+  return React.createElement(
+    'span',
+    {
+      className: LANGUAGE_BADGE_CLASS,
+    },
+    badgeLanguage || 'text'
+  )
+}
+
+function renderCopyButton (copied: boolean, onCopy: () => void): React.ReactElement {
+  return React.createElement(
+    'button',
+    {
+      type: 'button',
+      className: COPY_BUTTON_CLASS,
+      'aria-label': 'Copy code block',
+      [COPY_STATE_ATTRIBUTE]: copied ? 'true' : 'false',
+      onClick: onCopy,
+    },
+    copied ? COPY_SUCCESS_TEXT : COPY_TEXT
+  )
+}
+
+function renderCodeContent (codeHtml: string, codeLanguage: string | null): React.ReactElement {
+  return React.createElement('code', {
+    className: getCodeClassName(codeLanguage),
+    'data-language': codeLanguage || undefined,
+    dangerouslySetInnerHTML: {
+      __html: codeHtml,
+    },
+  })
+}
+
+function renderCodeBlock ({
+  badgeLanguage,
+  className,
+  codeLanguage,
+  copied,
+  html,
+  onCopy,
+  restProps,
+}: RenderCodeBlockProps): React.ReactElement {
+  return React.createElement(
+    'pre',
+    {
+      ...restProps,
+      className: joinClassNames(PANEL_CLASS, CODE_BLOCK_CLASS, className),
+      'data-language': codeLanguage || undefined,
+    },
+    renderLanguageBadge(badgeLanguage),
+    renderCopyButton(copied, onCopy),
+    renderCodeContent(html, codeLanguage)
+  )
+}
+
+export function MdxCodeBlock (props: MdxCodeBlockProps): React.ReactElement {
+  const { children, ...restProps } = props
+  return React.createElement('code', restProps, children)
+}
+
+export function MdxCodePreBlock (props: MdxPreBlockProps): React.ReactElement {
+  const { children, className, ...restProps } = props
+  const payload = React.useMemo(
+    () => resolveCodePayload(children, className),
+    [children, className]
+  )
+  const highlight = React.useMemo(
+    () => highlightSource(payload.source, payload.highlightLanguage),
+    [payload.highlightLanguage, payload.source]
+  )
+  const { copied, onCopy } = useCopyState(payload.source)
+  const resolvedCodeLanguage = highlight.language || payload.highlightLanguage
+  const resolvedBadgeLanguage =
+    payload.badgeLanguage ||
+    resolveBadgeLanguage(resolvedCodeLanguage) ||
+    inferBadgeLanguageFromSource(payload.source)
+
+  if (payload.source.trim() === '') {
+    return React.createElement('pre', { className, ...restProps }, children)
+  }
+
+  return renderCodeBlock({
+    badgeLanguage: resolvedBadgeLanguage,
+    className,
+    codeLanguage: resolvedCodeLanguage,
+    copied,
+    html: highlight.html || escapeHtml(payload.source),
+    onCopy,
+    restProps,
+  })
+}
diff --git a/yarn.lock b/yarn.lock
index 9b88e0c..93dc7c5 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1666,6 +1666,7 @@ __metadata:
     eslint-plugin-unused-imports: "npm:^4.4.1"
     flag-icons: "npm:^7.5.0"
     globals: "npm:^17.3.0"
+    highlight.js: "npm:^11.11.1"
     jsdom: "npm:^28.1.0"
     lodash.isequal: "npm:^4.5.0"
     playwright: "npm:^1.55.0"
@@ -1726,6 +1727,7 @@ __metadata:
     eslint-plugin-vue: "npm:^10.8.0"
     flag-icons: "npm:^7.5.0"
     globals: "npm:^17.3.0"
+    highlight.js: "npm:^11.11.1"
     jsdom: "npm:^28.1.0"
     lodash.isequal: "npm:^4.5.0"
     playwright: "npm:^1.55.0"
@@ -7356,6 +7358,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"highlight.js@npm:^11.11.1":
+  version: 11.11.1
+  resolution: "highlight.js@npm:11.11.1"
+  checksum: 10c0/40f53ac19dac079891fcefd5bd8a21cf2e8931fd47da5bd1dca73b7e4375c1defed0636fc39120c639b9c44119b7d110f7f0c15aa899557a5a1c8910f3c0144c
+  languageName: node
+  linkType: hard
+
 "hookable@npm:^5.5.3":
   version: 5.5.3
   resolution: "hookable@npm:5.5.3"

From b957c17a05c44bd9c815e94b3dcc0ebd090acc7a Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 22:26:03 +0400
Subject: [PATCH 07/37] docs: Storybook docs dark theme text colors were fixed

---
 m3-react/storybook/preview-head.html     | 34 +++++++++++++++++++++++-
 m3-react/storybook/utils/mdxCodeBlock.ts | 31 ++++++++++++++++-----
 m3-vue/storybook/preview-head.html       | 34 +++++++++++++++++++++++-
 m3-vue/storybook/utils/mdxCodeBlock.ts   | 31 ++++++++++++++++-----
 4 files changed, 114 insertions(+), 16 deletions(-)

diff --git a/m3-react/storybook/preview-head.html b/m3-react/storybook/preview-head.html
index 3610f4c..e63338e 100644
--- a/m3-react/storybook/preview-head.html
+++ b/m3-react/storybook/preview-head.html
@@ -12,6 +12,26 @@
             color: var(--m3-sys-on-surface) !important;
         }
 
+        :where(ul:not(.sb-anchor, .sb-unstyled, .sb-unstyled ul)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(ol:not(.sb-anchor, .sb-unstyled, .sb-unstyled ol)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(li:not(.sb-anchor, .sb-unstyled, .sb-unstyled li)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(code:not(.hljs, .hljs *)) {
+            border-radius: 8px;
+            background: var(--m3-sys-surface-container-highest) !important;
+            color: var(--m3-sys-on-surface) !important;
+            font-size: 0.875em;
+            padding: 0.125em 0.5em;
+        }
+
         :where(h2:not(.sb-anchor, .sb-unstyled, .sb-unstyled h2)) {
             border-color: var(--m3-state-layers-on-surface-opacity-020) !important;
         }
@@ -24,4 +44,16 @@
             }
         }
     }
-</style>
\ No newline at end of file
+
+    :where(.sbdocs-content ul, .sbdocs-content ol, .sbdocs-content li) {
+        color: var(--m3-sys-on-surface) !important;
+    }
+
+    :where(.sbdocs-content code:not(.hljs, .hljs *)) {
+        border-radius: 8px;
+        background: var(--m3-sys-surface-container-highest) !important;
+        color: var(--m3-sys-on-surface) !important;
+        font-size: 0.875em;
+        padding: 0.125em 0.5em;
+    }
+</style>
diff --git a/m3-react/storybook/utils/mdxCodeBlock.ts b/m3-react/storybook/utils/mdxCodeBlock.ts
index e705618..5a67c07 100644
--- a/m3-react/storybook/utils/mdxCodeBlock.ts
+++ b/m3-react/storybook/utils/mdxCodeBlock.ts
@@ -39,6 +39,11 @@ type RenderCodeBlockProps = {
   restProps: Omit<MdxPreBlockProps, 'children' | 'className'>
 }
 
+type ResolvedLanguages = {
+  badgeLanguage: string | null
+  codeLanguage: string | null
+}
+
 const AUTO_DETECT_MAX_LENGTH = 5000
 const CODE_BLOCK_CLASS = 'm3-docs-code-block'
 const COPY_BUTTON_CLASS = 'm3-docs-code-copy'
@@ -309,6 +314,19 @@ function resolveCodePayload (children: ReactNode, className?: string): CodePaylo
   }
 }
 
+function resolveRenderedLanguages (payload: CodePayload, highlight: HighlightPayload): ResolvedLanguages {
+  const codeLanguage = highlight.language || payload.highlightLanguage
+  const badgeLanguage =
+    payload.badgeLanguage ||
+    resolveBadgeLanguage(codeLanguage) ||
+    inferBadgeLanguageFromSource(payload.source)
+
+  return {
+    badgeLanguage,
+    codeLanguage,
+  }
+}
+
 function useCopyState (source: string): { copied: boolean; onCopy: () => void } {
   const [copied, setCopied] = React.useState(false)
   const resetTimerRef = React.useRef<number | null>(null)
@@ -412,20 +430,19 @@ export function MdxCodePreBlock (props: MdxPreBlockProps): React.ReactElement {
     [payload.highlightLanguage, payload.source]
   )
   const { copied, onCopy } = useCopyState(payload.source)
-  const resolvedCodeLanguage = highlight.language || payload.highlightLanguage
-  const resolvedBadgeLanguage =
-    payload.badgeLanguage ||
-    resolveBadgeLanguage(resolvedCodeLanguage) ||
-    inferBadgeLanguageFromSource(payload.source)
+  const languages = React.useMemo(
+    () => resolveRenderedLanguages(payload, highlight),
+    [payload, highlight]
+  )
 
   if (payload.source.trim() === '') {
     return React.createElement('pre', { className, ...restProps }, children)
   }
 
   return renderCodeBlock({
-    badgeLanguage: resolvedBadgeLanguage,
+    badgeLanguage: languages.badgeLanguage,
     className,
-    codeLanguage: resolvedCodeLanguage,
+    codeLanguage: languages.codeLanguage,
     copied,
     html: highlight.html || escapeHtml(payload.source),
     onCopy,
diff --git a/m3-vue/storybook/preview-head.html b/m3-vue/storybook/preview-head.html
index 3610f4c..e63338e 100644
--- a/m3-vue/storybook/preview-head.html
+++ b/m3-vue/storybook/preview-head.html
@@ -12,6 +12,26 @@
             color: var(--m3-sys-on-surface) !important;
         }
 
+        :where(ul:not(.sb-anchor, .sb-unstyled, .sb-unstyled ul)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(ol:not(.sb-anchor, .sb-unstyled, .sb-unstyled ol)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(li:not(.sb-anchor, .sb-unstyled, .sb-unstyled li)) {
+            color: var(--m3-sys-on-surface) !important;
+        }
+
+        :where(code:not(.hljs, .hljs *)) {
+            border-radius: 8px;
+            background: var(--m3-sys-surface-container-highest) !important;
+            color: var(--m3-sys-on-surface) !important;
+            font-size: 0.875em;
+            padding: 0.125em 0.5em;
+        }
+
         :where(h2:not(.sb-anchor, .sb-unstyled, .sb-unstyled h2)) {
             border-color: var(--m3-state-layers-on-surface-opacity-020) !important;
         }
@@ -24,4 +44,16 @@
             }
         }
     }
-</style>
\ No newline at end of file
+
+    :where(.sbdocs-content ul, .sbdocs-content ol, .sbdocs-content li) {
+        color: var(--m3-sys-on-surface) !important;
+    }
+
+    :where(.sbdocs-content code:not(.hljs, .hljs *)) {
+        border-radius: 8px;
+        background: var(--m3-sys-surface-container-highest) !important;
+        color: var(--m3-sys-on-surface) !important;
+        font-size: 0.875em;
+        padding: 0.125em 0.5em;
+    }
+</style>
diff --git a/m3-vue/storybook/utils/mdxCodeBlock.ts b/m3-vue/storybook/utils/mdxCodeBlock.ts
index e705618..5a67c07 100644
--- a/m3-vue/storybook/utils/mdxCodeBlock.ts
+++ b/m3-vue/storybook/utils/mdxCodeBlock.ts
@@ -39,6 +39,11 @@ type RenderCodeBlockProps = {
   restProps: Omit<MdxPreBlockProps, 'children' | 'className'>
 }
 
+type ResolvedLanguages = {
+  badgeLanguage: string | null
+  codeLanguage: string | null
+}
+
 const AUTO_DETECT_MAX_LENGTH = 5000
 const CODE_BLOCK_CLASS = 'm3-docs-code-block'
 const COPY_BUTTON_CLASS = 'm3-docs-code-copy'
@@ -309,6 +314,19 @@ function resolveCodePayload (children: ReactNode, className?: string): CodePaylo
   }
 }
 
+function resolveRenderedLanguages (payload: CodePayload, highlight: HighlightPayload): ResolvedLanguages {
+  const codeLanguage = highlight.language || payload.highlightLanguage
+  const badgeLanguage =
+    payload.badgeLanguage ||
+    resolveBadgeLanguage(codeLanguage) ||
+    inferBadgeLanguageFromSource(payload.source)
+
+  return {
+    badgeLanguage,
+    codeLanguage,
+  }
+}
+
 function useCopyState (source: string): { copied: boolean; onCopy: () => void } {
   const [copied, setCopied] = React.useState(false)
   const resetTimerRef = React.useRef<number | null>(null)
@@ -412,20 +430,19 @@ export function MdxCodePreBlock (props: MdxPreBlockProps): React.ReactElement {
     [payload.highlightLanguage, payload.source]
   )
   const { copied, onCopy } = useCopyState(payload.source)
-  const resolvedCodeLanguage = highlight.language || payload.highlightLanguage
-  const resolvedBadgeLanguage =
-    payload.badgeLanguage ||
-    resolveBadgeLanguage(resolvedCodeLanguage) ||
-    inferBadgeLanguageFromSource(payload.source)
+  const languages = React.useMemo(
+    () => resolveRenderedLanguages(payload, highlight),
+    [payload, highlight]
+  )
 
   if (payload.source.trim() === '') {
     return React.createElement('pre', { className, ...restProps }, children)
   }
 
   return renderCodeBlock({
-    badgeLanguage: resolvedBadgeLanguage,
+    badgeLanguage: languages.badgeLanguage,
     className,
-    codeLanguage: resolvedCodeLanguage,
+    codeLanguage: languages.codeLanguage,
     copied,
     html: highlight.html || escapeHtml(payload.source),
     onCopy,

From ddbd6e58458f22f1730607bc583c79a803b54349 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 22:29:52 +0400
Subject: [PATCH 08/37] fix(m3-vue): Storybook inline app id prefix was added

---
 m3-vue/storybook/components/Inline.ts | 59 +++++++++++++++++++--------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/m3-vue/storybook/components/Inline.ts b/m3-vue/storybook/components/Inline.ts
index 3593786..734fc4c 100644
--- a/m3-vue/storybook/components/Inline.ts
+++ b/m3-vue/storybook/components/Inline.ts
@@ -5,28 +5,53 @@ import { v4 } from 'uuid'
 
 import { createApp, h } from 'vue'
 
+const normalizeIdSegment = (value: string): string => {
+  return value.replace(/[^a-zA-Z0-9_-]/g, '')
+}
+
+const buildInlineIdPrefix = (reactId: string, uuid: string): string => {
+  return `m3-inline-${normalizeIdSegment(reactId)}-${normalizeIdSegment(uuid)}-`
+}
+
+const mountInlineApp = ({ appIdPrefix, children, is, props, root }) => {
+  const id = v4()
+
+  const app = createApp({
+    mounted () {
+      if (children) {
+        ReactDOM.render(
+          React.createElement(React.Fragment, {}, children),
+          document.getElementById(id)
+        )
+      }
+    },
+
+    render: () => h(is, props),
+  })
+
+  app.config.idPrefix = appIdPrefix
+  app.mount(root)
+
+  return () => app.unmount()
+}
+
 export default ({ is, children, tag, ...props }) => {
   const ref = React.useRef(null)
+  const reactId = React.useId()
+  const uuidRef = React.useRef(v4())
+  const appIdPrefix = React.useMemo(
+    () => buildInlineIdPrefix(reactId, uuidRef.current),
+    [reactId]
+  )
 
   React.useEffect(() => {
-    const id = v4()
-
-    const app = createApp({
-      mounted () {
-        if (children) {
-          ReactDOM.render(
-            React.createElement(React.Fragment, {}, children),
-            document.getElementById(id)
-          )
-        }
-      },
-
-      render: () => h(is, props),
+    return mountInlineApp({
+      appIdPrefix,
+      children,
+      is,
+      props,
+      root: ref.current,
     })
-
-    app.mount(ref.current)
-
-    return () => app.unmount()
   })
 
   return React.createElement(tag ?? 'div', {

From e48c08fde35689efc552dc7c0bbfa93def40b099 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 22:55:18 +0400
Subject: [PATCH 09/37] fix: Storybook mdx code block typecheck compatibility
 was fixed

---
 m3-react/storybook/utils/mdxCodeBlock.ts | 10 +++++-----
 m3-vue/storybook/utils/mdxCodeBlock.ts   | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/m3-react/storybook/utils/mdxCodeBlock.ts b/m3-react/storybook/utils/mdxCodeBlock.ts
index 5a67c07..17d22c7 100644
--- a/m3-react/storybook/utils/mdxCodeBlock.ts
+++ b/m3-react/storybook/utils/mdxCodeBlock.ts
@@ -124,11 +124,11 @@ function ensureLanguagesRegistered (): void {
 
 function escapeHtml (value: string): string {
   return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('\'', '&#39;')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }
 
 function normalizeLanguageFromClass (className?: string | null): string | null {
diff --git a/m3-vue/storybook/utils/mdxCodeBlock.ts b/m3-vue/storybook/utils/mdxCodeBlock.ts
index 5a67c07..17d22c7 100644
--- a/m3-vue/storybook/utils/mdxCodeBlock.ts
+++ b/m3-vue/storybook/utils/mdxCodeBlock.ts
@@ -124,11 +124,11 @@ function ensureLanguagesRegistered (): void {
 
 function escapeHtml (value: string): string {
   return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('\'', '&#39;')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }
 
 function normalizeLanguageFromClass (className?: string | null): string | null {

From 13628dba2456e79b285cf003d2a064f01e761287 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 22 Feb 2026 23:01:41 +0400
Subject: [PATCH 10/37] chore: Drafts directory ignore rule was added

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 7e65074..18e828f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,4 @@ node_modules/
 .yarnrc.yml
 *storybook.log
 .env
+drafts/

From 6cf8325cb2d10045de8f88731c93e4dad9c6aa6c Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 23 Feb 2026 00:11:13 +0400
Subject: [PATCH 11/37] docs: Added drafts mixed-format documentation workflow
 rules

---
 AGENTS.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 33ec614..3cffad9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,14 @@
   files include code covered by eslint rules (for example `*.js`, `*.ts`,
   and similar source files). Do not run `make eslint` for markdown-only
   changes (for example `*.md`).
+- When working on files under `drafts/`, keep documentation mixed-format:
+  narrative context in `*.md` plus machine-readable `*.yaml` sidecars for
+  structured entities (for example tokens, decisions, boundaries, variation
+  axes, invariants, confidence, and source references).
+- For `drafts/` work, create and update these YAML sidecars proactively
+  without requiring explicit user confirmation.
+- For `drafts/` work, automatically maintain links from the main draft
+  markdown file to related YAML sidecars.
 - Getter/helper functions must be side-effect free. Side effects are allowed
   only by prior agreement and only when there are strong, explicit reasons.
 

From b6503a8d112e41c1c109659850969dc07f956900 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 23 Feb 2026 20:19:09 +0400
Subject: [PATCH 12/37] feat(m3-vue): Added Experimental Surface stories and
 orchestration tests

---
 m3-vue/src/experimental/M3Surface.vue         | 471 +++++++++++
 m3-vue/storybook/components/M3Surface.mdx     |  13 +
 .../storybook/components/M3Surface.stories.ts |  98 +++
 .../examples/surface/SurfaceCardPageMorph.vue | 514 ++++++++++++
 .../surface/SurfaceNestedDialogsChain.vue     | 449 +++++++++++
 .../surface/SurfaceSideSheetAlwaysModal.vue   | 479 +++++++++++
 .../SurfaceSideSheetDismissToRemove.vue       | 601 ++++++++++++++
 .../surface/SurfaceSideSheetModalToWindow.vue | 751 ++++++++++++++++++
 .../surface/SurfaceSideSheetMorph.vue         | 592 ++++++++++++++
 m3-vue/tests/M3Surface.e2e.ts                 | 200 +++++
 m3-vue/tests/M3Surface.test.ts                | 111 +++
 m3-vue/tests/M3SurfaceStories.e2e.ts          | 427 ++++++++++
 .../fixtures/SurfaceExperimentHarness.vue     | 542 +++++++++++++
 13 files changed, 5248 insertions(+)
 create mode 100644 m3-vue/src/experimental/M3Surface.vue
 create mode 100644 m3-vue/storybook/components/M3Surface.mdx
 create mode 100644 m3-vue/storybook/components/M3Surface.stories.ts
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
 create mode 100644 m3-vue/tests/M3Surface.e2e.ts
 create mode 100644 m3-vue/tests/M3Surface.test.ts
 create mode 100644 m3-vue/tests/M3SurfaceStories.e2e.ts
 create mode 100644 m3-vue/tests/fixtures/SurfaceExperimentHarness.vue

diff --git a/m3-vue/src/experimental/M3Surface.vue b/m3-vue/src/experimental/M3Surface.vue
new file mode 100644
index 0000000..37acd88
--- /dev/null
+++ b/m3-vue/src/experimental/M3Surface.vue
@@ -0,0 +1,471 @@
+<template>
+    <Teleport v-if="isModal" :to="teleportTo">
+        <Transition name="m3-transition-fade">
+            <div
+                v-show="shown"
+                :style="{ zIndex: zIndex - 1 }"
+                class="m3-surface__scrim"
+                @click="onScrimClick"
+            />
+        </Transition>
+
+        <component
+            :is="tag"
+            v-show="shown"
+            :id="_id"
+            :class="surfaceClass"
+            :style="surfaceStyle"
+            v-bind="surfaceAttrs"
+        >
+            <slot />
+        </component>
+    </Teleport>
+
+    <component
+        :is="tag"
+        v-else
+        v-show="shown"
+        :id="_id"
+        :class="surfaceClass"
+        :style="surfaceStyle"
+        v-bind="surfaceAttrs"
+    >
+        <slot />
+    </component>
+</template>
+
+<script lang="ts" setup>
+import type { PropType } from 'vue'
+
+import {
+  computed,
+  useAttrs,
+} from 'vue'
+
+import {
+  isId,
+  isUndefined,
+  Or,
+} from '@modulify/m3-foundation/lib/predicates'
+
+import useId from '@/composables/id'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+type Length = string | number
+
+type SurfaceMode = 'standard' | 'modal'
+
+type SurfaceRole =
+  | 'auto'
+  | 'surface'
+  | 'surface-dim'
+  | 'surface-bright'
+  | 'surface-container-lowest'
+  | 'surface-container-low'
+  | 'surface-container'
+  | 'surface-container-high'
+  | 'surface-container-highest'
+
+type Anchor =
+  | 'none'
+  | 'center'
+  | 'start'
+  | 'end'
+  | 'top'
+  | 'bottom'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom-end'
+
+type AnchorStyleFactory = (inset: {
+  top: string,
+  right: string,
+  bottom: string,
+  left: string,
+}) => Record<string, string>
+
+const MODAL_ANCHOR_STYLE: Record<Anchor, AnchorStyleFactory> = {
+  none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
+  center: () => ({
+    top: '50%',
+    left: '50%',
+    right: 'auto',
+    bottom: 'auto',
+    transform: 'translate(-50%, -50%)',
+  }),
+  start: ({ top, bottom, left }) => ({ top, bottom, left, right: 'auto' }),
+  end: ({ top, right, bottom }) => ({ top, right, bottom, left: 'auto' }),
+  top: ({ top, left, right }) => ({ top, left, right, bottom: 'auto' }),
+  bottom: ({ bottom, left, right }) => ({ bottom, left, right, top: 'auto' }),
+  'top-start': ({ top, left }) => ({ top, left, right: 'auto', bottom: 'auto' }),
+  'top-end': ({ top, right }) => ({ top, right, left: 'auto', bottom: 'auto' }),
+  'bottom-start': ({ bottom, left }) => ({ bottom, left, right: 'auto', top: 'auto' }),
+  'bottom-end': ({ bottom, right }) => ({ bottom, right, left: 'auto', top: 'auto' }),
+}
+
+const props = defineProps({
+  id: {
+    type: null as unknown as PropType<string | undefined>,
+    validator: Or(isId, isUndefined),
+    default: undefined,
+  },
+
+  tag: {
+    type: String,
+    default: 'section',
+  },
+
+  shown: {
+    type: Boolean,
+    default: true,
+  },
+
+  mode: {
+    type: String as PropType<SurfaceMode>,
+    default: 'standard',
+  },
+
+  teleportTo: {
+    type: String,
+    default: 'body',
+  },
+
+  elevation: {
+    type: Number,
+    default: 0,
+    validator: (value: number) => Number.isInteger(value) && value >= 0 && value <= 5,
+  },
+
+  surfaceRole: {
+    type: String as PropType<SurfaceRole>,
+    default: 'auto',
+  },
+
+  fillWidth: {
+    type: Boolean,
+    default: true,
+  },
+
+  fillHeight: {
+    type: Boolean,
+    default: true,
+  },
+
+  width: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  height: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  minWidth: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  maxWidth: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  minHeight: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  maxHeight: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  rounding: {
+    type: null as unknown as PropType<Length>,
+    default: 0,
+  },
+
+  roundingTopLeft: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  roundingTopRight: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  roundingBottomRight: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  roundingBottomLeft: {
+    type: null as unknown as PropType<Length | null>,
+    default: null,
+  },
+
+  anchor: {
+    type: String as PropType<Anchor>,
+    default: 'none',
+  },
+
+  insetTop: {
+    type: null as unknown as PropType<Length>,
+    default: 0,
+  },
+
+  insetRight: {
+    type: null as unknown as PropType<Length>,
+    default: 0,
+  },
+
+  insetBottom: {
+    type: null as unknown as PropType<Length>,
+    default: 0,
+  },
+
+  insetLeft: {
+    type: null as unknown as PropType<Length>,
+    default: 0,
+  },
+
+  zIndex: {
+    type: Number,
+    default: 400,
+  },
+
+  transitionMs: {
+    type: Number,
+    default: 220,
+  },
+
+  transitionTiming: {
+    type: String,
+    default: 'cubic-bezier(0.2, 0, 0, 1)',
+  },
+
+  overflow: {
+    type: String,
+    default: 'visible',
+  },
+})
+
+const emit = defineEmits([
+  'update:shown',
+  'dismiss',
+])
+
+const attrs = useAttrs()
+
+function toLength(value: Length | null | undefined, fallback: string): string {
+  if (value == null) {
+    return fallback
+  }
+
+  return typeof value === 'number'
+    ? `${value}px`
+    : value
+}
+
+function isDefined<T>(value: T | null | undefined): value is T {
+  return value !== null && value !== undefined
+}
+
+const _id = useId('m3-surface', computed(() => props.id))
+
+const isModal = computed(() => props.mode === 'modal')
+
+const resolvedRole = computed<Exclude<SurfaceRole, 'auto'>>(() => {
+  if (props.surfaceRole !== 'auto') return props.surfaceRole
+
+  switch (props.elevation) {
+    case 0: return 'surface'
+    case 1: return 'surface-container-low'
+    case 2: return 'surface-container'
+    case 3: return 'surface-container-high'
+    case 4: return 'surface-container-highest'
+    default: return 'surface-bright'
+  }
+})
+
+const resolvedSizeStyle = computed(() => {
+  const width = isDefined(props.width)
+    ? toLength(props.width, 'auto')
+    : (props.fillWidth ? '100%' : 'auto')
+
+  const height = isDefined(props.height)
+    ? toLength(props.height, 'auto')
+    : (props.fillHeight ? '100%' : 'auto')
+
+  return {
+    width,
+    height,
+    minWidth: isDefined(props.minWidth) ? toLength(props.minWidth, '0px') : undefined,
+    maxWidth: isDefined(props.maxWidth) ? toLength(props.maxWidth, 'none') : undefined,
+    minHeight: isDefined(props.minHeight) ? toLength(props.minHeight, '0px') : undefined,
+    maxHeight: isDefined(props.maxHeight) ? toLength(props.maxHeight, 'none') : undefined,
+  }
+})
+
+const cornerRadiusStyle = computed(() => {
+  const base = toLength(props.rounding, '0px')
+
+  return {
+    borderTopLeftRadius: isDefined(props.roundingTopLeft) ? toLength(props.roundingTopLeft, base) : base,
+    borderTopRightRadius: isDefined(props.roundingTopRight) ? toLength(props.roundingTopRight, base) : base,
+    borderBottomRightRadius: isDefined(props.roundingBottomRight) ? toLength(props.roundingBottomRight, base) : base,
+    borderBottomLeftRadius: isDefined(props.roundingBottomLeft) ? toLength(props.roundingBottomLeft, base) : base,
+  }
+})
+
+const anchorStyle = computed(() => {
+  if (!isModal.value) {
+    return {}
+  }
+
+  const inset = {
+    top: toLength(props.insetTop, '0px'),
+    right: toLength(props.insetRight, '0px'),
+    bottom: toLength(props.insetBottom, '0px'),
+    left: toLength(props.insetLeft, '0px'),
+  }
+
+  return MODAL_ANCHOR_STYLE[props.anchor](inset)
+})
+
+const transition = computed(() => {
+  const duration = `${props.transitionMs}ms`
+
+  return [
+    `width ${duration} ${props.transitionTiming}`,
+    `height ${duration} ${props.transitionTiming}`,
+    `min-width ${duration} ${props.transitionTiming}`,
+    `max-width ${duration} ${props.transitionTiming}`,
+    `min-height ${duration} ${props.transitionTiming}`,
+    `max-height ${duration} ${props.transitionTiming}`,
+    `border-radius ${duration} ${props.transitionTiming}`,
+    `top ${duration} ${props.transitionTiming}`,
+    `right ${duration} ${props.transitionTiming}`,
+    `bottom ${duration} ${props.transitionTiming}`,
+    `left ${duration} ${props.transitionTiming}`,
+    `transform ${duration} ${props.transitionTiming}`,
+    `opacity ${duration} ${props.transitionTiming}`,
+    `background-color ${duration} ${props.transitionTiming}`,
+    `box-shadow ${duration} ${props.transitionTiming}`,
+  ].join(', ')
+})
+
+const surfaceAttrs = computed(() => {
+  return isModal.value ? {
+    role: 'dialog',
+    'aria-modal': 'true',
+    ...attrs,
+  } : {
+    role: 'region',
+    ...attrs,
+  }
+})
+
+const surfaceClass = computed(() => ({
+  'm3-surface': true,
+  'm3-surface_modal': isModal.value,
+  [`m3-surface_role-${resolvedRole.value}`]: true,
+  [`m3-surface_anchor-${props.anchor}`]: true,
+  [`m3-surface_elevation-${props.elevation}`]: true,
+}))
+
+const surfaceStyle = computed(() => {
+  return {
+    ...resolvedSizeStyle.value,
+    ...cornerRadiusStyle.value,
+    ...anchorStyle.value,
+    overflow: props.overflow,
+    transition: transition.value,
+    position: isModal.value ? 'fixed' : 'relative',
+    zIndex: isModal.value ? props.zIndex : undefined,
+  }
+})
+
+function onScrimClick() {
+  emit('update:shown', false)
+  emit('dismiss')
+}
+</script>
+
+<style scoped lang="scss">
+@use '../../../m3-foundation/assets/stylesheets/basics/palette' as palette;
+@use '../../../m3-foundation/assets/stylesheets/themes/dark' as dark;
+@use '../../../m3-foundation/assets/stylesheets/themes/light' as light;
+
+.m3-surface {
+  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{light.$m3-sys-light-surface});
+  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{palette.$m3-palette-neutral-100});
+  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{light.$m3-sys-light-surface-container});
+  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{light.$m3-sys-light-surface-container-high});
+  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+  --m3-surface-elevation-1: var(--m3-elevation-1, #{light.$m3-elevation-light-1});
+  --m3-surface-elevation-2: var(--m3-elevation-2, #{light.$m3-elevation-light-2});
+  --m3-surface-elevation-3: var(--m3-elevation-3, #{light.$m3-elevation-light-3});
+  --m3-surface-elevation-4: var(--m3-elevation-4, #{light.$m3-elevation-light-4});
+  --m3-surface-elevation-5: var(--m3-elevation-5, #{light.$m3-elevation-light-5});
+
+  display: block;
+  isolation: isolate;
+  box-sizing: border-box;
+
+  &_modal {
+    max-width: 100vw;
+    max-height: 100vh;
+  }
+
+  &_role-surface {
+    background-color: var(--m3-surface-role-surface-bg);
+  }
+
+  &_role-surface-dim               { background-color: var(--m3-surface-role-surface-dim-bg); }
+  &_role-surface-bright            { background-color: var(--m3-surface-role-surface-bright-bg); }
+  &_role-surface-container-lowest  { background-color: var(--m3-surface-role-container-lowest-bg); }
+  &_role-surface-container-low     { background-color: var(--m3-surface-role-container-low-bg); }
+  &_role-surface-container         { background-color: var(--m3-surface-role-container-bg); }
+  &_role-surface-container-high    { background-color: var(--m3-surface-role-container-high-bg); }
+  &_role-surface-container-highest { background-color: var(--m3-surface-role-container-highest-bg); }
+
+  &_elevation-0 { box-shadow: none; }
+  &_elevation-1 { box-shadow: var(--m3-surface-elevation-1); }
+  &_elevation-2 { box-shadow: var(--m3-surface-elevation-2); }
+  &_elevation-3 { box-shadow: var(--m3-surface-elevation-3); }
+  &_elevation-4 { box-shadow: var(--m3-surface-elevation-4); }
+  &_elevation-5 { box-shadow: var(--m3-surface-elevation-5); }
+
+  &__scrim {
+    position: fixed;
+    inset: 0;
+    background: color-mix(in srgb, var(--m3-sys-shadow, #{palette.$m3-palette-neutral-0}) 38%, transparent);
+  }
+}
+
+:global(html.m3-theme-dark) .m3-surface {
+  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
+  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
+  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
+  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
+  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
+  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{dark.$m3-sys-dark-surface-container});
+  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{dark.$m3-sys-dark-surface-container-high});
+  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
+  --m3-surface-elevation-1: var(--m3-elevation-1, #{dark.$m3-elevation-dark-1});
+  --m3-surface-elevation-2: var(--m3-elevation-2, #{dark.$m3-elevation-dark-2});
+  --m3-surface-elevation-3: var(--m3-elevation-3, #{dark.$m3-elevation-dark-3});
+  --m3-surface-elevation-4: var(--m3-elevation-4, #{dark.$m3-elevation-dark-4});
+  --m3-surface-elevation-5: var(--m3-elevation-5, #{dark.$m3-elevation-dark-5});
+}
+</style>
diff --git a/m3-vue/storybook/components/M3Surface.mdx b/m3-vue/storybook/components/M3Surface.mdx
new file mode 100644
index 0000000..5650ce0
--- /dev/null
+++ b/m3-vue/storybook/components/M3Surface.mdx
@@ -0,0 +1,13 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SurfaceStories from './M3Surface.stories'
+
+<Meta of={M3SurfaceStories} />
+
+# Surfaces
+
+- [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
+- [Card Replacing Page](?path=/story/components-m3surface--card-replacing-page)
+- [Side Sheet Modal Dismiss Removes Surface](?path=/story/components-m3surface--side-sheet-modal-dismiss-removes-surface)
+- [Side Sheet Always Modal Toggle](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
+- [Side Sheet Modal To Window](?path=/story/components-m3surface--side-sheet-modal-to-window)
+- [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
diff --git a/m3-vue/storybook/components/M3Surface.stories.ts b/m3-vue/storybook/components/M3Surface.stories.ts
new file mode 100644
index 0000000..dd0af65
--- /dev/null
+++ b/m3-vue/storybook/components/M3Surface.stories.ts
@@ -0,0 +1,98 @@
+import type {
+  Meta,
+  StoryObj,
+} from '@storybook/vue3'
+
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph.vue'
+import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain.vue'
+import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal.vue'
+import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove.vue'
+import SurfaceSideSheetModalToWindow from '../examples/surface/SurfaceSideSheetModalToWindow.vue'
+import SurfaceSideSheetMorph from '../examples/surface/SurfaceSideSheetMorph.vue'
+
+const meta = {
+  title: 'Components/M3Surface',
+  component: M3Surface,
+
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof M3Surface>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const SideSheetDockedToModal: Story = {
+  render: () => ({
+    components: {
+      SurfaceSideSheetMorph,
+    },
+
+    template: `
+        <SurfaceSideSheetMorph />
+    `,
+  }),
+}
+
+export const CardReplacingPage: Story = {
+  render: () => ({
+    components: {
+      SurfaceCardPageMorph,
+    },
+
+    template: `
+        <SurfaceCardPageMorph />
+    `,
+  }),
+}
+
+export const SideSheetModalDismissRemovesSurface: Story = {
+  render: () => ({
+    components: {
+      SurfaceSideSheetDismissToRemove,
+    },
+
+    template: `
+        <SurfaceSideSheetDismissToRemove />
+    `,
+  }),
+}
+
+export const SideSheetAlwaysModalToggle: Story = {
+  render: () => ({
+    components: {
+      SurfaceSideSheetAlwaysModal,
+    },
+
+    template: `
+        <SurfaceSideSheetAlwaysModal />
+    `,
+  }),
+}
+
+export const SideSheetModalToWindow: Story = {
+  render: () => ({
+    components: {
+      SurfaceSideSheetModalToWindow,
+    },
+
+    template: `
+        <SurfaceSideSheetModalToWindow />
+    `,
+  }),
+}
+
+export const NestedDialogsChain: Story = {
+  render: () => ({
+    components: {
+      SurfaceNestedDialogsChain,
+    },
+
+    template: `
+        <SurfaceNestedDialogsChain />
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
new file mode 100644
index 0000000..eaddf14
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
@@ -0,0 +1,514 @@
+<template>
+    <div
+        class="surface-card-page"
+        :data-card-expanded="expanded ? 'true' : 'false'"
+        data-testid="surface-card-page-root"
+    >
+        <M3Surface
+            class="surface-card-page__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-card-page__topbar-content">
+                <div>
+                    <strong>Surface orchestration: card replacing page</strong>
+                    <p>The same surface morphs between compact card and page-like container.</p>
+                </div>
+
+                <M3Button
+                    appearance="filled"
+                    :disabled="busy"
+                    data-testid="surface-card-toggle"
+                    @click="toggleCardMode"
+                >
+                    {{ expanded ? 'Return to card state' : 'Expand card to page state' }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            v-model:expanded="navExpanded"
+            class="surface-card-page__nav"
+            appearance="auto"
+            alignment="top"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Open navigation"
+                    @click="navExpanded = true"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <M3NavigationTab
+                label="Files"
+                :active="activeNavTab === 'files'"
+                @navigate="activeNavTab = 'files'; navExpanded = false"
+            >
+                <M3Icon name="folder" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Timeline"
+                :active="activeNavTab === 'timeline'"
+                @navigate="activeNavTab = 'timeline'; navExpanded = false"
+            >
+                <M3Icon name="schedule" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Tasks"
+                :active="activeNavTab === 'tasks'"
+                @navigate="activeNavTab = 'tasks'; navExpanded = false"
+            >
+                <M3Icon name="check_circle" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Analytics"
+                :active="activeNavTab === 'analytics'"
+                @navigate="activeNavTab = 'analytics'; navExpanded = false"
+            >
+                <M3Icon name="insights" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-card-page__body">
+            <div class="surface-card-page__workspace">
+                <M3Surface
+                    class="surface-card-page__header-card"
+                    :fill-height="false"
+                    :height="120"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Card-to-page transition playground</h3>
+                    <p>Original slot remains reserved while the morphing surface overlays the page area.</p>
+                </M3Surface>
+
+                <div
+                    ref="canvas"
+                    class="surface-card-page__canvas"
+                    data-testid="surface-card-canvas"
+                >
+                    <div
+                        v-if="!backgroundCollapsed"
+                        class="surface-card-page__grid"
+                        data-testid="surface-card-grid"
+                    >
+                        <div
+                            ref="originSlot"
+                            class="surface-card-page__origin-slot"
+                            :style="{ minHeight: `${originHeight}px` }"
+                            data-testid="surface-card-origin"
+                        />
+
+                        <M3Surface
+                            class="surface-card-page__grid-card"
+                            :fill-height="false"
+                            :height="184"
+                            :rounding="16"
+                            surface-role="surface-container-low"
+                            :elevation="1"
+                        >
+                            <strong>Static card A</strong>
+                            <p>Background content remains in flow.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-card-page__grid-card"
+                            :fill-height="false"
+                            :height="184"
+                            :rounding="16"
+                            surface-role="surface-container"
+                            :elevation="2"
+                        >
+                            <strong>Static card B</strong>
+                            <p>Independent surface in the same scene.</p>
+                        </M3Surface>
+                    </div>
+
+                    <div class="surface-card-page__overlay">
+                        <div
+                            class="surface-card-page__overlay-wrap"
+                            :style="overlayStyle"
+                            data-testid="surface-card-overlay-wrap"
+                        >
+                            <M3Surface
+                                :class="[
+                                    'surface-card-page__morph-surface',
+                                    expanded
+                                        ? 'surface-card-page__morph-surface_expanded'
+                                        : 'surface-card-page__morph-surface_compact',
+                                ]"
+                                :fill-width="true"
+                                :fill-height="true"
+                                :rounding="expanded ? 0 : 24"
+                                :transition-ms="TRANSITION_MS"
+                                transition-timing="cubic-bezier(0.2, 0, 0, 1)"
+                                :surface-role="expanded ? 'surface' : 'surface-container-low'"
+                                :elevation="expanded ? 0 : 1"
+                                overflow="auto"
+                                data-testid="surface-card-morph"
+                            >
+                                <h3>Morph target surface</h3>
+                                <p>
+                                    In compact mode this surface behaves like a card. In expanded mode it replaces the
+                                    page work area while keeping top bar and rail reserved.
+                                </p>
+
+                                <M3Surface
+                                    class="surface-card-page__morph-nested"
+                                    :fill-height="false"
+                                    :height="120"
+                                    :rounding="14"
+                                    :surface-role="expanded ? 'surface-container-low' : 'surface-container-high'"
+                                    :elevation="expanded ? 1 : 3"
+                                >
+                                    Nested surface demonstrates composability in both states.
+                                </M3Surface>
+                            </M3Surface>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  computed,
+  nextTick,
+  onMounted,
+  ref,
+} from 'vue'
+
+const expanded = ref(false)
+const busy = ref(false)
+const navExpanded = ref(false)
+const backgroundCollapsed = ref(false)
+const activeNavTab = ref<'files' | 'timeline' | 'tasks' | 'analytics'>('files')
+const TRANSITION_MS = 340
+
+const canvas = ref<HTMLElement | null>(null)
+const originSlot = ref<HTMLElement | null>(null)
+const originHeight = ref(220)
+
+const motion = ref({
+  top: 16,
+  left: 16,
+  width: 320,
+  height: 220,
+})
+
+const overlayStyle = computed(() => ({
+  top: `${motion.value.top}px`,
+  left: `${motion.value.left}px`,
+  width: `${motion.value.width}px`,
+  height: `${motion.value.height}px`,
+}))
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function measureOrigin() {
+  if (!canvas.value || !originSlot.value) {
+    return null
+  }
+
+  const canvasRect = canvas.value.getBoundingClientRect()
+  const originRect = originSlot.value.getBoundingClientRect()
+
+  return {
+    top: originRect.top - canvasRect.top,
+    left: originRect.left - canvasRect.left,
+    width: originRect.width,
+    height: originRect.height,
+  }
+}
+
+function measureExpanded() {
+  if (!canvas.value) {
+    return null
+  }
+
+  const canvasRect = canvas.value.getBoundingClientRect()
+
+  return {
+    top: 0,
+    left: 0,
+    width: canvasRect.width,
+    height: canvasRect.height,
+  }
+}
+
+async function initMotion() {
+  await nextTick()
+  await raf()
+
+  const origin = measureOrigin()
+  if (!origin) {
+    return
+  }
+
+  motion.value = origin
+  originHeight.value = origin.height
+}
+
+async function expandCard() {
+  backgroundCollapsed.value = false
+
+  const origin = measureOrigin()
+  if (origin) {
+    motion.value = origin
+    originHeight.value = origin.height
+  }
+
+  expanded.value = true
+  await nextTick()
+  await raf()
+
+  const full = measureExpanded()
+  if (!full) {
+    return
+  }
+
+  motion.value = full
+  await wait(TRANSITION_MS)
+  backgroundCollapsed.value = true
+}
+
+async function collapseCard() {
+  if (backgroundCollapsed.value) {
+    backgroundCollapsed.value = false
+    await nextTick()
+    await raf()
+  }
+
+  const full = measureExpanded()
+  if (full) {
+    motion.value = full
+  }
+
+  const origin = measureOrigin()
+  if (origin) {
+    originHeight.value = origin.height
+  }
+
+  expanded.value = false
+  await nextTick()
+  await raf()
+
+  if (!origin) {
+    return
+  }
+
+  motion.value = origin
+  await wait(TRANSITION_MS)
+}
+
+async function toggleCardMode() {
+  if (busy.value) {
+    return
+  }
+
+  busy.value = true
+
+  if (expanded.value) {
+    await collapseCard()
+    busy.value = false
+    return
+  }
+
+  await expandCard()
+  busy.value = false
+}
+
+onMounted(() => {
+  initMotion()
+})
+</script>
+
+<style scoped>
+.surface-card-page {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: rgba(103, 80, 164, 0.14);
+    --surface-accent-b: rgba(96, 125, 139, 0.16);
+    --surface-border: var(--m3-sys-outline-variant, rgba(73, 69, 79, 0.2));
+    --surface-shadow: var(--m3-elevation-1, 0 2px 6px rgba(0, 0, 0, 0.14));
+    --surface-canvas-bg: var(--m3-sys-surface-container-low, var(--m3-sys-surface, #fef7ff));
+    --surface-origin-slot: color-mix(in srgb, var(--m3-sys-primary, #6750a4) 12%, transparent);
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 14% 4%, var(--surface-accent-a), transparent 38%),
+        radial-gradient(circle at 90% 8%, var(--surface-accent-b), transparent 38%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+:global(html.m3-theme-dark) .surface-card-page {
+    --surface-accent-a: rgba(208, 188, 255, 0.18);
+    --surface-accent-b: rgba(128, 203, 196, 0.16);
+}
+
+.surface-card-page__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-card-page__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.8;
+}
+
+.surface-card-page__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+    .surface-card-page__body {
+        padding-left: var(--m3-navigation-drawer-width, 360px);
+    }
+}
+
+:global(.surface-card-page__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-card-page__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    min-height: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-card-page__topbar {
+    padding: 16px;
+}
+
+.surface-card-page__header-card {
+    padding: 18px;
+}
+
+.surface-card-page__header-card h3 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__header-card p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__canvas {
+    flex: 1 1 auto;
+    position: relative;
+    min-height: 0;
+    border-radius: 20px;
+    overflow: hidden;
+    background: var(--surface-canvas-bg);
+    box-shadow: 0 14px 28px var(--surface-shadow);
+}
+
+.surface-card-page__grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 12px;
+    padding: 14px;
+}
+
+.surface-card-page__grid > .surface-card-page__grid-card {
+    padding: 16px;
+}
+
+.surface-card-page__grid p {
+    margin: 6px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__origin-slot {
+    border-radius: 24px;
+    border: 1px dashed var(--surface-border);
+    background: var(--surface-origin-slot);
+}
+
+.surface-card-page__overlay {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+}
+
+.surface-card-page__overlay-wrap {
+    position: absolute;
+    transition:
+        top 340ms cubic-bezier(0.2, 0, 0, 1),
+        left 340ms cubic-bezier(0.2, 0, 0, 1),
+        width 340ms cubic-bezier(0.2, 0, 0, 1),
+        height 340ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+.surface-card-page__morph-surface {
+    pointer-events: auto;
+}
+
+.surface-card-page__morph-surface_compact {
+    padding: 20px;
+}
+
+.surface-card-page__morph-surface_expanded {
+    padding: 28px;
+}
+
+.surface-card-page__morph-nested {
+    padding: 14px;
+}
+
+.surface-card-page__morph-surface h3 {
+    margin: 0 0 8px;
+    font: 700 18px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__morph-surface p {
+    margin: 0 0 12px;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+    max-width: 70ch;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
new file mode 100644
index 0000000..c4e2838
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
@@ -0,0 +1,449 @@
+<template>
+    <div
+        class="surface-dialog-chain"
+        :data-top-level="`${topDialogLevel}`"
+    >
+        <M3Surface
+            class="surface-dialog-chain__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-dialog-chain__topbar-content">
+                <div>
+                    <strong>Surface orchestration: nested dialogs chain</strong>
+                    <p>Rail layout opens a nested dialog chain with one active scrim on the topmost dialog.</p>
+                </div>
+
+                <M3Button
+                    appearance="filled"
+                    :disabled="chainOpened"
+                    data-testid="surface-dialog-chain-open-root"
+                    @click="openDialog(0)"
+                >
+                    {{ chainOpened ? 'Dialog chain is open' : 'Open dialog chain' }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            class="surface-dialog-chain__nav"
+            appearance="rail"
+            alignment="top"
+        >
+            <M3NavigationTab
+                label="Inbox"
+                :active="activeNavTab === 'inbox'"
+                @navigate="activeNavTab = 'inbox'"
+            >
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Boards"
+                :active="activeNavTab === 'boards'"
+                @navigate="activeNavTab = 'boards'"
+            >
+                <M3Icon name="dashboard" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Archive"
+                :active="activeNavTab === 'archive'"
+                @navigate="activeNavTab = 'archive'"
+            >
+                <M3Icon name="archive" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Lab"
+                :active="activeNavTab === 'lab'"
+                @navigate="activeNavTab = 'lab'"
+            >
+                <M3Icon name="science" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-dialog-chain__body">
+            <div class="surface-dialog-chain__workspace">
+                <M3Surface
+                    class="surface-dialog-chain__workspace-intro"
+                    :fill-height="false"
+                    :height="124"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Workspace</h3>
+                    <p>Page composition stays stable while dialogs are stacked progressively.</p>
+                </M3Surface>
+
+                <M3Surface
+                    class="surface-dialog-chain__canvas"
+                    :rounding="20"
+                    surface-role="surface-container-low"
+                    :elevation="0"
+                >
+                    <h4>Background content</h4>
+                    <p>Open dialog 1 from top action, then continue through the chain.</p>
+                </M3Surface>
+            </div>
+        </div>
+
+        <template
+            v-for="(dialog, level) in dialogChain"
+            :key="dialog.id"
+        >
+            <M3Surface
+                v-if="dialogMounted[level]"
+                :class="[
+                    'surface-dialog-chain__dialog',
+                    `surface-dialog-chain__dialog_level-${level + 1}`,
+                ]"
+                :mode="dialogMode(level)"
+                :shown="dialogMounted[level]"
+                anchor="center"
+                :fill-width="false"
+                :fill-height="false"
+                :width="dialog.width"
+                :inset-top="24"
+                :inset-bottom="24"
+                :rounding="dialog.rounding"
+                :transition-ms="DIALOG_TRANSITION_MS"
+                :transition-timing="DIALOG_TRANSITION_EASING"
+                :z-index="dialogZIndex(level)"
+                surface-role="surface-container-highest"
+                :elevation="dialogElevation(level)"
+                overflow="visible"
+                :style="dialogInlineStyle(level)"
+                :data-testid="`surface-dialog-chain-level-${level + 1}`"
+                @dismiss="closeFrom(level)"
+            >
+                <div class="surface-dialog-chain__dialog-head">
+                    <h3>Dialog {{ level + 1 }} of {{ dialogChain.length }}</h3>
+
+                    <M3IconButton
+                        appearance="standard"
+                        :aria-label="`Close dialog ${level + 1}`"
+                        @click="closeFrom(level)"
+                    >
+                        <M3Icon name="close" />
+                    </M3IconButton>
+                </div>
+
+                <p>{{ dialog.description }}</p>
+
+                <div class="surface-dialog-chain__dialog-actions">
+                    <M3Button
+                        appearance="text"
+                        :data-testid="`surface-dialog-chain-close-${level + 1}`"
+                        @click="closeFrom(level)"
+                    >
+                        Close
+                    </M3Button>
+
+                    <M3Button
+                        v-if="hasNextDialog(level)"
+                        appearance="filled"
+                        :disabled="dialogMounted[level + 1]"
+                        :data-testid="`surface-dialog-chain-open-next-${level + 1}`"
+                        @click="openDialog(level + 1)"
+                    >
+                        Open dialog {{ level + 2 }}
+                    </M3Button>
+                </div>
+            </M3Surface>
+        </template>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  computed,
+  nextTick,
+  ref,
+} from 'vue'
+
+const DIALOG_TRANSITION_MS = 300
+const DIALOG_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const DIALOG_ENTRY_OFFSET_PX = 24
+const DIALOG_Z_INDEX_BASE = 560
+const DIALOG_Z_INDEX_STEP = 40
+
+type DialogSpec = {
+  id: string,
+  width: number,
+  rounding: number,
+  description: string,
+}
+
+const dialogChain: DialogSpec[] = [{
+  id: 'dialog-1',
+  width: 720,
+  rounding: 28,
+  description: 'First layer in the chain. It opens dialog 2.',
+}, {
+  id: 'dialog-2',
+  width: 620,
+  rounding: 26,
+  description: 'Second layer keeps the same controls and opens the next dialog.',
+}, {
+  id: 'dialog-3',
+  width: 520,
+  rounding: 24,
+  description: 'Third layer opens the final nested dialog.',
+}, {
+  id: 'dialog-4',
+  width: 440,
+  rounding: 22,
+  description: 'Final layer in this scenario: close only, no next dialog action.',
+}]
+
+const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
+const dialogMounted = ref<boolean[]>(Array.from({ length: dialogChain.length }, () => false))
+const dialogVisible = ref<boolean[]>(Array.from({ length: dialogChain.length }, () => false))
+
+const chainOpened = computed(() => dialogMounted.value.some(Boolean))
+
+const topDialogLevel = computed(() => {
+  for (let index = dialogChain.length - 1; index >= 0; index -= 1) {
+    if (dialogMounted.value[index]) {
+      return index
+    }
+  }
+
+  return -1
+})
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function hasNextDialog(level: number) {
+  return level < dialogChain.length - 1
+}
+
+function isTopDialog(level: number) {
+  return topDialogLevel.value === level
+}
+
+function dialogMode(level: number): 'standard' | 'modal' {
+  return isTopDialog(level) ? 'modal' : 'standard'
+}
+
+function dialogZIndex(level: number) {
+  return DIALOG_Z_INDEX_BASE + (level * DIALOG_Z_INDEX_STEP)
+}
+
+function dialogElevation(level: number) {
+  return Math.min(5, 2 + level)
+}
+
+function dialogInlineStyle(level: number) {
+  const visible = dialogVisible.value[level]
+
+  return {
+    position: 'fixed',
+    top: '50%',
+    left: '50%',
+    zIndex: dialogZIndex(level),
+    opacity: visible ? 1 : 0,
+    transform: visible
+      ? 'translate(-50%, -50%)'
+      : `translate(-50%, calc(-50% + ${DIALOG_ENTRY_OFFSET_PX}px))`,
+    transition: `opacity ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_EASING}, transform ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_EASING}`,
+    pointerEvents: visible ? 'auto' : 'none',
+  }
+}
+
+async function openDialog(level: number) {
+  if (level < 0 || level >= dialogChain.length || dialogMounted.value[level]) {
+    return
+  }
+
+  if (level > 0 && !dialogMounted.value[level - 1]) {
+    return
+  }
+
+  dialogMounted.value[level] = true
+  dialogVisible.value[level] = false
+
+  await nextTick()
+  await raf()
+
+  dialogVisible.value[level] = true
+}
+
+async function closeFrom(level: number) {
+  if (level < 0 || level >= dialogChain.length) {
+    return
+  }
+
+  let hasMountedDialog = false
+  for (let index = level; index < dialogChain.length; index += 1) {
+    if (dialogMounted.value[index]) {
+      hasMountedDialog = true
+      break
+    }
+  }
+
+  if (!hasMountedDialog) {
+    return
+  }
+
+  for (let index = dialogChain.length - 1; index >= level; index -= 1) {
+    if (dialogMounted.value[index]) {
+      dialogVisible.value[index] = false
+    }
+  }
+
+  await wait(DIALOG_TRANSITION_MS)
+
+  for (let index = level; index < dialogChain.length; index += 1) {
+    dialogMounted.value[index] = false
+    dialogVisible.value[index] = false
+  }
+}
+</script>
+
+<style scoped>
+.surface-dialog-chain {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+    --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+    --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+        radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-dialog-chain__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-dialog-chain__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.82;
+}
+
+.surface-dialog-chain__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+:global(.surface-dialog-chain__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-dialog-chain__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-dialog-chain__topbar {
+    padding: 16px;
+}
+
+.surface-dialog-chain__workspace-intro {
+    padding: 20px;
+}
+
+.surface-dialog-chain__workspace h3,
+.surface-dialog-chain__workspace h4 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__workspace p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__canvas {
+    flex: 1 1 auto;
+    min-height: 220px;
+    padding: 18px;
+    background: var(--surface-layout-bg);
+}
+
+:global(.surface-dialog-chain__dialog) {
+    overflow: visible;
+}
+
+:global(.surface-dialog-chain__dialog_level-1) {
+    padding: 24px;
+}
+
+:global(.surface-dialog-chain__dialog_level-2) {
+    padding: 22px;
+}
+
+:global(.surface-dialog-chain__dialog_level-3) {
+    padding: 20px;
+}
+
+:global(.surface-dialog-chain__dialog_level-4) {
+    padding: 18px;
+}
+
+:global(.surface-dialog-chain__dialog-head) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+}
+
+:global(.surface-dialog-chain__dialog-head h3) {
+    margin: 0;
+    font: 700 18px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-dialog-chain__dialog p) {
+    margin: 8px 0 0;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-dialog-chain__dialog-actions) {
+    margin-top: 14px;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
new file mode 100644
index 0000000..560df11
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
@@ -0,0 +1,479 @@
+<template>
+    <div
+        class="surface-side-sheet"
+        :data-modal-mounted="modalMounted ? 'true' : 'false'"
+        data-testid="surface-always-root"
+    >
+        <M3Surface
+            class="surface-side-sheet__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-side-sheet__topbar-content">
+                <div>
+                    <strong>Surface orchestration: always-modal side sheet</strong>
+                    <p>The side sheet exists only in modal mode and can be shown repeatedly from the page header.</p>
+                </div>
+
+                <M3Button
+                    appearance="tonal"
+                    :disabled="transitioning || modalMounted"
+                    data-testid="surface-always-open"
+                    @click="openModal"
+                >
+                    {{ modalMounted ? 'Modal side sheet is open' : 'Show modal side sheet' }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            v-model:expanded="navExpanded"
+            class="surface-side-sheet__nav"
+            appearance="auto"
+            alignment="top"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Open navigation"
+                    @click="navExpanded = true"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <M3NavigationTab
+                label="Inbox"
+                :active="activeNavTab === 'inbox'"
+                @navigate="activeNavTab = 'inbox'; navExpanded = false"
+            >
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Boards"
+                :active="activeNavTab === 'boards'"
+                @navigate="activeNavTab = 'boards'; navExpanded = false"
+            >
+                <M3Icon name="dashboard" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Archive"
+                :active="activeNavTab === 'archive'"
+                @navigate="activeNavTab = 'archive'; navExpanded = false"
+            >
+                <M3Icon name="archive" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Lab"
+                :active="activeNavTab === 'lab'"
+                @navigate="activeNavTab = 'lab'; navExpanded = false"
+            >
+                <M3Icon name="science" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-side-sheet__body">
+            <div class="surface-side-sheet__workspace">
+                <M3Surface
+                    class="surface-side-sheet__header-card"
+                    :fill-height="false"
+                    :height="120"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Workspace surfaces</h3>
+                    <p>Background layout stays in flow while the side sheet appears as a modal overlay.</p>
+                </M3Surface>
+
+                <div
+                    ref="layoutRoot"
+                    class="surface-side-sheet__layout"
+                    data-testid="surface-always-layout"
+                >
+                    <main
+                        class="surface-side-sheet__content-grid"
+                        data-testid="surface-always-content-grid"
+                    >
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-lowest"
+                            :elevation="0"
+                        >
+                            <strong>surface-container-lowest</strong>
+                            <p>Read-heavy content block in the page flow.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-low"
+                            :elevation="1"
+                        >
+                            <strong>surface-container-low</strong>
+                            <p>Secondary block with mild emphasis.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-high"
+                            :elevation="3"
+                        >
+                            <strong>surface-container-high</strong>
+                            <p>Contextual utility content.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-dim"
+                            :elevation="0"
+                        >
+                            <strong>surface-dim</strong>
+                            <p>Low-brightness complementary content.</p>
+                        </M3Surface>
+                    </main>
+
+                    <M3Surface
+                        v-if="modalMounted"
+                        class="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                        mode="modal"
+                        :shown="modalVisible"
+                        anchor="end"
+                        :fill-width="false"
+                        :fill-height="false"
+                        :width="sideSheetWidth"
+                        :inset-top="MODAL_INSET_TOP"
+                        :inset-right="modalInsetRight"
+                        :inset-bottom="MODAL_INSET_BOTTOM"
+                        :rounding-top-left="modalRadiusLeft"
+                        :rounding-bottom-left="modalRadiusLeft"
+                        :rounding-top-right="0"
+                        :rounding-bottom-right="0"
+                        :transition-ms="PANEL_TRANSITION_MS"
+                        :transition-timing="PANEL_TRANSITION_EASING"
+                        :z-index="520"
+                        surface-role="surface-container-high"
+                        :elevation="modalElevation"
+                        overflow="auto"
+                        data-testid="surface-always-panel"
+                        @dismiss="closeModal"
+                    >
+                        <div class="surface-side-sheet__modal-header">
+                            <h3>Modal side sheet</h3>
+
+                            <M3IconButton
+                                class="surface-side-sheet__modal-close"
+                                appearance="standard"
+                                aria-label="Close modal side sheet"
+                                :disabled="transitioning"
+                                data-testid="surface-always-close"
+                                @click="closeModal"
+                            >
+                                <M3Icon name="close" />
+                            </M3IconButton>
+                        </div>
+
+                        <p>This side sheet is always modal and never returns to a docked state.</p>
+                        <p>Close actions: scrim click or close button inside the panel.</p>
+                        <p class="surface-side-sheet__meta">
+                            Fixed width: {{ sideSheetWidth }}px
+                        </p>
+                    </M3Surface>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  onBeforeUnmount,
+  onMounted,
+  nextTick,
+  ref,
+} from 'vue'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = 300
+const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const SCRIM_FADE_MS = 500
+
+const navExpanded = ref(false)
+const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
+const sideSheetWidth = ref(320)
+const modalInsetRight = ref(-(sideSheetWidth.value + 12))
+const modalRadiusLeft = ref(0)
+const modalElevation = ref(0)
+const modalMounted = ref(false)
+const modalVisible = ref(false)
+const transitioning = ref(false)
+const layoutRoot = ref<HTMLElement | null>(null)
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function hiddenInsetRight() {
+  return -(sideSheetWidth.value + 12)
+}
+
+function resolveSheetWidthFromLayout() {
+  const layoutWidth = Math.round(layoutRoot.value?.getBoundingClientRect().width ?? window.innerWidth)
+  const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+  return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+}
+
+function syncFixedWidth() {
+  sideSheetWidth.value = resolveSheetWidthFromLayout()
+
+  if (!modalMounted.value) {
+    modalInsetRight.value = hiddenInsetRight()
+  }
+}
+
+async function openModal() {
+  if (transitioning.value || modalMounted.value) {
+    return
+  }
+
+  transitioning.value = true
+  syncFixedWidth()
+
+  modalRadiusLeft.value = 0
+  modalElevation.value = 0
+  modalInsetRight.value = hiddenInsetRight()
+  modalMounted.value = true
+
+  await nextTick()
+  await raf()
+
+  modalVisible.value = true
+  await nextTick()
+  await raf()
+
+  modalInsetRight.value = MODAL_INSET_END
+  modalRadiusLeft.value = 28
+  modalElevation.value = 1
+  await wait(PANEL_TRANSITION_MS)
+  transitioning.value = false
+}
+
+async function closeModal() {
+  if (transitioning.value || !modalMounted.value) {
+    return
+  }
+
+  transitioning.value = true
+  modalInsetRight.value = hiddenInsetRight()
+  modalRadiusLeft.value = 0
+  modalElevation.value = 0
+  await wait(PANEL_TRANSITION_MS)
+
+  modalVisible.value = false
+  await wait(SCRIM_FADE_MS)
+  modalMounted.value = false
+  transitioning.value = false
+}
+
+function onResize() {
+  syncFixedWidth()
+}
+
+onMounted(() => {
+  syncFixedWidth()
+  window.addEventListener('resize', onResize, { passive: true })
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', onResize)
+})
+</script>
+
+<style scoped>
+.surface-side-sheet {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+    --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+    --surface-border: var(--m3-sys-outline-variant, var(--md-sys-color-outline-variant, rgba(73, 69, 79, 0.2)));
+    --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+    --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+    --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+        radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-side-sheet__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.82;
+}
+
+.surface-side-sheet__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+    .surface-side-sheet__body {
+        padding-left: var(--m3-navigation-drawer-width, 360px);
+    }
+}
+
+:global(.surface-side-sheet__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-side-sheet__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-side-sheet__topbar {
+    padding: 16px;
+}
+
+.surface-side-sheet__header-card {
+    padding: 18px;
+}
+
+.surface-side-sheet__header-card h3 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__header-card p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__layout {
+    min-height: 440px;
+    display: flex;
+    overflow: hidden;
+    border-radius: 20px;
+    background: var(--surface-layout-bg);
+    box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet__content-grid {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    grid-auto-rows: min-content;
+    gap: 12px;
+    padding: 14px;
+    align-content: flex-start;
+    align-items: start;
+    background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet__content-grid > .surface-side-sheet__grid-surface {
+    padding: 18px;
+}
+
+.surface-side-sheet__content-grid p {
+    margin: 6px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet h3) {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet_modal) {
+    padding: 24px;
+}
+
+:global(.surface-side-sheet__modal-header) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+}
+
+:global(.surface-side-sheet__modal-close) {
+    flex: 0 0 auto;
+}
+
+:global(.surface-side-sheet__sheet p) {
+    margin: 0 0 8px;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet .surface-side-sheet__meta) {
+    margin-top: 14px;
+    font: 600 11px/1.2 'Trebuchet MS', 'Segoe UI', sans-serif;
+    letter-spacing: 0.04em;
+    opacity: 0.76;
+    text-transform: uppercase;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
new file mode 100644
index 0000000..12b7199
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
@@ -0,0 +1,601 @@
+<template>
+    <div class="surface-side-sheet">
+        <M3Surface
+            class="surface-side-sheet__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-side-sheet__topbar-content">
+                <div>
+                    <strong>Surface orchestration: side sheet remove flow</strong>
+                    <p>After modal close, the side sheet is removed from the page instead of returning to docked mode.</p>
+                </div>
+
+                <M3Button
+                    appearance="tonal"
+                    :disabled="transitioning || sheetRemoved"
+                    @click="handleTopbarAction"
+                >
+                    {{
+                        sheetRemoved
+                            ? 'Side sheet removed'
+                            : (sideSheetModal ? 'Close modal and remove sheet' : 'Switch to modal sheet')
+                    }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            v-model:expanded="navExpanded"
+            class="surface-side-sheet__nav"
+            appearance="auto"
+            alignment="top"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Open navigation"
+                    @click="navExpanded = true"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <M3NavigationTab
+                label="Inbox"
+                :active="activeNavTab === 'inbox'"
+                @navigate="activeNavTab = 'inbox'; navExpanded = false"
+            >
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Boards"
+                :active="activeNavTab === 'boards'"
+                @navigate="activeNavTab = 'boards'; navExpanded = false"
+            >
+                <M3Icon name="dashboard" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Archive"
+                :active="activeNavTab === 'archive'"
+                @navigate="activeNavTab = 'archive'; navExpanded = false"
+            >
+                <M3Icon name="archive" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Lab"
+                :active="activeNavTab === 'lab'"
+                @navigate="activeNavTab = 'lab'; navExpanded = false"
+            >
+                <M3Icon name="science" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-side-sheet__body">
+            <div class="surface-side-sheet__workspace">
+                <M3Surface
+                    class="surface-side-sheet__header-card"
+                    :fill-height="false"
+                    :height="120"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Workspace surfaces</h3>
+                    <p>Static blocks keep flow while side-sheet changes modality.</p>
+                </M3Surface>
+
+                <div
+                    ref="layoutRoot"
+                    class="surface-side-sheet__layout"
+                >
+                    <main class="surface-side-sheet__content-grid">
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-lowest"
+                            :elevation="0"
+                        >
+                            <strong>surface-container-lowest</strong>
+                            <p>Read-heavy content block in the page flow.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-low"
+                            :elevation="1"
+                        >
+                            <strong>surface-container-low</strong>
+                            <p>Secondary block with mild emphasis.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-high"
+                            :elevation="3"
+                        >
+                            <strong>surface-container-high</strong>
+                            <p>Contextual utility content.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-dim"
+                            :elevation="0"
+                        >
+                            <strong>surface-dim</strong>
+                            <p>Low-brightness complementary content.</p>
+                        </M3Surface>
+                    </main>
+
+                    <div
+                        v-if="!sheetRemoved"
+                        ref="dockedHost"
+                        class="surface-side-sheet__docked-host"
+                        :style="{ width: `${sideSheetDockedWidth}px` }"
+                    >
+                        <M3Surface
+                            v-if="!sideSheetModal && !sheetRemoved"
+                            class="surface-side-sheet__sheet"
+                            :fill-width="true"
+                            :fill-height="true"
+                            :rounding="0"
+                            surface-role="surface-container-low"
+                            :elevation="0"
+                            overflow="auto"
+                        >
+                            <h3>Docked side sheet</h3>
+                            <p>Coplanar layout participant with fixed width per layout region.</p>
+                            <p>Main content remains interactive.</p>
+                            <p class="surface-side-sheet__meta">
+                                Fixed width: {{ sideSheetWidth }}px
+                            </p>
+                        </M3Surface>
+                    </div>
+
+                    <M3Surface
+                        v-if="modalShown"
+                        class="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                        mode="modal"
+                        :shown="modalVisible"
+                        anchor="end"
+                        :fill-width="false"
+                        :fill-height="false"
+                        :width="modalWidth"
+                        :inset-top="modalInsetTop"
+                        :inset-right="modalInsetRight"
+                        :inset-bottom="modalInsetBottom"
+                        :rounding-top-left="modalRadiusLeft"
+                        :rounding-bottom-left="modalRadiusLeft"
+                        :rounding-top-right="0"
+                        :rounding-bottom-right="0"
+                        :transition-ms="PANEL_TRANSITION_MS"
+                        :transition-timing="PANEL_TRANSITION_EASING"
+                        :z-index="520"
+                        :surface-role="modalRole"
+                        :elevation="modalElevation"
+                        overflow="auto"
+                        @dismiss="closeModalFromPanel"
+                    >
+                        <div class="surface-side-sheet__modal-header">
+                            <h3>Modal side sheet</h3>
+
+                            <M3IconButton
+                                v-if="sideSheetModal"
+                                class="surface-side-sheet__modal-close"
+                                appearance="standard"
+                                aria-label="Close modal side sheet"
+                                :disabled="transitioning"
+                                @click="closeModalFromPanel"
+                            >
+                                <M3Icon name="close" />
+                            </M3IconButton>
+                        </div>
+
+                        <p>Layer rebind: docked layer to modal layer.</p>
+                        <p>Anchored to end/right edge with full-height modal surface.</p>
+                        <p>Closing this modal removes the side sheet from the scene.</p>
+                        <p class="surface-side-sheet__meta">
+                            Fixed width: {{ modalWidth }}px
+                        </p>
+                    </M3Surface>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  onBeforeUnmount,
+  onMounted,
+  nextTick,
+  ref,
+} from 'vue'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = 300
+const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const SCRIM_FADE_MS = 500
+
+const navExpanded = ref(false)
+const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
+const sideSheetModal = ref(false)
+const sheetRemoved = ref(false)
+const sideSheetWidth = ref(320)
+const sideSheetDockedWidth = ref(sideSheetWidth.value)
+const modalShown = ref(false)
+const modalVisible = ref(false)
+const modalWidth = ref(sideSheetWidth.value)
+const modalInsetTop = ref(MODAL_INSET_TOP)
+const modalInsetRight = ref(-(sideSheetWidth.value + 12))
+const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
+const modalRadiusLeft = ref(0)
+const modalElevation = ref(0)
+const modalRole = ref<'surface-container-low' | 'surface-container-high'>('surface-container-low')
+const transitioning = ref(false)
+const dockedHost = ref<HTMLElement | null>(null)
+const layoutRoot = ref<HTMLElement | null>(null)
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function hiddenInsetRight() {
+  return -(modalWidth.value + 12)
+}
+
+function resolveSheetWidthFromLayout() {
+  const layoutWidth = Math.round(layoutRoot.value?.getBoundingClientRect().width ?? window.innerWidth)
+  const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+  return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+}
+
+function syncFixedWidth() {
+  const nextWidth = resolveSheetWidthFromLayout()
+
+  sideSheetWidth.value = nextWidth
+  modalWidth.value = nextWidth
+
+  if (sheetRemoved.value) {
+    sideSheetDockedWidth.value = 0
+    modalInsetRight.value = hiddenInsetRight()
+
+    return
+  }
+
+  if (!sideSheetModal.value) {
+    sideSheetDockedWidth.value = nextWidth
+    modalInsetRight.value = hiddenInsetRight()
+  }
+}
+
+function measureDockedGeometry() {
+  const host = dockedHost.value
+  if (!host) {
+    return null
+  }
+
+  const rect = host.getBoundingClientRect()
+
+  return {
+    width: Math.round(rect.width),
+    insetTop: Math.round(rect.top),
+    insetRight: Math.round(window.innerWidth - rect.right),
+    insetBottom: Math.round(window.innerHeight - rect.bottom),
+  }
+}
+
+function setModalGeometryFromDocked() {
+  const docked = measureDockedGeometry()
+
+  modalWidth.value = docked?.width ?? sideSheetWidth.value
+  modalInsetTop.value = docked?.insetTop ?? MODAL_INSET_TOP
+  modalInsetRight.value = docked?.insetRight ?? MODAL_INSET_END
+  modalInsetBottom.value = docked?.insetBottom ?? MODAL_INSET_BOTTOM
+}
+
+function setModalGeometryTarget() {
+  modalWidth.value = sideSheetWidth.value
+  modalInsetTop.value = MODAL_INSET_TOP
+  modalInsetRight.value = MODAL_INSET_END
+  modalInsetBottom.value = MODAL_INSET_BOTTOM
+}
+
+async function switchDockedToModal() {
+  if (sheetRemoved.value) {
+    return
+  }
+
+  syncFixedWidth()
+  setModalGeometryFromDocked()
+
+  modalRadiusLeft.value = 0
+  modalElevation.value = 0
+  modalRole.value = 'surface-container-low'
+  modalVisible.value = false
+  modalShown.value = true
+
+  await nextTick()
+  await raf()
+
+  modalVisible.value = true
+  await nextTick()
+  await raf()
+
+  sideSheetModal.value = true
+  sideSheetDockedWidth.value = 0
+  setModalGeometryTarget()
+  modalRadiusLeft.value = 28
+  modalElevation.value = 1
+  modalRole.value = 'surface-container-high'
+  await wait(PANEL_TRANSITION_MS)
+}
+
+async function dismissModalAndRemove() {
+  if (!sideSheetModal.value) {
+    return
+  }
+
+  modalInsetTop.value = MODAL_INSET_TOP
+  modalInsetBottom.value = MODAL_INSET_BOTTOM
+  modalInsetRight.value = hiddenInsetRight()
+  modalElevation.value = 0
+  modalRole.value = 'surface-container-low'
+  modalRadiusLeft.value = 0
+  await wait(PANEL_TRANSITION_MS)
+  modalVisible.value = false
+  await wait(SCRIM_FADE_MS)
+  modalShown.value = false
+  sideSheetModal.value = false
+  sideSheetDockedWidth.value = 0
+  sheetRemoved.value = true
+}
+
+async function handleTopbarAction() {
+  if (transitioning.value) {
+    return
+  }
+
+  if (sheetRemoved.value) {
+    return
+  }
+
+  transitioning.value = true
+
+  if (!sideSheetModal.value) {
+    await switchDockedToModal()
+    transitioning.value = false
+    return
+  }
+
+  await dismissModalAndRemove()
+  transitioning.value = false
+}
+
+async function closeModalFromPanel() {
+  if (!sideSheetModal.value || transitioning.value) {
+    return
+  }
+
+  transitioning.value = true
+  await dismissModalAndRemove()
+  transitioning.value = false
+}
+
+function onResize() {
+  syncFixedWidth()
+}
+
+onMounted(() => {
+  syncFixedWidth()
+  window.addEventListener('resize', onResize, { passive: true })
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', onResize)
+})
+</script>
+
+<style scoped>
+.surface-side-sheet {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+    --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+    --surface-border: var(--m3-sys-outline-variant, var(--md-sys-color-outline-variant, rgba(73, 69, 79, 0.2)));
+    --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+    --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+    --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-panel-transition-ms: 300ms;
+    --surface-panel-transition-easing: cubic-bezier(0.2, 0, 0, 1);
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+        radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-side-sheet__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.82;
+}
+
+.surface-side-sheet__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+    .surface-side-sheet__body {
+        padding-left: var(--m3-navigation-drawer-width, 360px);
+    }
+}
+
+:global(.surface-side-sheet__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-side-sheet__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-side-sheet__topbar {
+    padding: 16px;
+}
+
+.surface-side-sheet__header-card {
+    padding: 18px;
+}
+
+.surface-side-sheet__header-card h3 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__header-card p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__layout {
+    min-height: 440px;
+    display: flex;
+    overflow: hidden;
+    border-radius: 20px;
+    background: var(--surface-layout-bg);
+    box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet__content-grid {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    grid-auto-rows: min-content;
+    gap: 12px;
+    padding: 14px;
+    align-content: flex-start;
+    align-items: start;
+    background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet__content-grid > .surface-side-sheet__grid-surface {
+    padding: 18px;
+}
+
+.surface-side-sheet__content-grid p {
+    margin: 6px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__docked-host {
+    flex: 0 0 auto;
+    min-width: 0;
+    overflow: hidden;
+    border-left: 1px solid var(--surface-border);
+    transition: width var(--surface-panel-transition-ms) var(--surface-panel-transition-easing);
+}
+
+:global(.surface-side-sheet__sheet h3) {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet) {
+    padding: 20px;
+}
+
+:global(.surface-side-sheet__sheet_modal) {
+    padding: 24px;
+}
+
+:global(.surface-side-sheet__modal-header) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+}
+
+:global(.surface-side-sheet__modal-close) {
+    flex: 0 0 auto;
+}
+
+:global(.surface-side-sheet__sheet p) {
+    margin: 0 0 8px;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet .surface-side-sheet__meta) {
+    margin-top: 14px;
+    font: 600 11px/1.2 'Trebuchet MS', 'Segoe UI', sans-serif;
+    letter-spacing: 0.04em;
+    opacity: 0.76;
+    text-transform: uppercase;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
new file mode 100644
index 0000000..ccf6649
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
@@ -0,0 +1,751 @@
+<template>
+    <div
+        class="surface-side-sheet-window"
+        :data-panel-mode="panelAsWindow ? 'window' : 'sheet'"
+        :data-panel-mounted="modalMounted ? 'true' : 'false'"
+        data-testid="surface-window-root"
+    >
+        <M3Surface
+            class="surface-side-sheet-window__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-side-sheet-window__topbar-content">
+                <div>
+                    <strong>Surface orchestration: modal side sheet to window</strong>
+                    <p>Use the action inside the panel to morph a modal side sheet into a modal window.</p>
+                </div>
+
+                <M3Button
+                    appearance="tonal"
+                    :disabled="transitioning || modalMounted"
+                    data-testid="surface-window-open"
+                    @click="openModal"
+                >
+                    {{ modalMounted ? 'Modal panel is open' : 'Show modal side sheet' }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            v-model:expanded="navExpanded"
+            class="surface-side-sheet-window__nav"
+            appearance="auto"
+            alignment="top"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Open navigation"
+                    @click="navExpanded = true"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <M3NavigationTab
+                label="Inbox"
+                :active="activeNavTab === 'inbox'"
+                @navigate="activeNavTab = 'inbox'; navExpanded = false"
+            >
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Boards"
+                :active="activeNavTab === 'boards'"
+                @navigate="activeNavTab = 'boards'; navExpanded = false"
+            >
+                <M3Icon name="dashboard" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Archive"
+                :active="activeNavTab === 'archive'"
+                @navigate="activeNavTab = 'archive'; navExpanded = false"
+            >
+                <M3Icon name="archive" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Lab"
+                :active="activeNavTab === 'lab'"
+                @navigate="activeNavTab = 'lab'; navExpanded = false"
+            >
+                <M3Icon name="science" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-side-sheet-window__body">
+            <div class="surface-side-sheet-window__workspace">
+                <M3Surface
+                    class="surface-side-sheet-window__header-card"
+                    :fill-height="false"
+                    :height="120"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Workspace surfaces</h3>
+                    <p>Background layout stays in flow while the modal panel morphs between side-sheet and window geometries.</p>
+                </M3Surface>
+
+                <div
+                    ref="layoutRoot"
+                    class="surface-side-sheet-window__layout"
+                    data-testid="surface-window-layout"
+                >
+                    <main
+                        class="surface-side-sheet-window__content-grid"
+                        data-testid="surface-window-content-grid"
+                    >
+                        <M3Surface
+                            class="surface-side-sheet-window__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-lowest"
+                            :elevation="0"
+                        >
+                            <strong>surface-container-lowest</strong>
+                            <p>Read-heavy content block in the page flow.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet-window__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-low"
+                            :elevation="1"
+                        >
+                            <strong>surface-container-low</strong>
+                            <p>Secondary block with mild emphasis.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet-window__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-high"
+                            :elevation="3"
+                        >
+                            <strong>surface-container-high</strong>
+                            <p>Contextual utility content.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet-window__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-dim"
+                            :elevation="0"
+                        >
+                            <strong>surface-dim</strong>
+                            <p>Low-brightness complementary content.</p>
+                        </M3Surface>
+                    </main>
+
+                    <M3Surface
+                        v-if="modalMounted"
+                        :class="[
+                            'surface-side-sheet-window__sheet',
+                            panelAsWindow ? 'surface-side-sheet-window__sheet_window' : 'surface-side-sheet-window__sheet_sheet',
+                        ]"
+                        mode="modal"
+                        :shown="modalVisible"
+                        :anchor="panelAnchor"
+                        :fill-width="false"
+                        :fill-height="false"
+                        :width="panelWidth"
+                        :inset-top="MODAL_INSET_TOP"
+                        :inset-right="panelInsetRight"
+                        :inset-bottom="MODAL_INSET_BOTTOM"
+                        :rounding-top-left="panelRoundingTopLeft"
+                        :rounding-bottom-left="panelRoundingBottomLeft"
+                        :rounding-top-right="panelRoundingTopRight"
+                        :rounding-bottom-right="panelRoundingBottomRight"
+                        :transition-ms="panelTransitionMs"
+                        :transition-timing="panelTransitionTiming"
+                        :z-index="520"
+                        :surface-role="panelSurfaceRole"
+                        :elevation="panelElevation"
+                        :style="panelInlineStyle"
+                        overflow="auto"
+                        :data-panel-mode="panelAsWindow ? 'window' : 'sheet'"
+                        :data-window-closing="windowClosing ? 'true' : 'false'"
+                        data-testid="surface-window-panel"
+                        @dismiss="closeModal"
+                    >
+                        <div
+                            class="surface-side-sheet-window__panel-content"
+                            data-testid="surface-window-panel-content"
+                        >
+                            <div class="surface-side-sheet-window__modal-header">
+                                <h3>{{ panelAsWindow ? 'Window mode' : 'Modal side sheet' }}</h3>
+
+                                <div class="surface-side-sheet-window__modal-actions">
+                                    <M3IconButton
+                                        class="surface-side-sheet-window__modal-action"
+                                        appearance="standard"
+                                        :aria-label="panelAsWindow ? 'Dock panel to side sheet mode' : 'Open panel in window mode'"
+                                        :disabled="transitioning"
+                                        data-testid="surface-window-toggle-mode"
+                                        @click="toggleWindowMode"
+                                    >
+                                        <M3Icon :name="panelAsWindow ? 'close_fullscreen' : 'open_in_new'" />
+                                    </M3IconButton>
+
+                                    <M3IconButton
+                                        class="surface-side-sheet-window__modal-action"
+                                        appearance="standard"
+                                        aria-label="Close modal panel"
+                                        :disabled="transitioning"
+                                        data-testid="surface-window-close"
+                                        @click="closeModal"
+                                    >
+                                        <M3Icon name="close" />
+                                    </M3IconButton>
+                                </div>
+                            </div>
+
+                            <p>Form layout adapts when switching from side-sheet to window mode.</p>
+
+                            <form
+                                class="surface-side-sheet-window__form"
+                                :class="{ 'surface-side-sheet-window__form_window': panelAsWindow }"
+                                @submit.prevent
+                            >
+                                <div class="surface-side-sheet-window__field">
+                                    <M3TextField
+                                        v-model:value="form.project"
+                                        label="Project name"
+                                        placeholder="Q3 Design Refresh"
+                                        outlined
+                                    />
+                                </div>
+
+                                <div class="surface-side-sheet-window__field">
+                                    <M3TextField
+                                        v-model:value="form.ownerEmail"
+                                        type="email"
+                                        label="Owner email"
+                                        placeholder="owner@example.com"
+                                        outlined
+                                    />
+                                </div>
+
+                                <div class="surface-side-sheet-window__field">
+                                    <M3TextField
+                                        v-model:value="form.startDate"
+                                        label="Start date"
+                                        placeholder="YYYY-MM-DD"
+                                        outlined
+                                    />
+                                </div>
+
+                                <div class="surface-side-sheet-window__field">
+                                    <M3Select
+                                        v-model:value="form.priority"
+                                        :options="priorityOptions"
+                                        label="Priority"
+                                        outlined
+                                    />
+                                </div>
+
+                                <div
+                                    class="surface-side-sheet-window__field"
+                                    :class="{ 'surface-side-sheet-window__field_wide': panelAsWindow }"
+                                >
+                                    <M3TextField
+                                        v-model:value="form.notes"
+                                        multiline
+                                        label="Notes"
+                                        placeholder="Describe constraints, risks, and acceptance criteria."
+                                        outlined
+                                    />
+                                </div>
+
+                                <div
+                                    class="surface-side-sheet-window__form-actions"
+                                    :class="{ 'surface-side-sheet-window__form-actions_window': panelAsWindow }"
+                                >
+                                    <M3Button
+                                        appearance="text"
+                                        type="button"
+                                        @click="resetForm"
+                                    >
+                                        Reset
+                                    </M3Button>
+                                    <M3Button appearance="filled" type="button">
+                                        Save
+                                    </M3Button>
+                                </div>
+                            </form>
+                        </div>
+                    </M3Surface>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Select } from '@/components/select'
+import { M3TextField } from '@/components/text-field'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  reactive,
+  ref,
+} from 'vue'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const WINDOW_WIDTH_MIN = 440
+const WINDOW_WIDTH_MAX = 920
+const WINDOW_WIDTH_RATIO = 0.72
+const WINDOW_WIDTH_STEP = 8
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = 300
+const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const SCRIM_FADE_MS = 500
+const DIALOG_HIDE_MS = 500
+
+const navExpanded = ref(false)
+const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
+const sideSheetWidth = ref(320)
+const windowWidth = ref(720)
+
+const modalInsetRight = ref(-(sideSheetWidth.value + 12))
+const modalRadiusLeft = ref(0)
+const modalElevationBase = ref(0)
+
+const modalMounted = ref(false)
+const modalVisible = ref(false)
+const panelAsWindow = ref(false)
+const windowClosing = ref(false)
+const transitioning = ref(false)
+const layoutRoot = ref<HTMLElement | null>(null)
+
+type Priority = 'low' | 'normal' | 'high'
+
+type FormState = {
+  project: string,
+  ownerEmail: string,
+  startDate: string,
+  priority: Priority,
+  notes: string,
+}
+
+const DEFAULT_FORM: FormState = {
+  project: 'Q3 Design Refresh',
+  ownerEmail: 'owner@example.com',
+  startDate: '2026-03-01',
+  priority: 'normal',
+  notes: 'Move supplemental workflows into a reusable surface with predictable transitions.',
+}
+
+const form = reactive<FormState>({ ...DEFAULT_FORM })
+
+const priorityOptions = [{
+  label: 'Low',
+  value: 'low',
+}, {
+  label: 'Normal',
+  value: 'normal',
+}, {
+  label: 'High',
+  value: 'high',
+}]
+
+const panelAnchor = computed(() => panelAsWindow.value ? 'center' : 'end')
+const panelWidth = computed(() => panelAsWindow.value ? windowWidth.value : sideSheetWidth.value)
+const panelInsetRight = computed(() => panelAsWindow.value ? 0 : modalInsetRight.value)
+const panelRoundingTopLeft = computed(() => panelAsWindow.value ? 28 : modalRadiusLeft.value)
+const panelRoundingBottomLeft = computed(() => panelAsWindow.value ? 28 : modalRadiusLeft.value)
+const panelRoundingTopRight = computed(() => panelAsWindow.value ? 28 : 0)
+const panelRoundingBottomRight = computed(() => panelAsWindow.value ? 28 : 0)
+const panelSurfaceRole = computed(() => panelAsWindow.value ? 'surface-container-highest' : 'surface-container-high')
+const panelElevation = computed(() => panelAsWindow.value ? Math.max(2, modalElevationBase.value) : modalElevationBase.value)
+const panelTransitionMs = computed(() => {
+  if (panelAsWindow.value && windowClosing.value) {
+    return DIALOG_HIDE_MS
+  }
+
+  return PANEL_TRANSITION_MS
+})
+const panelTransitionTiming = computed(() => PANEL_TRANSITION_EASING)
+const panelInlineStyle = computed(() => {
+  if (!(panelAsWindow.value && windowClosing.value)) {
+    return {}
+  }
+
+  return {
+    opacity: 0,
+    transform: 'translate(-50%, calc(-50% - 24px))',
+  }
+})
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function hiddenInsetRight() {
+  return -(sideSheetWidth.value + 12)
+}
+
+function resolveSheetWidthFromLayout() {
+  const layoutWidth = Math.round(layoutRoot.value?.getBoundingClientRect().width ?? window.innerWidth)
+  const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+  return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+}
+
+function resolveWindowWidth() {
+  const estimated = Math.round((window.innerWidth * WINDOW_WIDTH_RATIO) / WINDOW_WIDTH_STEP) * WINDOW_WIDTH_STEP
+
+  return clamp(estimated, WINDOW_WIDTH_MIN, WINDOW_WIDTH_MAX)
+}
+
+function syncDimensions() {
+  sideSheetWidth.value = resolveSheetWidthFromLayout()
+  windowWidth.value = resolveWindowWidth()
+
+  if (!modalMounted.value) {
+    modalInsetRight.value = hiddenInsetRight()
+  }
+}
+
+async function openModal() {
+  if (transitioning.value || modalMounted.value) {
+    return
+  }
+
+  transitioning.value = true
+  panelAsWindow.value = false
+  windowClosing.value = false
+  syncDimensions()
+
+  modalRadiusLeft.value = 0
+  modalElevationBase.value = 0
+  modalInsetRight.value = hiddenInsetRight()
+  modalMounted.value = true
+
+  // Let modal layer mount before showing scrim and panel enter animation.
+  await nextTick()
+  await raf()
+
+  modalVisible.value = true
+  await nextTick()
+  await raf()
+
+  modalInsetRight.value = MODAL_INSET_END
+  modalRadiusLeft.value = 28
+  modalElevationBase.value = 1
+  await wait(PANEL_TRANSITION_MS)
+  transitioning.value = false
+}
+
+async function toggleWindowMode() {
+  if (transitioning.value || !modalMounted.value) {
+    return
+  }
+
+  transitioning.value = true
+
+  if (!panelAsWindow.value) {
+    panelAsWindow.value = true
+    await wait(PANEL_TRANSITION_MS)
+    transitioning.value = false
+    return
+  }
+
+  panelAsWindow.value = false
+  await wait(PANEL_TRANSITION_MS)
+  transitioning.value = false
+}
+
+async function closeModal() {
+  if (transitioning.value || !modalMounted.value) {
+    return
+  }
+
+  transitioning.value = true
+
+  if (panelAsWindow.value) {
+    await closeWindowModal()
+    transitioning.value = false
+    return
+  }
+
+  await closeSideSheetModal()
+  transitioning.value = false
+}
+
+function resetForm() {
+  Object.assign(form, DEFAULT_FORM)
+}
+
+async function closeWindowModal() {
+  windowClosing.value = true
+  await wait(DIALOG_HIDE_MS)
+
+  modalVisible.value = false
+  await wait(SCRIM_FADE_MS)
+  modalMounted.value = false
+
+  modalInsetRight.value = hiddenInsetRight()
+  modalRadiusLeft.value = 0
+  modalElevationBase.value = 0
+  windowClosing.value = false
+  panelAsWindow.value = false
+}
+
+async function closeSideSheetModal() {
+  modalInsetRight.value = hiddenInsetRight()
+  modalRadiusLeft.value = 0
+  modalElevationBase.value = 0
+  await wait(PANEL_TRANSITION_MS)
+
+  modalVisible.value = false
+  await wait(SCRIM_FADE_MS)
+  modalMounted.value = false
+}
+
+function onResize() {
+  syncDimensions()
+}
+
+onMounted(() => {
+  syncDimensions()
+  window.addEventListener('resize', onResize, { passive: true })
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', onResize)
+})
+</script>
+
+<style lang="scss" scoped>
+.surface-side-sheet-window {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+    --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+    --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+    --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+    --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+        radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet-window__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-side-sheet-window__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.82;
+}
+
+.surface-side-sheet-window__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+    .surface-side-sheet-window__body {
+        padding-left: var(--m3-navigation-drawer-width, 360px);
+    }
+}
+
+:global(.surface-side-sheet-window__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-side-sheet-window__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-side-sheet-window__topbar {
+    padding: 16px;
+}
+
+.surface-side-sheet-window__header-card {
+    padding: 18px;
+}
+
+.surface-side-sheet-window__header-card h3 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__header-card p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__layout {
+    min-height: 440px;
+    display: flex;
+    overflow: hidden;
+    border-radius: 20px;
+    background: var(--surface-layout-bg);
+    box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet-window__content-grid {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    grid-auto-rows: min-content;
+    gap: 12px;
+    padding: 14px;
+    align-content: flex-start;
+    align-items: start;
+    background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet-window__content-grid > .surface-side-sheet-window__grid-surface {
+    padding: 18px;
+}
+
+.surface-side-sheet-window__content-grid p {
+    margin: 6px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet-window__modal-header) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+}
+
+:global(.surface-side-sheet-window__sheet_sheet) {
+    padding: 24px;
+}
+
+:global(.surface-side-sheet-window__sheet_window) {
+    padding: 20px;
+}
+
+:global(.surface-side-sheet-window__modal-header h3) {
+    margin: 0;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet-window__modal-actions) {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+}
+
+:global(.surface-side-sheet-window__modal-action) {
+    flex: 0 0 auto;
+}
+
+:global(.surface-side-sheet-window__sheet p) {
+    margin: 8px 0 0;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet-window__panel-content) {
+    min-height: 0;
+}
+
+.surface-side-sheet-window__form {
+    margin-top: 14px;
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 12px;
+}
+
+.surface-side-sheet-window__form_window {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 14px;
+}
+
+.surface-side-sheet-window__field {
+    display: grid;
+    gap: 6px;
+}
+
+.surface-side-sheet-window__field_wide {
+    grid-column: 1 / -1;
+}
+
+.surface-side-sheet-window__field :deep(.m3-text-field),
+.surface-side-sheet-window__field :deep(.m3-select) {
+    width: 100%;
+}
+
+.surface-side-sheet-window__field_wide :deep(.m3-text-field textarea) {
+    min-height: 120px;
+}
+
+.surface-side-sheet-window__form-actions {
+    display: flex;
+    gap: 10px;
+    justify-content: flex-start;
+}
+
+.surface-side-sheet-window__form-actions_window {
+    grid-column: 1 / -1;
+    justify-content: flex-end;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
new file mode 100644
index 0000000..72e3f59
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
@@ -0,0 +1,592 @@
+<template>
+    <div
+        class="surface-side-sheet"
+        :data-sheet-modal="sideSheetModal ? 'true' : 'false'"
+        data-testid="surface-morph-root"
+    >
+        <M3Surface
+            class="surface-side-sheet__topbar"
+            :fill-height="false"
+            :height="72"
+            surface-role="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-side-sheet__topbar-content">
+                <div>
+                    <strong>Surface orchestration: side sheet morph</strong>
+                    <p>Docked sheet transitions into modal sheet with fixed width, right-edge anchoring, and full-height modal target.</p>
+                </div>
+
+                <M3Button
+                    appearance="tonal"
+                    :disabled="transitioning"
+                    data-testid="surface-morph-toggle"
+                    @click="toggleSideSheetMode"
+                >
+                    {{ sideSheetModal ? 'Switch to docked sheet' : 'Switch to modal sheet' }}
+                </M3Button>
+            </div>
+        </M3Surface>
+
+        <M3Navigation
+            v-model:expanded="navExpanded"
+            class="surface-side-sheet__nav"
+            appearance="auto"
+            alignment="top"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Open navigation"
+                    @click="navExpanded = true"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <M3NavigationTab
+                label="Inbox"
+                :active="activeNavTab === 'inbox'"
+                @navigate="activeNavTab = 'inbox'; navExpanded = false"
+            >
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Boards"
+                :active="activeNavTab === 'boards'"
+                @navigate="activeNavTab = 'boards'; navExpanded = false"
+            >
+                <M3Icon name="dashboard" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Archive"
+                :active="activeNavTab === 'archive'"
+                @navigate="activeNavTab = 'archive'; navExpanded = false"
+            >
+                <M3Icon name="archive" />
+            </M3NavigationTab>
+
+            <M3NavigationTab
+                label="Lab"
+                :active="activeNavTab === 'lab'"
+                @navigate="activeNavTab = 'lab'; navExpanded = false"
+            >
+                <M3Icon name="science" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="surface-side-sheet__body">
+            <div class="surface-side-sheet__workspace">
+                <M3Surface
+                    class="surface-side-sheet__header-card"
+                    :fill-height="false"
+                    :height="120"
+                    :rounding="20"
+                    surface-role="surface-container-lowest"
+                    :elevation="0"
+                >
+                    <h3>Workspace surfaces</h3>
+                    <p>Static blocks keep flow while side-sheet changes modality.</p>
+                </M3Surface>
+
+                <div
+                    ref="layoutRoot"
+                    class="surface-side-sheet__layout"
+                    data-testid="surface-morph-layout"
+                >
+                    <main
+                        class="surface-side-sheet__content-grid"
+                        data-testid="surface-morph-content-grid"
+                    >
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-lowest"
+                            :elevation="0"
+                        >
+                            <strong>surface-container-lowest</strong>
+                            <p>Read-heavy content block in the page flow.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-low"
+                            :elevation="1"
+                        >
+                            <strong>surface-container-low</strong>
+                            <p>Secondary block with mild emphasis.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-container-high"
+                            :elevation="3"
+                        >
+                            <strong>surface-container-high</strong>
+                            <p>Contextual utility content.</p>
+                        </M3Surface>
+
+                        <M3Surface
+                            class="surface-side-sheet__grid-surface"
+                            :fill-height="false"
+                            :height="136"
+                            :rounding="18"
+                            surface-role="surface-dim"
+                            :elevation="0"
+                        >
+                            <strong>surface-dim</strong>
+                            <p>Low-brightness complementary content.</p>
+                        </M3Surface>
+                    </main>
+
+                    <div
+                        ref="dockedHost"
+                        class="surface-side-sheet__docked-host"
+                        :style="{ width: `${sideSheetDockedWidth}px` }"
+                        data-testid="surface-morph-docked-host"
+                    >
+                        <M3Surface
+                            v-if="!sideSheetModal"
+                            class="surface-side-sheet__sheet"
+                            :fill-width="true"
+                            :fill-height="true"
+                            :rounding="0"
+                            surface-role="surface-container-low"
+                            :elevation="0"
+                            overflow="auto"
+                            data-testid="surface-morph-docked-sheet"
+                        >
+                            <h3>Docked side sheet</h3>
+                            <p>Coplanar layout participant with fixed width per layout region.</p>
+                            <p>Main content remains interactive.</p>
+                            <p class="surface-side-sheet__meta">
+                                Fixed width: {{ sideSheetWidth }}px
+                            </p>
+                        </M3Surface>
+                    </div>
+
+                    <M3Surface
+                        v-if="modalShown"
+                        class="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                        mode="modal"
+                        :shown="modalVisible"
+                        anchor="end"
+                        :fill-width="false"
+                        :fill-height="false"
+                        :width="modalWidth"
+                        :inset-top="modalInsetTop"
+                        :inset-right="modalInsetRight"
+                        :inset-bottom="modalInsetBottom"
+                        :rounding-top-left="modalRadiusLeft"
+                        :rounding-bottom-left="modalRadiusLeft"
+                        :rounding-top-right="0"
+                        :rounding-bottom-right="0"
+                        :transition-ms="PANEL_TRANSITION_MS"
+                        :transition-timing="PANEL_TRANSITION_EASING"
+                        :z-index="520"
+                        :surface-role="modalRole"
+                        :elevation="modalElevation"
+                        overflow="auto"
+                        data-testid="surface-morph-modal-sheet"
+                        @dismiss="closeModalFromPanel"
+                    >
+                        <div class="surface-side-sheet__modal-header">
+                            <h3>Modal side sheet</h3>
+
+                            <M3IconButton
+                                v-if="sideSheetModal"
+                                class="surface-side-sheet__modal-close"
+                                appearance="standard"
+                                aria-label="Close modal side sheet"
+                                :disabled="transitioning"
+                                data-testid="surface-morph-close"
+                                @click="closeModalFromPanel"
+                            >
+                                <M3Icon name="close" />
+                            </M3IconButton>
+                        </div>
+
+                        <p>Layer rebind: docked layer to modal layer.</p>
+                        <p>Anchored to end/right edge with full-height modal surface.</p>
+                        <p class="surface-side-sheet__meta">
+                            Fixed width: {{ modalWidth }}px
+                        </p>
+                    </M3Surface>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import M3Surface from '@/experimental/M3Surface.vue'
+
+import {
+  onBeforeUnmount,
+  onMounted,
+  nextTick,
+  ref,
+} from 'vue'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = 300
+const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const SCRIM_FADE_MS = 500
+
+const navExpanded = ref(false)
+const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
+const sideSheetModal = ref(false)
+const sideSheetWidth = ref(320)
+const sideSheetDockedWidth = ref(sideSheetWidth.value)
+const modalShown = ref(false)
+const modalVisible = ref(false)
+const modalWidth = ref(sideSheetWidth.value)
+const modalInsetTop = ref(MODAL_INSET_TOP)
+const modalInsetRight = ref(-(sideSheetWidth.value + 12))
+const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
+const modalRadiusLeft = ref(0)
+const modalElevation = ref(0)
+const modalRole = ref<'surface-container-low' | 'surface-container-high'>('surface-container-low')
+const transitioning = ref(false)
+const dockedHost = ref<HTMLElement | null>(null)
+const layoutRoot = ref<HTMLElement | null>(null)
+
+function wait(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value))
+}
+
+function hiddenInsetRight() {
+  return -(modalWidth.value + 12)
+}
+
+function resolveSheetWidthFromLayout() {
+  const layoutWidth = Math.round(layoutRoot.value?.getBoundingClientRect().width ?? window.innerWidth)
+  const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+  return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+}
+
+function syncFixedWidth() {
+  const nextWidth = resolveSheetWidthFromLayout()
+
+  sideSheetWidth.value = nextWidth
+  modalWidth.value = nextWidth
+
+  if (!sideSheetModal.value) {
+    sideSheetDockedWidth.value = nextWidth
+    modalInsetRight.value = hiddenInsetRight()
+  }
+}
+
+function measureDockedGeometry() {
+  const host = dockedHost.value
+  if (!host) {
+    return null
+  }
+
+  const rect = host.getBoundingClientRect()
+
+  return {
+    width: Math.round(rect.width),
+    insetTop: Math.round(rect.top),
+    insetRight: Math.round(window.innerWidth - rect.right),
+    insetBottom: Math.round(window.innerHeight - rect.bottom),
+  }
+}
+
+function setModalGeometryFromDocked() {
+  const docked = measureDockedGeometry()
+
+  modalWidth.value = docked?.width ?? sideSheetWidth.value
+  modalInsetTop.value = docked?.insetTop ?? MODAL_INSET_TOP
+  modalInsetRight.value = docked?.insetRight ?? MODAL_INSET_END
+  modalInsetBottom.value = docked?.insetBottom ?? MODAL_INSET_BOTTOM
+}
+
+function setModalGeometryTarget() {
+  modalWidth.value = sideSheetWidth.value
+  modalInsetTop.value = MODAL_INSET_TOP
+  modalInsetRight.value = MODAL_INSET_END
+  modalInsetBottom.value = MODAL_INSET_BOTTOM
+}
+
+async function switchDockedToModal() {
+  syncFixedWidth()
+  setModalGeometryFromDocked()
+
+  modalRadiusLeft.value = 0
+  modalElevation.value = 0
+  modalRole.value = 'surface-container-low'
+  modalVisible.value = false
+  modalShown.value = true
+
+  await nextTick()
+  await raf()
+
+  modalVisible.value = true
+  await nextTick()
+  await raf()
+
+  sideSheetModal.value = true
+  sideSheetDockedWidth.value = 0
+  setModalGeometryTarget()
+  modalRadiusLeft.value = 28
+  modalElevation.value = 1
+  modalRole.value = 'surface-container-high'
+  await wait(PANEL_TRANSITION_MS)
+}
+
+async function switchModalToDocked() {
+  syncFixedWidth()
+
+  modalElevation.value = 0
+  modalRole.value = 'surface-container-low'
+  modalRadiusLeft.value = 0
+  modalInsetTop.value = MODAL_INSET_TOP
+  modalInsetBottom.value = MODAL_INSET_BOTTOM
+  modalInsetRight.value = hiddenInsetRight()
+  await wait(PANEL_TRANSITION_MS)
+  modalVisible.value = false
+  await wait(SCRIM_FADE_MS)
+  modalShown.value = false
+  sideSheetModal.value = false
+  await nextTick()
+  await raf()
+  sideSheetDockedWidth.value = sideSheetWidth.value
+  await wait(PANEL_TRANSITION_MS)
+}
+
+async function toggleSideSheetMode() {
+  if (transitioning.value) {
+    return
+  }
+
+  transitioning.value = true
+
+  if (!sideSheetModal.value) {
+    await switchDockedToModal()
+    transitioning.value = false
+    return
+  }
+
+  await switchModalToDocked()
+  transitioning.value = false
+}
+
+async function closeModalFromPanel() {
+  if (!sideSheetModal.value || transitioning.value) {
+    return
+  }
+
+  transitioning.value = true
+  await switchModalToDocked()
+  transitioning.value = false
+}
+
+function onResize() {
+  syncFixedWidth()
+}
+
+onMounted(() => {
+  syncFixedWidth()
+  window.addEventListener('resize', onResize, { passive: true })
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', onResize)
+})
+</script>
+
+<style scoped>
+.surface-side-sheet {
+    --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+    --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+    --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+    --surface-border: var(--m3-sys-outline-variant, var(--md-sys-color-outline-variant, rgba(73, 69, 79, 0.2)));
+    --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+    --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+    --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+    --surface-panel-transition-ms: 300ms;
+    --surface-panel-transition-easing: cubic-bezier(0.2, 0, 0, 1);
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+        radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+        linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+    color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-side-sheet__topbar-content strong {
+    display: block;
+    font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__topbar-content p {
+    margin: 4px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+    opacity: 0.82;
+}
+
+.surface-side-sheet__body {
+    display: flex;
+    height: calc(100vh - 72px);
+    padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+    .surface-side-sheet__body {
+        padding-left: var(--m3-navigation-drawer-width, 360px);
+    }
+}
+
+:global(.surface-side-sheet__nav.m3-navigation) {
+    top: 72px;
+    height: calc(100vh - 72px);
+}
+
+.surface-side-sheet__workspace {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.surface-side-sheet__topbar {
+    padding: 16px;
+}
+
+.surface-side-sheet__header-card {
+    padding: 18px;
+}
+
+.surface-side-sheet__header-card h3 {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__header-card p {
+    margin: 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__layout {
+    min-height: 440px;
+    display: flex;
+    overflow: hidden;
+    border-radius: 20px;
+    background: var(--surface-layout-bg);
+    box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet__content-grid {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    grid-auto-rows: min-content;
+    gap: 12px;
+    padding: 14px;
+    align-content: flex-start;
+    align-items: start;
+    background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet__content-grid > .surface-side-sheet__grid-surface {
+    padding: 18px;
+}
+
+.surface-side-sheet__content-grid p {
+    margin: 6px 0 0;
+    font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__docked-host {
+    flex: 0 0 auto;
+    min-width: 0;
+    overflow: hidden;
+    border-left: 1px solid var(--surface-border);
+    transition: width var(--surface-panel-transition-ms) var(--surface-panel-transition-easing);
+}
+
+:global(.surface-side-sheet__sheet h3) {
+    margin: 0 0 8px;
+    font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet) {
+    padding: 20px;
+}
+
+:global(.surface-side-sheet__sheet_modal) {
+    padding: 24px;
+}
+
+:global(.surface-side-sheet__modal-header) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+}
+
+:global(.surface-side-sheet__modal-close) {
+    flex: 0 0 auto;
+}
+
+:global(.surface-side-sheet__sheet p) {
+    margin: 0 0 8px;
+    font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+:global(.surface-side-sheet__sheet .surface-side-sheet__meta) {
+    margin-top: 14px;
+    font: 600 11px/1.2 'Trebuchet MS', 'Segoe UI', sans-serif;
+    letter-spacing: 0.04em;
+    opacity: 0.76;
+    text-transform: uppercase;
+}
+</style>
diff --git a/m3-vue/tests/M3Surface.e2e.ts b/m3-vue/tests/M3Surface.e2e.ts
new file mode 100644
index 0000000..3745a74
--- /dev/null
+++ b/m3-vue/tests/M3Surface.e2e.ts
@@ -0,0 +1,200 @@
+import type { App } from 'vue'
+
+import {
+  createApp,
+  nextTick,
+} from 'vue'
+
+import { page } from 'vitest/browser'
+
+import SurfaceExperimentHarness from './fixtures/SurfaceExperimentHarness.vue'
+
+const RUN_ID = 'EXP-2026-02-23-surface-e2e-002h-001'
+const SCREENSHOT_DIR = `../../drafts/experiment/runs/${RUN_ID}/screenshots/e2e`
+
+type HarnessMount = {
+  app: App;
+  mountPoint: HTMLDivElement;
+}
+
+const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+const waitFor = async (assertion: () => void, timeoutMs = 1600) => {
+  const startedAt = Date.now()
+  let lastError: unknown
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      assertion()
+      return
+    } catch (error) {
+      lastError = error
+      await delay(12)
+    }
+  }
+
+  throw lastError ?? new Error('waitFor timeout')
+}
+
+const mountHarness = (): HarnessMount => {
+  const mountPoint = document.createElement('div')
+  mountPoint.setAttribute('data-testid', 'surface-harness-mount')
+  document.body.append(mountPoint)
+
+  const app = createApp(SurfaceExperimentHarness)
+  app.mount(mountPoint)
+
+  return {
+    app,
+    mountPoint,
+  }
+}
+
+const collectRectSeries = async (element: HTMLElement, durationMs = 380, stepMs = 32) => {
+  const points: Array<{ width: number, height: number }> = []
+  const startedAt = performance.now()
+
+  while (performance.now() - startedAt < durationMs) {
+    const rect = element.getBoundingClientRect()
+    points.push({
+      width: rect.width,
+      height: rect.height,
+    })
+    await delay(stepMs)
+  }
+
+  return points
+}
+
+const deltas = (values: number[]) => values.slice(1).map((value, index) => value - values[index])
+
+const click = (selector: string) => {
+  const element = document.querySelector(selector) as HTMLButtonElement | null
+  if (!element) {
+    throw new Error(`Element not found: ${selector}`)
+  }
+
+  element.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+}
+
+const capture = async (name: string) => {
+  await page.screenshot({
+    path: `${SCREENSHOT_DIR}/${name}.png`,
+  })
+}
+
+describe('m3-vue/surface e2e', () => {
+  let mounted: HarnessMount | null = null
+
+  beforeEach(async () => {
+    await page.viewport(1440, 1024)
+    mounted = mountHarness()
+  })
+
+  afterEach(() => {
+    mounted?.app.unmount()
+    mounted?.mountPoint.remove()
+    mounted = null
+    document.body.innerHTML = ''
+  })
+
+  test('orchestrates multiple roles and morphs docked side-sheet to modal without layout jerk', async () => {
+    await waitFor(() => {
+      const root = document.querySelector('[data-testid="surface-exp-root"]')
+      expect(root).not.toBeNull()
+    })
+
+    const staticRoles = [
+      'surface-container-lowest',
+      'surface-container-low',
+      'surface-container-high',
+      'surface-dim',
+    ]
+
+    staticRoles.forEach((role) => {
+      const block = document.querySelector(`[data-testid="static-role-${role}"]`) as HTMLElement | null
+      expect(block).not.toBeNull()
+      expect(block?.classList.contains(`m3-surface_role-${role}`)).toBe(true)
+    })
+
+    const content = document.querySelector('[data-testid="sheet-layout-content"]') as HTMLElement
+    const beforeRect = content.getBoundingClientRect()
+
+    await capture('scenario-a-side-sheet-before')
+
+    click('[data-testid="sheet-to-modal"]')
+    await nextTick()
+
+    const widthSeries = (await collectRectSeries(content, 560, 32)).map(point => point.width)
+    const widthDeltas = deltas(widthSeries)
+
+    await waitFor(() => {
+      const modalSheet = document.querySelector('[data-testid="orchestrated-side-sheet"][role="dialog"]')
+      const scrim = document.querySelector('.m3-surface__scrim')
+      expect(modalSheet).not.toBeNull()
+      expect(scrim).not.toBeNull()
+    })
+
+    await delay(180)
+    await capture('scenario-a-side-sheet-mid')
+
+    expect(widthDeltas.some(delta => delta > 0)).toBe(true)
+    expect(Math.min(...widthDeltas)).toBeGreaterThan(-6)
+    expect(Math.max(...widthDeltas)).toBeLessThan(120)
+
+    await delay(220)
+    const afterRect = content.getBoundingClientRect()
+    expect(afterRect.width).toBeGreaterThan(beforeRect.width + 220)
+
+    await capture('scenario-a-side-sheet-after')
+  })
+
+  test('expands card-like surface into page-like container with reserved layout zones', async () => {
+    await waitFor(() => {
+      const card = document.querySelector('[data-testid="orchestrated-card-surface"]') as HTMLElement | null
+      expect(card).not.toBeNull()
+    })
+
+    const canvas = document.querySelector('[data-testid="card-canvas"]') as HTMLElement
+    const overlayWrap = document.querySelector('[data-testid="card-overlay-wrap"]') as HTMLElement
+    const beforeRect = overlayWrap.getBoundingClientRect()
+
+    expect(beforeRect.width).toBeGreaterThan(280)
+    expect(beforeRect.height).toBeGreaterThan(180)
+
+    await capture('scenario-b-card-before')
+
+    click('[data-testid="card-to-page"]')
+    await nextTick()
+
+    await delay(120)
+    await capture('scenario-b-card-mid')
+
+    const rectSeries = await collectRectSeries(overlayWrap, 380, 32)
+    const widths = rectSeries.map(point => point.width)
+    const heights = rectSeries.map(point => point.height)
+
+    const widthDeltas = deltas(widths)
+    const heightDeltas = deltas(heights)
+
+    expect(widthDeltas.some(delta => delta > 0)).toBe(true)
+    expect(heightDeltas.some(delta => delta > 0)).toBe(true)
+    expect(Math.min(...widthDeltas)).toBeGreaterThan(-6)
+    expect(Math.min(...heightDeltas)).toBeGreaterThan(-6)
+    expect(Math.max(...widthDeltas)).toBeLessThan(140)
+    expect(Math.max(...heightDeltas)).toBeLessThan(140)
+
+    await delay(240)
+    const afterRect = overlayWrap.getBoundingClientRect()
+    const canvasRect = canvas.getBoundingClientRect()
+
+    expect(afterRect.width).toBeGreaterThan(canvasRect.width - 44)
+    expect(afterRect.height).toBeGreaterThan(canvasRect.height - 44)
+
+    const morphedSurface = document.querySelector('[data-testid="orchestrated-card-surface"]') as HTMLElement
+    expect(morphedSurface.classList.contains('m3-surface_role-surface')).toBe(true)
+    expect(morphedSurface.style.borderTopLeftRadius).toBe('0px')
+
+    await capture('scenario-b-card-after')
+  })
+})
diff --git a/m3-vue/tests/M3Surface.test.ts b/m3-vue/tests/M3Surface.test.ts
new file mode 100644
index 0000000..f02992e
--- /dev/null
+++ b/m3-vue/tests/M3Surface.test.ts
@@ -0,0 +1,111 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/vue'
+
+import M3Surface from '@/experimental/M3Surface.vue'
+
+describe('m3-vue/experimental/surface', () => {
+  test('applies deterministic default contract', () => {
+    render(M3Surface, {
+      slots: {
+        default: 'Surface body',
+      },
+    })
+
+    const surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface')).toBe(true)
+    expect(surface.style.width).toBe('100%')
+    expect(surface.style.height).toBe('100%')
+    expect(surface.style.margin).toBe('')
+    expect(surface.style.padding).toBe('')
+    expect(surface.style.borderTopLeftRadius).toBe('0px')
+    expect(surface.style.borderTopRightRadius).toBe('0px')
+    expect(surface.style.borderBottomRightRadius).toBe('0px')
+    expect(surface.style.borderBottomLeftRadius).toBe('0px')
+    expect(surface.style.boxSizing).toBe('')
+  })
+
+  test('supports global and per-corner rounding overrides', () => {
+    render(M3Surface, {
+      props: {
+        rounding: 16,
+        roundingTopLeft: 4,
+        roundingBottomRight: '24px',
+      },
+    })
+
+    const surface = screen.getByRole('region')
+
+    expect(surface.style.borderTopLeftRadius).toBe('4px')
+    expect(surface.style.borderTopRightRadius).toBe('16px')
+    expect(surface.style.borderBottomRightRadius).toBe('24px')
+    expect(surface.style.borderBottomLeftRadius).toBe('16px')
+  })
+
+  test('emits close request and dismiss on scrim click in modal mode', async () => {
+    const view = render(M3Surface, {
+      props: {
+        mode: 'modal',
+        shown: true,
+      },
+      slots: {
+        default: 'Modal body',
+      },
+    })
+
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
+
+    await fireEvent.click(scrim)
+
+    expect(view.emitted()['update:shown']?.[0]).toEqual([false])
+    expect(view.emitted().dismiss?.[0]).toEqual([])
+  })
+
+  test('anchors modal surface to center with fixed positioning', () => {
+    render(M3Surface, {
+      props: {
+        mode: 'modal',
+        shown: true,
+        anchor: 'center',
+        width: 320,
+        height: 240,
+        fillWidth: false,
+        fillHeight: false,
+      },
+    })
+
+    const surface = screen.getByRole('dialog')
+
+    expect(surface.style.position).toBe('fixed')
+    expect(surface.style.top).toBe('50%')
+    expect(surface.style.left).toBe('50%')
+    expect(surface.style.transform).toContain('translate(-50%, -50%)')
+    expect(surface.style.width).toBe('320px')
+    expect(surface.style.height).toBe('240px')
+  })
+
+  test('maps auto surface role from elevation and allows explicit role override', async () => {
+    const view = render(M3Surface, {
+      props: {
+        elevation: 3,
+      },
+    })
+
+    let surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(true)
+
+    await view.rerender({
+      elevation: 3,
+      surfaceRole: 'surface-bright',
+    })
+
+    surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface_role-surface-bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(false)
+  })
+})
diff --git a/m3-vue/tests/M3SurfaceStories.e2e.ts b/m3-vue/tests/M3SurfaceStories.e2e.ts
new file mode 100644
index 0000000..c823bba
--- /dev/null
+++ b/m3-vue/tests/M3SurfaceStories.e2e.ts
@@ -0,0 +1,427 @@
+import type {
+  App,
+  Component,
+} from 'vue'
+
+import {
+  createApp,
+  h,
+  nextTick,
+} from 'vue'
+
+import { page } from 'vitest/browser'
+
+import SurfaceCardPageMorph from '../storybook/examples/surface/SurfaceCardPageMorph.vue'
+import SurfaceNestedDialogsChain from '../storybook/examples/surface/SurfaceNestedDialogsChain.vue'
+import SurfaceSideSheetAlwaysModal from '../storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue'
+import SurfaceSideSheetModalToWindow from '../storybook/examples/surface/SurfaceSideSheetModalToWindow.vue'
+import SurfaceSideSheetMorph from '../storybook/examples/surface/SurfaceSideSheetMorph.vue'
+
+type MountedStory = {
+  app: App;
+  mountPoint: HTMLDivElement;
+}
+
+const delay = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms))
+
+const waitFor = async (assertion: () => void, timeoutMs = 1800) => {
+  const startedAt = Date.now()
+  let lastError: unknown
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      assertion()
+      return
+    } catch (error) {
+      lastError = error
+      await delay(14)
+    }
+  }
+
+  throw lastError ?? new Error('waitFor timeout')
+}
+
+const mountStory = (component: Component): MountedStory => {
+  const mountPoint = document.createElement('div')
+  mountPoint.setAttribute('data-testid', 'surface-story-mount')
+  document.body.append(mountPoint)
+
+  const app = createApp({
+    render: () => h(component),
+  })
+
+  app.mount(mountPoint)
+
+  return {
+    app,
+    mountPoint,
+  }
+}
+
+const query = <T extends Element>(selector: string) => {
+  const element = document.querySelector(selector) as T | null
+  if (!element) {
+    throw new Error(`Element not found: ${selector}`)
+  }
+
+  return element
+}
+
+const click = (selector: string) => {
+  query<HTMLElement>(selector).dispatchEvent(new MouseEvent('click', {
+    bubbles: true,
+    cancelable: true,
+  }))
+}
+
+const collectSeries = async (reader: () => number, durationMs = 360, stepMs = 24) => {
+  const values: number[] = []
+  const startedAt = performance.now()
+
+  while (performance.now() - startedAt < durationMs) {
+    values.push(reader())
+    await delay(stepMs)
+  }
+
+  return values
+}
+
+const deltas = (values: number[]) => values.slice(1).map((value, index) => value - values[index])
+
+const toNumber = (raw: string) => {
+  const value = Number.parseFloat(raw)
+
+  if (Number.isNaN(value)) {
+    throw new Error(`Expected numeric CSS value, got "${raw}"`)
+  }
+
+  return value
+}
+
+const matrixTranslateY = (element: HTMLElement) => {
+  const transform = getComputedStyle(element).transform
+
+  if (!transform || transform === 'none') {
+    return 0
+  }
+
+  const matrix3d = transform.match(/^matrix3d\((.+)\)$/)
+  if (matrix3d) {
+    const values = matrix3d[1].split(',').map(part => Number.parseFloat(part.trim()))
+
+    return values[13] ?? 0
+  }
+
+  const matrix2d = transform.match(/^matrix\((.+)\)$/)
+  if (matrix2d) {
+    const values = matrix2d[1].split(',').map(part => Number.parseFloat(part.trim()))
+
+    return values[5] ?? 0
+  }
+
+  return 0
+}
+
+const expectCentered = (element: HTMLElement, tolerancePx = 8) => {
+  const rect = element.getBoundingClientRect()
+  const centerX = rect.left + (rect.width / 2)
+  const centerY = rect.top + (rect.height / 2)
+
+  expect(Math.abs(centerX - (window.innerWidth / 2))).toBeLessThanOrEqual(tolerancePx)
+  expect(Math.abs(centerY - (window.innerHeight / 2))).toBeLessThanOrEqual(tolerancePx)
+}
+
+describe('m3-vue/surface stories e2e', () => {
+  let mounted: MountedStory | null = null
+
+  beforeEach(async () => {
+    await page.viewport(1440, 1024)
+  })
+
+  afterEach(() => {
+    mounted?.app.unmount()
+    mounted?.mountPoint.remove()
+    mounted = null
+    document.body.innerHTML = ''
+  })
+
+  test('keeps side-sheet docked->modal->docked roundtrip smooth and stateful', async () => {
+    mounted = mountStory(SurfaceSideSheetMorph)
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-morph-docked-sheet"]')).not.toBeNull()
+    })
+
+    const root = query<HTMLElement>('[data-testid="surface-morph-root"]')
+    const content = query<HTMLElement>('[data-testid="surface-morph-content-grid"]')
+    const beforeWidth = content.getBoundingClientRect().width
+
+    click('[data-testid="surface-morph-toggle"]')
+    await nextTick()
+
+    const expandSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-morph-content-grid"]').getBoundingClientRect().width, 440, 28)
+    const expandDeltas = deltas(expandSeries)
+
+    await waitFor(() => {
+      expect(root.getAttribute('data-sheet-modal')).toBe('true')
+      expect(document.querySelector('[data-testid="surface-morph-modal-sheet"]')).not.toBeNull()
+      expect(document.querySelector('.m3-surface__scrim')).not.toBeNull()
+    })
+
+    const modalWidth = content.getBoundingClientRect().width
+    expect(modalWidth).toBeGreaterThan(beforeWidth + 220)
+    expect(expandDeltas.some(delta => delta > 0.2)).toBe(true)
+    expect(Math.min(...expandDeltas)).toBeGreaterThan(-8)
+
+    click('[data-testid="surface-morph-toggle"]')
+    await nextTick()
+
+    const collapseSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-morph-content-grid"]').getBoundingClientRect().width, 1320, 32)
+    const collapseDeltas = deltas(collapseSeries)
+
+    await waitFor(() => {
+      expect(root.getAttribute('data-sheet-modal')).toBe('false')
+      expect(document.querySelector('[data-testid="surface-morph-docked-sheet"]')).not.toBeNull()
+      expect(document.querySelector('[data-testid="surface-morph-modal-sheet"]')).toBeNull()
+    }, 2200)
+
+    await delay(340)
+
+    const afterWidth = content.getBoundingClientRect().width
+    expect(Math.abs(afterWidth - beforeWidth)).toBeLessThan(16)
+    expect(collapseDeltas.some(delta => delta < -0.2)).toBe(true)
+    expect(Math.max(...collapseDeltas)).toBeLessThan(34)
+  })
+
+  test('keeps card->page->card geometry and layer choreography stable', async () => {
+    mounted = mountStory(SurfaceCardPageMorph)
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-card-origin"]')).not.toBeNull()
+    })
+
+    const root = query<HTMLElement>('[data-testid="surface-card-page-root"]')
+    const canvas = query<HTMLElement>('[data-testid="surface-card-canvas"]')
+    const overlayWrap = query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]')
+    const originBefore = query<HTMLElement>('[data-testid="surface-card-origin"]').getBoundingClientRect()
+
+    expect(document.querySelector('[data-testid="surface-card-grid"]')).not.toBeNull()
+
+    click('[data-testid="surface-card-toggle"]')
+    await nextTick()
+
+    await delay(120)
+    expect(document.querySelector('[data-testid="surface-card-grid"]')).not.toBeNull()
+
+    const widthSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]').getBoundingClientRect().width, 380, 28)
+    const heightSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]').getBoundingClientRect().height, 380, 28)
+    const widthDeltas = deltas(widthSeries)
+    const heightDeltas = deltas(heightSeries)
+
+    expect(widthDeltas.some(delta => delta > 0.2) || heightDeltas.some(delta => delta > 0.2)).toBe(true)
+    expect(Math.min(...widthDeltas)).toBeGreaterThan(-8)
+    expect(Math.min(...heightDeltas)).toBeGreaterThan(-8)
+
+    await waitFor(() => {
+      expect(root.getAttribute('data-card-expanded')).toBe('true')
+      expect(document.querySelector('[data-testid="surface-card-grid"]')).toBeNull()
+    }, 2200)
+
+    const expandedRect = overlayWrap.getBoundingClientRect()
+    const canvasRect = canvas.getBoundingClientRect()
+    expect(expandedRect.width).toBeGreaterThan(canvasRect.width - 6)
+    expect(expandedRect.height).toBeGreaterThan(canvasRect.height - 6)
+
+    click('[data-testid="surface-card-toggle"]')
+    await nextTick()
+
+    await delay(80)
+    expect(document.querySelector('[data-testid="surface-card-grid"]')).not.toBeNull()
+
+    const collapseWidthSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]').getBoundingClientRect().width, 420, 28)
+    const collapseHeightSeries = await collectSeries(() => query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]').getBoundingClientRect().height, 420, 28)
+    const collapseWidthDeltas = deltas(collapseWidthSeries)
+    const collapseHeightDeltas = deltas(collapseHeightSeries)
+
+    expect(collapseWidthDeltas.some(delta => delta < -0.2)).toBe(true)
+    expect(collapseWidthDeltas.some(delta => delta < -0.2) || collapseHeightDeltas.some(delta => delta < -0.2)).toBe(true)
+    expect(Math.max(...collapseWidthDeltas)).toBeLessThan(42)
+    expect(Math.max(...collapseHeightDeltas)).toBeLessThan(42)
+
+    await waitFor(() => {
+      expect(root.getAttribute('data-card-expanded')).toBe('false')
+      expect(document.querySelector('[data-testid="surface-card-grid"]')).not.toBeNull()
+    }, 2200)
+
+    const originAfter = query<HTMLElement>('[data-testid="surface-card-origin"]').getBoundingClientRect()
+    const collapsedRect = overlayWrap.getBoundingClientRect()
+
+    expect(Math.abs(collapsedRect.width - originAfter.width)).toBeLessThan(12)
+    expect(Math.abs(collapsedRect.height - originAfter.height)).toBeLessThan(12)
+    expect(Math.abs(originAfter.width - originBefore.width)).toBeLessThan(8)
+    expect(Math.abs(originAfter.height - originBefore.height)).toBeLessThan(8)
+  })
+
+  test('reopens always-modal side-sheet with animated entry after close', async () => {
+    mounted = mountStory(SurfaceSideSheetAlwaysModal)
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-always-open"]')).not.toBeNull()
+    })
+
+    const openAndSampleEntry = async () => {
+      click('[data-testid="surface-always-open"]')
+      await nextTick()
+
+      await waitFor(() => {
+        expect(document.querySelector('[data-testid="surface-always-panel"]')).not.toBeNull()
+      })
+
+      const rightSeries = await collectSeries(
+        () => toNumber(getComputedStyle(query<HTMLElement>('[data-testid="surface-always-panel"]')).right),
+        380,
+        24
+      )
+
+      const rightDeltas = deltas(rightSeries)
+      const amplitude = Math.max(...rightSeries) - Math.min(...rightSeries)
+
+      expect(amplitude).toBeGreaterThan(40)
+      expect(rightDeltas.some(delta => delta > 0.2)).toBe(true)
+    }
+
+    await openAndSampleEntry()
+
+    click('[data-testid="surface-always-close"]')
+    await nextTick()
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-always-panel"]')).toBeNull()
+    }, 2200)
+
+    await openAndSampleEntry()
+  })
+
+  test('closes modal window with fade+slide and keeps animated re-open in side-sheet mode', async () => {
+    mounted = mountStory(SurfaceSideSheetModalToWindow)
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-window-open"]')).not.toBeNull()
+    })
+
+    const openAndSampleSheetEntry = async () => {
+      click('[data-testid="surface-window-open"]')
+      await nextTick()
+
+      await waitFor(() => {
+        const panel = document.querySelector('[data-testid="surface-window-panel"]') as HTMLElement | null
+        expect(panel).not.toBeNull()
+        expect(panel?.getAttribute('data-panel-mode')).toBe('sheet')
+      })
+
+      const rightSeries = await collectSeries(
+        () => toNumber(getComputedStyle(query<HTMLElement>('[data-testid="surface-window-panel"]')).right),
+        380,
+        24
+      )
+
+      const rightDeltas = deltas(rightSeries)
+      const amplitude = Math.max(...rightSeries) - Math.min(...rightSeries)
+
+      expect(amplitude).toBeGreaterThan(40)
+      expect(rightDeltas.some(delta => delta > 0.2)).toBe(true)
+    }
+
+    await openAndSampleSheetEntry()
+
+    click('[data-testid="surface-window-toggle-mode"]')
+    await nextTick()
+
+    await waitFor(() => {
+      expect(query<HTMLElement>('[data-testid="surface-window-panel"]').getAttribute('data-panel-mode')).toBe('window')
+    }, 1800)
+
+    await waitFor(() => {
+      expect(query<HTMLButtonElement>('[data-testid="surface-window-close"]').disabled).toBe(false)
+    }, 1200)
+
+    click('[data-testid="surface-window-close"]')
+    await nextTick()
+
+    await delay(260)
+    expect(document.querySelector('[data-testid="surface-window-panel"]')).not.toBeNull()
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-window-panel"]')).toBeNull()
+      expect(query<HTMLElement>('[data-testid="surface-window-root"]').getAttribute('data-panel-mounted')).toBe('false')
+    }, 2600)
+
+    await openAndSampleSheetEntry()
+  })
+
+  test('keeps only one top scrim in nested chain and preserves center+slide dialog motion', async () => {
+    mounted = mountStory(SurfaceNestedDialogsChain)
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-dialog-chain-open-root"]')).not.toBeNull()
+    })
+
+    click('[data-testid="surface-dialog-chain-open-root"]')
+    await nextTick()
+
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="surface-dialog-chain-level-1"]')).not.toBeNull()
+      expect(query<HTMLElement>('.surface-dialog-chain').getAttribute('data-top-level')).toBe('0')
+    })
+
+    while (true) {
+      const root = query<HTMLElement>('.surface-dialog-chain')
+      const topLevel = Number.parseInt(root.getAttribute('data-top-level') ?? '-1', 10)
+
+      expect(topLevel).toBeGreaterThanOrEqual(0)
+
+      const topDialogSelector = `[data-testid="surface-dialog-chain-level-${topLevel + 1}"]`
+      await waitFor(() => {
+        expectCentered(query<HTMLElement>(topDialogSelector), 10)
+      }, 900)
+
+      expect(document.querySelectorAll('.m3-surface__scrim').length).toBe(1)
+
+      const openNextSelector = `[data-testid="surface-dialog-chain-open-next-${topLevel + 1}"]`
+      const openNextButton = document.querySelector(openNextSelector) as HTMLButtonElement | null
+
+      if (!openNextButton) {
+        break
+      }
+
+      openNextButton.dispatchEvent(new MouseEvent('click', {
+        bubbles: true,
+        cancelable: true,
+      }))
+      await nextTick()
+
+      const nextDialogSelector = `[data-testid="surface-dialog-chain-level-${topLevel + 2}"]`
+      await waitFor(() => {
+        expect(document.querySelector(nextDialogSelector)).not.toBeNull()
+      })
+
+      const translateYSeries = await collectSeries(
+        () => matrixTranslateY(query<HTMLElement>(nextDialogSelector)),
+        340,
+        24
+      )
+      const translateYDeltas = deltas(translateYSeries)
+      const amplitude = Math.max(...translateYSeries) - Math.min(...translateYSeries)
+
+      expect(amplitude).toBeGreaterThan(6)
+      expect(translateYDeltas.some(delta => delta < -0.15)).toBe(true)
+
+      await waitFor(() => {
+        expect(query<HTMLElement>('.surface-dialog-chain').getAttribute('data-top-level')).toBe(`${topLevel + 1}`)
+      })
+
+      expect(document.querySelectorAll('.m3-surface__scrim').length).toBe(1)
+      expectCentered(query<HTMLElement>(nextDialogSelector), 10)
+    }
+  })
+})
diff --git a/m3-vue/tests/fixtures/SurfaceExperimentHarness.vue b/m3-vue/tests/fixtures/SurfaceExperimentHarness.vue
new file mode 100644
index 0000000..e96e919
--- /dev/null
+++ b/m3-vue/tests/fixtures/SurfaceExperimentHarness.vue
@@ -0,0 +1,542 @@
+<template>
+    <div class="surface-exp" data-testid="surface-exp-root">
+        <M3Surface
+            class="surface-exp__topbar"
+            data-testid="surface-topbar"
+            :fill-height="false"
+            :height="64"
+            variant="surface-container"
+            :elevation="2"
+        >
+            <div class="surface-exp__topbar-content">
+                <strong>Surface Experiment</strong>
+                <div class="surface-exp__controls">
+                    <button
+                        type="button"
+                        data-testid="sheet-to-modal"
+                        @click="morphSheetToModal"
+                    >
+                        Sheet: Docked -> Modal
+                    </button>
+                    <button
+                        type="button"
+                        data-testid="card-to-page"
+                        @click="morphCardToPage"
+                    >
+                        Card -> Full Page
+                    </button>
+                </div>
+            </div>
+        </M3Surface>
+
+        <div class="surface-exp__frame">
+            <M3Surface
+                class="surface-exp__rail"
+                data-testid="surface-nav-rail"
+                :fill-width="false"
+                :width="88"
+                variant="surface-container-low"
+                :elevation="1"
+            >
+                <div class="surface-exp__rail-stack">
+                    <span>Nav</span>
+                    <span>Home</span>
+                    <span>Docs</span>
+                    <span>Lab</span>
+                </div>
+            </M3Surface>
+
+            <div class="surface-exp__workspace">
+                <section class="surface-exp__scenario" data-testid="scenario-side-sheet">
+                    <header class="surface-exp__scenario-head">
+                        <h2>Scenario A: Multi-surface + Docked Sheet -> Modal</h2>
+                    </header>
+
+                    <div class="sheet-layout">
+                        <main class="sheet-layout__content" data-testid="sheet-layout-content">
+                            <M3Surface
+                                class="sheet-layout__card"
+                                data-testid="static-role-surface-container-lowest"
+                                :fill-height="false"
+                                :height="112"
+                                :rounding="20"
+                                variant="surface-container-lowest"
+                                :elevation="0"
+                            >
+                                <strong>Static block: surface-container-lowest</strong>
+                                <p>Neutral content block anchored in page flow.</p>
+                            </M3Surface>
+
+                            <M3Surface
+                                class="sheet-layout__card"
+                                data-testid="static-role-surface-container-low"
+                                :fill-height="false"
+                                :height="112"
+                                :rounding="20"
+                                variant="surface-container-low"
+                                :elevation="1"
+                            >
+                                <strong>Static block: surface-container-low</strong>
+                                <p>Secondary panel with increased emphasis.</p>
+                            </M3Surface>
+
+                            <M3Surface
+                                class="sheet-layout__card"
+                                data-testid="static-role-surface-container-high"
+                                :fill-height="false"
+                                :height="112"
+                                :rounding="20"
+                                variant="surface-container-high"
+                                :elevation="3"
+                            >
+                                <strong>Static block: surface-container-high</strong>
+                                <p>Read-only section with stronger elevation.</p>
+                            </M3Surface>
+
+                            <M3Surface
+                                class="sheet-layout__card"
+                                data-testid="static-role-surface-dim"
+                                :fill-height="false"
+                                :height="112"
+                                :rounding="20"
+                                variant="surface-dim"
+                                :elevation="0"
+                            >
+                                <strong>Static block: surface-dim</strong>
+                                <p>Low-brightness background container.</p>
+                            </M3Surface>
+                        </main>
+
+                        <div
+                            v-if="!sheetIsModal"
+                            class="sheet-layout__docked-host"
+                            data-testid="sheet-docked-host"
+                            :style="{ width: `${sheetDockedWidth}px` }"
+                        >
+                            <M3Surface
+                                class="sheet-layout__sheet"
+                                data-testid="orchestrated-side-sheet"
+                                :fill-width="true"
+                                :fill-height="true"
+                                :rounding="0"
+                                variant="surface-container-low"
+                                :elevation="1"
+                                overflow="auto"
+                            >
+                                <h3>Docked side sheet</h3>
+                                <p>Initial state: coplanar with the main content.</p>
+                                <p>It can coexist with interactions in page content.</p>
+                            </M3Surface>
+                        </div>
+
+                        <M3Surface
+                            v-else
+                            class="sheet-layout__sheet sheet-layout__sheet_modal"
+                            data-testid="orchestrated-side-sheet"
+                            mode="modal"
+                            anchor="end"
+                            :fill-width="false"
+                            :fill-height="false"
+                            :width="420"
+                            height="calc(100vh - 96px)"
+                            :inset-top="72"
+                            :inset-right="24"
+                            :inset-bottom="24"
+                            :rounding-top-left="28"
+                            :rounding-bottom-left="28"
+                            :rounding-top-right="0"
+                            :rounding-bottom-right="0"
+                            variant="surface-container-high"
+                            :elevation="4"
+                            :z-index="520"
+                            :transition-ms="320"
+                            overflow="auto"
+                        >
+                            <h3>Modal side sheet</h3>
+                            <p>Layer switched from docked flow to modal surface stack.</p>
+                            <p>Main content expands while sheet is detached to modal layer.</p>
+                        </M3Surface>
+                    </div>
+                </section>
+
+                <section class="surface-exp__scenario" data-testid="scenario-card-page">
+                    <header class="surface-exp__scenario-head">
+                        <h2>Scenario B: Card -> Full Page</h2>
+                    </header>
+
+                    <div
+                        ref="cardCanvas"
+                        class="card-morph-layout"
+                        data-testid="card-canvas"
+                    >
+                        <div class="card-morph-layout__grid">
+                            <div
+                                ref="cardOrigin"
+                                class="card-morph-layout__origin"
+                                data-testid="card-origin-slot"
+                                :style="{ minHeight: `${cardPlaceholderHeight}px` }"
+                            />
+                            <M3Surface
+                                class="card-morph-layout__card"
+                                data-testid="card-static-a"
+                                :fill-height="false"
+                                :height="176"
+                                :rounding="16"
+                                variant="surface-container-low"
+                                :elevation="1"
+                            >
+                                <strong>Static card A</strong>
+                                <p>Background card in feed.</p>
+                            </M3Surface>
+                            <M3Surface
+                                class="card-morph-layout__card"
+                                data-testid="card-static-b"
+                                :fill-height="false"
+                                :height="176"
+                                :rounding="16"
+                                variant="surface-container"
+                                :elevation="2"
+                            >
+                                <strong>Static card B</strong>
+                                <p>Background card in feed.</p>
+                            </M3Surface>
+                        </div>
+
+                        <div class="card-morph-layout__overlay" data-testid="card-overlay-layer">
+                            <div
+                                class="card-morph-layout__overlay-wrap"
+                                data-testid="card-overlay-wrap"
+                                :style="cardOverlayStyle"
+                            >
+                                <M3Surface
+                                    :class="[
+                                        'card-morph-layout__overlay-surface',
+                                        cardExpanded
+                                            ? 'card-morph-layout__overlay-surface_expanded'
+                                            : 'card-morph-layout__overlay-surface_compact',
+                                    ]"
+                                    data-testid="orchestrated-card-surface"
+                                    :fill-width="true"
+                                    :fill-height="true"
+                                    :rounding="cardExpanded ? 0 : 24"
+                                    :transition-ms="320"
+                                    transition-timing="cubic-bezier(0.2, 0, 0, 1)"
+                                    :variant="cardExpanded ? 'surface' : 'surface-container-low'"
+                                    :elevation="cardExpanded ? 0 : 1"
+                                    overflow="auto"
+                                >
+                                    <h3>Surface morph target</h3>
+                                    <p>Initial card geometry transitions into a page-like container.</p>
+                                    <p>Reserved zones are kept by top app bar and nav rail layout.</p>
+                                </M3Surface>
+                            </div>
+                        </div>
+                    </div>
+                </section>
+            </div>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import {
+  computed,
+  nextTick,
+  onMounted,
+  ref,
+} from 'vue'
+
+import M3Surface from '@/components/surface/M3Surface.vue'
+
+const sheetIsModal = ref(false)
+const sheetWidth = 360
+const sheetDockedWidth = ref(sheetWidth)
+
+const cardCanvas = ref<HTMLElement | null>(null)
+const cardOrigin = ref<HTMLElement | null>(null)
+const cardExpanded = ref(false)
+const cardPlaceholderHeight = ref(220)
+const cardMotion = ref({
+  top: 16,
+  left: 16,
+  width: 320,
+  height: 220,
+})
+
+const cardOverlayStyle = computed(() => ({
+  top: `${cardMotion.value.top}px`,
+  left: `${cardMotion.value.left}px`,
+  width: `${cardMotion.value.width}px`,
+  height: `${cardMotion.value.height}px`,
+}))
+
+function raf() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+function delay(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+function measureCardOrigin() {
+  if (!cardCanvas.value || !cardOrigin.value) {
+    return null
+  }
+
+  const canvasRect = cardCanvas.value.getBoundingClientRect()
+  const originRect = cardOrigin.value.getBoundingClientRect()
+
+  return {
+    top: originRect.top - canvasRect.top,
+    left: originRect.left - canvasRect.left,
+    width: originRect.width,
+    height: originRect.height,
+  }
+}
+
+function measureCardExpanded() {
+  if (!cardCanvas.value) {
+    return null
+  }
+
+  const canvasRect = cardCanvas.value.getBoundingClientRect()
+
+  return {
+    top: 12,
+    left: 12,
+    width: Math.max(320, canvasRect.width - 24),
+    height: Math.max(220, canvasRect.height - 24),
+  }
+}
+
+async function initCardGeometry() {
+  await nextTick()
+  await raf()
+  const origin = measureCardOrigin()
+  if (!origin) {
+    return
+  }
+
+  cardMotion.value = origin
+  cardPlaceholderHeight.value = origin.height
+}
+
+async function morphSheetToModal() {
+  if (sheetIsModal.value) {
+    return
+  }
+
+  sheetDockedWidth.value = sheetWidth
+  await nextTick()
+  await raf()
+  sheetDockedWidth.value = 0
+  await delay(440)
+  sheetIsModal.value = true
+}
+
+async function morphCardToPage() {
+  if (cardExpanded.value) {
+    return
+  }
+
+  const origin = measureCardOrigin()
+  if (origin) {
+    cardMotion.value = origin
+    cardPlaceholderHeight.value = origin.height
+  }
+
+  cardExpanded.value = true
+  await nextTick()
+  await raf()
+
+  const expanded = measureCardExpanded()
+  if (!expanded) {
+    return
+  }
+
+  cardMotion.value = expanded
+}
+
+onMounted(() => {
+  initCardGeometry()
+})
+</script>
+
+<style scoped>
+.surface-exp {
+  min-height: 100vh;
+  background: linear-gradient(135deg, #f7f2fa 0%, #efe8f7 100%);
+  color: #1d1b20;
+}
+
+.surface-exp__topbar-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.surface-exp__topbar {
+  padding: 16px;
+}
+
+.surface-exp__controls {
+  display: flex;
+  gap: 8px;
+}
+
+.surface-exp__controls button {
+  border: 1px solid rgba(73, 69, 79, 0.3);
+  border-radius: 10px;
+  background: #fff;
+  color: #1d1b20;
+  font: 600 12px/1.1 Arial, sans-serif;
+  padding: 8px 10px;
+  cursor: pointer;
+}
+
+.surface-exp__frame {
+  display: flex;
+  min-height: calc(100vh - 64px);
+}
+
+.surface-exp__rail {
+  flex: 0 0 auto;
+  padding: 12px;
+}
+
+.surface-exp__rail-stack {
+  display: grid;
+  gap: 8px;
+  align-content: start;
+  font: 600 13px/1.2 Arial, sans-serif;
+}
+
+.surface-exp__workspace {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 20px;
+  display: grid;
+  gap: 18px;
+}
+
+.surface-exp__scenario {
+  background: rgba(255, 255, 255, 0.7);
+  border-radius: 20px;
+  border: 1px solid rgba(73, 69, 79, 0.16);
+  padding: 16px;
+}
+
+.surface-exp__scenario-head {
+  margin-bottom: 12px;
+}
+
+.surface-exp__scenario-head h2 {
+  margin: 0;
+  font: 700 14px/1.3 Arial, sans-serif;
+}
+
+.sheet-layout {
+  min-height: 360px;
+  display: flex;
+  gap: 0;
+  border-radius: 16px;
+  overflow: hidden;
+  border: 1px solid rgba(73, 69, 79, 0.2);
+  background: rgba(249, 245, 253, 0.9);
+}
+
+.sheet-layout__content {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 14px;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  align-content: start;
+}
+
+.sheet-layout__content > .sheet-layout__card {
+  padding: 18px;
+}
+
+.sheet-layout__content p,
+.card-morph-layout p {
+  margin: 6px 0 0;
+  font: 400 12px/1.35 Arial, sans-serif;
+}
+
+.sheet-layout__docked-host {
+  flex: 0 0 auto;
+  width: 360px;
+  min-width: 0;
+  overflow: hidden;
+  transition: width 420ms cubic-bezier(0.2, 0, 0, 1);
+  border-left: 1px solid rgba(73, 69, 79, 0.2);
+}
+
+:global(.sheet-layout__sheet) {
+  padding: 20px;
+}
+
+:global(.sheet-layout__sheet_modal) {
+  padding: 24px;
+}
+
+.card-morph-layout {
+  position: relative;
+  min-height: 420px;
+  border-radius: 16px;
+  border: 1px solid rgba(73, 69, 79, 0.2);
+  background: rgba(249, 245, 253, 0.9);
+  overflow: hidden;
+}
+
+.card-morph-layout__grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  padding: 14px;
+}
+
+.card-morph-layout__grid > .card-morph-layout__card {
+  padding: 16px;
+}
+
+.card-morph-layout__origin {
+  border-radius: 24px;
+  border: 1px dashed rgba(73, 69, 79, 0.24);
+  background: rgba(208, 188, 255, 0.15);
+}
+
+.card-morph-layout__overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.card-morph-layout__overlay-wrap {
+  position: absolute;
+  transition:
+    top 320ms cubic-bezier(0.2, 0, 0, 1),
+    left 320ms cubic-bezier(0.2, 0, 0, 1),
+    width 320ms cubic-bezier(0.2, 0, 0, 1),
+    height 320ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+.card-morph-layout__overlay-wrap :deep(.m3-surface) {
+  pointer-events: auto;
+}
+
+.card-morph-layout__overlay-surface_compact {
+  padding: 20px;
+}
+
+.card-morph-layout__overlay-surface_expanded {
+  padding: 28px;
+}
+</style>

From b718d8162a7ef0fc63f851fdeea209093e954d5c Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 14:14:07 +0400
Subject: [PATCH 13/37] feat(m3-foundation): Added Surface Stylesheet Module

---
 .../assets/stylesheets/components/index.scss  |  1 +
 .../stylesheets/components/surface/index.scss | 76 +++++++++++++++++++
 m3-foundation/assets/stylesheets/layout.scss  | 11 +--
 3 files changed, 78 insertions(+), 10 deletions(-)
 create mode 100644 m3-foundation/assets/stylesheets/components/surface/index.scss

diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index d436339..0fb04f0 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -19,4 +19,5 @@
 @use 'side-sheet';
 @use 'slider';
 @use 'switch';
+@use 'surface';
 @use 'text-field';
diff --git a/m3-foundation/assets/stylesheets/components/surface/index.scss b/m3-foundation/assets/stylesheets/components/surface/index.scss
new file mode 100644
index 0000000..03560c7
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/surface/index.scss
@@ -0,0 +1,76 @@
+@use '../../basics/motion' as m3-motion;
+@use '../../basics/palette' as palette;
+@use '../../themes/dark' as dark;
+@use '../../themes/light' as light;
+
+.m3-surface {
+  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{light.$m3-sys-light-surface});
+  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{palette.$m3-palette-neutral-100});
+  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{light.$m3-sys-light-surface-container});
+  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{light.$m3-sys-light-surface-container-high});
+  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+  --m3-surface-elevation-1: var(--m3-elevation-1, #{light.$m3-elevation-light-1});
+  --m3-surface-elevation-2: var(--m3-elevation-2, #{light.$m3-elevation-light-2});
+  --m3-surface-elevation-3: var(--m3-elevation-3, #{light.$m3-elevation-light-3});
+  --m3-surface-elevation-4: var(--m3-elevation-4, #{light.$m3-elevation-light-4});
+  --m3-surface-elevation-5: var(--m3-elevation-5, #{light.$m3-elevation-light-5});
+  --m3-surface-radius-transition-duration: #{m3-motion.duration('medium2')};
+
+  display: block;
+  isolation: isolate;
+  box-sizing: border-box;
+  transition:
+    border-top-left-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')},
+    border-top-right-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')},
+    border-bottom-right-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')},
+    border-bottom-left-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')};
+
+  &_modal {
+    max-width: 100vw;
+    max-height: 100vh;
+  }
+
+  &_role-surface {
+    background-color: var(--m3-surface-role-surface-bg);
+  }
+
+  &_role-surface-dim               { background-color: var(--m3-surface-role-surface-dim-bg); }
+  &_role-surface-bright            { background-color: var(--m3-surface-role-surface-bright-bg); }
+  &_role-surface-container-lowest  { background-color: var(--m3-surface-role-container-lowest-bg); }
+  &_role-surface-container-low     { background-color: var(--m3-surface-role-container-low-bg); }
+  &_role-surface-container         { background-color: var(--m3-surface-role-container-bg); }
+  &_role-surface-container-high    { background-color: var(--m3-surface-role-container-high-bg); }
+  &_role-surface-container-highest { background-color: var(--m3-surface-role-container-highest-bg); }
+
+  &_elevation-0 { box-shadow: none; }
+  &_elevation-1 { box-shadow: var(--m3-surface-elevation-1); }
+  &_elevation-2 { box-shadow: var(--m3-surface-elevation-2); }
+  &_elevation-3 { box-shadow: var(--m3-surface-elevation-3); }
+  &_elevation-4 { box-shadow: var(--m3-surface-elevation-4); }
+  &_elevation-5 { box-shadow: var(--m3-surface-elevation-5); }
+
+  &__scrim {
+    position: fixed;
+    inset: 0;
+    background: color-mix(in srgb, var(--m3-sys-shadow, #{palette.$m3-palette-neutral-0}) 38%, transparent);
+  }
+}
+
+html.m3-theme-dark .m3-surface {
+  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
+  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
+  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
+  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
+  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
+  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{dark.$m3-sys-dark-surface-container});
+  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{dark.$m3-sys-dark-surface-container-high});
+  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
+  --m3-surface-elevation-1: var(--m3-elevation-1, #{dark.$m3-elevation-dark-1});
+  --m3-surface-elevation-2: var(--m3-elevation-2, #{dark.$m3-elevation-dark-2});
+  --m3-surface-elevation-3: var(--m3-elevation-3, #{dark.$m3-elevation-dark-3});
+  --m3-surface-elevation-4: var(--m3-elevation-4, #{dark.$m3-elevation-dark-4});
+  --m3-surface-elevation-5: var(--m3-elevation-5, #{dark.$m3-elevation-dark-5});
+}
diff --git a/m3-foundation/assets/stylesheets/layout.scss b/m3-foundation/assets/stylesheets/layout.scss
index de2c60a..96ecf20 100644
--- a/m3-foundation/assets/stylesheets/layout.scss
+++ b/m3-foundation/assets/stylesheets/layout.scss
@@ -1,12 +1,3 @@
-.m3-surface {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
-  height: 100%;
-  background: var(--m3-sys-surface);
-  color: var(--m3-sys-on-surface);
-}
-
 .m3-panel {
   padding: 32px;
   background: var(--m3-sys-surface-container-low);
@@ -16,4 +7,4 @@
   &_elevated-1 { background: var(--m3-sys-surface-container); }
   &_elevated-2 { background: var(--m3-sys-surface-container-high); }
   &_elevated-3 { background: var(--m3-sys-surface-container-highest); }
-}
\ No newline at end of file
+}

From b99bd7af13899eb40a31ac795a0abffe8c2b3207 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 14:16:35 +0400
Subject: [PATCH 14/37] feat(m3-foundation): Added Motion Values And Surface
 Types

---
 m3-foundation/lib/motion/index.ts           | 10 ++++
 m3-foundation/lib/motion/values.ts          | 61 +++++++++++++++++++++
 m3-foundation/types/components/surface.d.ts | 26 +++++++++
 3 files changed, 97 insertions(+)
 create mode 100644 m3-foundation/lib/motion/index.ts
 create mode 100644 m3-foundation/lib/motion/values.ts
 create mode 100644 m3-foundation/types/components/surface.d.ts

diff --git a/m3-foundation/lib/motion/index.ts b/m3-foundation/lib/motion/index.ts
new file mode 100644
index 0000000..8bb94d3
--- /dev/null
+++ b/m3-foundation/lib/motion/index.ts
@@ -0,0 +1,10 @@
+export type {
+  M3MotionDurationKey,
+  M3MotionEasingKey,
+} from './values'
+
+export {
+  m3MotionDurations,
+  m3MotionEasings,
+  m3MotionTimingDefaults,
+} from './values'
diff --git a/m3-foundation/lib/motion/values.ts b/m3-foundation/lib/motion/values.ts
new file mode 100644
index 0000000..ae8b788
--- /dev/null
+++ b/m3-foundation/lib/motion/values.ts
@@ -0,0 +1,61 @@
+export const m3MotionDurations = {
+  short1: 50,
+  short2: 100,
+  short3: 150,
+  short4: 200,
+  medium1: 250,
+  medium2: 300,
+  medium3: 350,
+  medium4: 400,
+  long1: 450,
+  long2: 500,
+  long3: 550,
+  long4: 600,
+  'extra-long1': 700,
+  'extra-long2': 800,
+  'extra-long3': 900,
+  'extra-long4': 1000,
+} as const
+
+export type M3MotionDurationKey = keyof typeof m3MotionDurations
+
+export const m3MotionEasings = {
+  emphasized: 'cubic-bezier(0.2, 0.0, 0, 1.0)',
+  'emphasized-accelerate': 'cubic-bezier(0.3, 0.0, 0.8, 0.15)',
+  'emphasized-decelerate': 'cubic-bezier(0.05, 0.7, 0.1, 1.0)',
+  standard: 'cubic-bezier(0.2, 0.0, 0, 1.0)',
+  'standard-accelerate': 'cubic-bezier(0.3, 0, 1, 1)',
+  'standard-decelerate': 'cubic-bezier(0, 0, 0, 1)',
+} as const
+
+export type M3MotionEasingKey = keyof typeof m3MotionEasings
+
+export const m3MotionTimingDefaults = {
+  emphasized: {
+    duration: 'long2',
+    easing: 'emphasized',
+  },
+  'emphasized-accelerate': {
+    duration: 'short4',
+    easing: 'emphasized-accelerate',
+  },
+  'emphasized-decelerate': {
+    duration: 'medium4',
+    easing: 'emphasized-decelerate',
+  },
+  standard: {
+    duration: 'medium2',
+    easing: 'standard',
+  },
+  'standard-accelerate': {
+    duration: 'short4',
+    easing: 'standard-accelerate',
+  },
+  'standard-decelerate': {
+    duration: 'medium1',
+    easing: 'standard-decelerate',
+  },
+} as const satisfies Record<string, {
+  duration: M3MotionDurationKey;
+  easing: M3MotionEasingKey;
+}>
diff --git a/m3-foundation/types/components/surface.d.ts b/m3-foundation/types/components/surface.d.ts
new file mode 100644
index 0000000..b9ff647
--- /dev/null
+++ b/m3-foundation/types/components/surface.d.ts
@@ -0,0 +1,26 @@
+export type Length = string | number
+
+export type Mode = 'standard' | 'modal'
+
+export type Variant =
+  | 'auto'
+  | 'surface'
+  | 'surface-dim'
+  | 'surface-bright'
+  | 'surface-container-lowest'
+  | 'surface-container-low'
+  | 'surface-container'
+  | 'surface-container-high'
+  | 'surface-container-highest'
+
+export type Anchor =
+  | 'none'
+  | 'center'
+  | 'start'
+  | 'end'
+  | 'top'
+  | 'bottom'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom-start'
+  | 'bottom-end'

From be643633ead712c22ca04057b2e6a5b2a424ec16 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 14:37:46 +0400
Subject: [PATCH 15/37] feat(m3-react): Added M3Surface Component And Surface
 Storybook Scenarios

---
 m3-react/src/components/surface/M3Surface.tsx | 276 ++++++++
 m3-react/src/components/surface/index.ts      |   8 +
 m3-react/src/index.ts                         |  11 +
 m3-react/storybook/components/M3Surface.mdx   |  13 +
 .../components/M3Surface.stories.tsx          |  52 ++
 .../examples/surface/SurfaceCardPageMorph.tsx | 379 +++++++++++
 .../surface/SurfaceNestedDialogsChain.tsx     | 359 ++++++++++
 .../surface/SurfaceSideSheetAlwaysModal.tsx   | 347 ++++++++++
 .../SurfaceSideSheetDismissToRemove.tsx       | 452 +++++++++++++
 .../surface/SurfaceSideSheetModalToWindow.tsx | 609 +++++++++++++++++
 .../surface/SurfaceSideSheetMorph.tsx         | 487 ++++++++++++++
 .../storybook/examples/surface/styles.scss    | 628 ++++++++++++++++++
 m3-react/storybook/examples/surface/utils.ts  |  51 ++
 m3-react/tests/M3Surface.test.tsx             | 112 ++++
 14 files changed, 3784 insertions(+)
 create mode 100644 m3-react/src/components/surface/M3Surface.tsx
 create mode 100644 m3-react/src/components/surface/index.ts
 create mode 100644 m3-react/storybook/components/M3Surface.mdx
 create mode 100644 m3-react/storybook/components/M3Surface.stories.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
 create mode 100644 m3-react/storybook/examples/surface/styles.scss
 create mode 100644 m3-react/storybook/examples/surface/utils.ts
 create mode 100644 m3-react/tests/M3Surface.test.tsx

diff --git a/m3-react/src/components/surface/M3Surface.tsx b/m3-react/src/components/surface/M3Surface.tsx
new file mode 100644
index 0000000..397e3fb
--- /dev/null
+++ b/m3-react/src/components/surface/M3Surface.tsx
@@ -0,0 +1,276 @@
+import type {
+  CSSProperties,
+  FC,
+  HTMLAttributes,
+} from 'react'
+import type {
+  Anchor as SurfaceAnchor,
+  Length as SurfaceLength,
+  Mode as SurfaceMode,
+  Variant as SurfaceVariant,
+} from '@modulify/m3-foundation/types/components/surface'
+
+import { createPortal } from 'react-dom'
+import { m3MotionEasings } from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useId,
+} from '@/hooks'
+
+import { toClassName } from '@/utils/styling'
+
+type Inset = {
+  top: string;
+  right: string;
+  bottom: string;
+  left: string;
+}
+
+export type M3SurfaceMode = SurfaceMode
+export type M3SurfaceVariant = SurfaceVariant
+export type M3SurfaceAnchor = SurfaceAnchor
+
+export interface M3SurfaceProps extends HTMLAttributes<HTMLElement> {
+  id?: string;
+  tag?: keyof HTMLElementTagNameMap;
+  shown?: boolean;
+  mode?: M3SurfaceMode;
+  teleportTo?: string;
+  scrim?: boolean;
+  elevation?: number;
+  variant?: M3SurfaceVariant;
+  fillWidth?: boolean;
+  fillHeight?: boolean;
+  width?: SurfaceLength | null;
+  height?: SurfaceLength | null;
+  minWidth?: SurfaceLength | null;
+  maxWidth?: SurfaceLength | null;
+  minHeight?: SurfaceLength | null;
+  maxHeight?: SurfaceLength | null;
+  rounding?: SurfaceLength;
+  roundingTopLeft?: SurfaceLength | null;
+  roundingTopRight?: SurfaceLength | null;
+  roundingBottomRight?: SurfaceLength | null;
+  roundingBottomLeft?: SurfaceLength | null;
+  anchor?: M3SurfaceAnchor;
+  insetTop?: SurfaceLength;
+  insetRight?: SurfaceLength;
+  insetBottom?: SurfaceLength;
+  insetLeft?: SurfaceLength;
+  zIndex?: number;
+  transitionMs?: number;
+  transitionTiming?: string;
+  overflow?: CSSProperties['overflow'];
+  onToggle?: (shown: boolean) => void;
+  onDismiss?: () => void;
+}
+
+type AnchorStyleFactory = (inset: Inset) => CSSProperties
+
+const MODAL_ANCHOR_STYLE: Record<SurfaceAnchor, AnchorStyleFactory> = {
+  none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
+  center: () => ({
+    top: '50%',
+    left: '50%',
+    right: 'auto',
+    bottom: 'auto',
+    transform: 'translate(-50%, -50%)',
+  }),
+  start: ({ top, bottom, left }) => ({ top, bottom, left, right: 'auto' }),
+  end: ({ top, right, bottom }) => ({ top, right, bottom, left: 'auto' }),
+  top: ({ top, left, right }) => ({ top, left, right, bottom: 'auto' }),
+  bottom: ({ bottom, left, right }) => ({ bottom, left, right, top: 'auto' }),
+  'top-start': ({ top, left }) => ({ top, left, right: 'auto', bottom: 'auto' }),
+  'top-end': ({ top, right }) => ({ top, right, left: 'auto', bottom: 'auto' }),
+  'bottom-start': ({ bottom, left }) => ({ bottom, left, right: 'auto', top: 'auto' }),
+  'bottom-end': ({ bottom, right }) => ({ bottom, right, left: 'auto', top: 'auto' }),
+}
+
+const toLength = (value: SurfaceLength | null | undefined, fallback: string): string => {
+  if (value == null) {
+    return fallback
+  }
+
+  return typeof value === 'number'
+    ? `${value}px`
+    : value
+}
+
+const isDefined = <T,>(value: T | null | undefined): value is T => value !== null && value !== undefined
+
+const getResolvedVariant = (variant: SurfaceVariant, elevation: number): Exclude<SurfaceVariant, 'auto'> => {
+  if (variant !== 'auto') return variant
+
+  switch (elevation) {
+    case 0: return 'surface'
+    case 1: return 'surface-container-low'
+    case 2: return 'surface-container'
+    case 3: return 'surface-container-high'
+    case 4: return 'surface-container-highest'
+    default: return 'surface-bright'
+  }
+}
+
+const M3Surface: FC<M3SurfaceProps> = ({
+  id,
+  tag = 'section',
+  shown = true,
+  mode = 'standard',
+  teleportTo = 'body',
+  scrim = true,
+  elevation = 0,
+  variant = 'auto',
+  fillWidth = true,
+  fillHeight = true,
+  width = null,
+  height = null,
+  minWidth = null,
+  maxWidth = null,
+  minHeight = null,
+  maxHeight = null,
+  rounding = 0,
+  roundingTopLeft = null,
+  roundingTopRight = null,
+  roundingBottomRight = null,
+  roundingBottomLeft = null,
+  anchor = 'none',
+  insetTop = 0,
+  insetRight = 0,
+  insetBottom = 0,
+  insetLeft = 0,
+  zIndex = 400,
+  transitionMs = 220,
+  transitionTiming = m3MotionEasings.standard,
+  overflow = 'visible',
+  onToggle = (_: boolean) => {},
+  onDismiss = () => {},
+  className = '',
+  style,
+  children = [],
+  ...attrs
+}) => {
+  const _id = useId(id, 'm3-surface')
+  const isModal = mode === 'modal'
+  const resolvedVariant = getResolvedVariant(variant, elevation)
+  const SurfaceTag = tag
+
+  const resolvedSizeStyle: CSSProperties = {
+    width: isDefined(width)
+      ? toLength(width, 'auto')
+      : (fillWidth ? '100%' : 'auto'),
+    height: isDefined(height)
+      ? toLength(height, 'auto')
+      : (fillHeight ? '100%' : 'auto'),
+    minWidth: isDefined(minWidth) ? toLength(minWidth, '0px') : undefined,
+    maxWidth: isDefined(maxWidth) ? toLength(maxWidth, 'none') : undefined,
+    minHeight: isDefined(minHeight) ? toLength(minHeight, '0px') : undefined,
+    maxHeight: isDefined(maxHeight) ? toLength(maxHeight, 'none') : undefined,
+  }
+
+  const baseRounding = toLength(rounding, '0px')
+
+  const cornerStyle: CSSProperties = {
+    borderTopLeftRadius: isDefined(roundingTopLeft) ? toLength(roundingTopLeft, baseRounding) : baseRounding,
+    borderTopRightRadius: isDefined(roundingTopRight) ? toLength(roundingTopRight, baseRounding) : baseRounding,
+    borderBottomRightRadius: isDefined(roundingBottomRight) ? toLength(roundingBottomRight, baseRounding) : baseRounding,
+    borderBottomLeftRadius: isDefined(roundingBottomLeft) ? toLength(roundingBottomLeft, baseRounding) : baseRounding,
+  }
+
+  const anchorStyle: CSSProperties = isModal
+    ? MODAL_ANCHOR_STYLE[anchor]({
+      top: toLength(insetTop, '0px'),
+      right: toLength(insetRight, '0px'),
+      bottom: toLength(insetBottom, '0px'),
+      left: toLength(insetLeft, '0px'),
+    })
+    : {}
+
+  const duration = `${transitionMs}ms`
+  const transition = [
+    `width ${duration} ${transitionTiming}`,
+    `height ${duration} ${transitionTiming}`,
+    `min-width ${duration} ${transitionTiming}`,
+    `max-width ${duration} ${transitionTiming}`,
+    `min-height ${duration} ${transitionTiming}`,
+    `max-height ${duration} ${transitionTiming}`,
+    `top ${duration} ${transitionTiming}`,
+    `right ${duration} ${transitionTiming}`,
+    `bottom ${duration} ${transitionTiming}`,
+    `left ${duration} ${transitionTiming}`,
+    `transform ${duration} ${transitionTiming}`,
+    `opacity ${duration} ${transitionTiming}`,
+    `background-color ${duration} ${transitionTiming}`,
+    `box-shadow ${duration} ${transitionTiming}`,
+  ].join(', ')
+
+  const surfaceClassName = toClassName([className, {
+    'm3-surface': true,
+    'm3-surface_modal': isModal,
+    [`m3-surface_role-${resolvedVariant}`]: true,
+    [`m3-surface_anchor-${anchor}`]: true,
+    [`m3-surface_elevation-${elevation}`]: true,
+  }])
+
+  const radiusTransitionStyle = {
+    '--m3-surface-radius-transition-duration': duration,
+  } as CSSProperties
+
+  const surfaceNode = (
+    <SurfaceTag
+      id={_id}
+      className={surfaceClassName}
+      style={{
+        ...resolvedSizeStyle,
+        ...cornerStyle,
+        ...anchorStyle,
+        ...radiusTransitionStyle,
+        overflow,
+        transition,
+        position: isModal ? 'fixed' : 'relative',
+        zIndex: isModal ? zIndex : undefined,
+        display: shown ? undefined : 'none',
+        ...style,
+      }}
+      {...(isModal
+        ? { role: 'dialog', 'aria-modal': 'true' as const }
+        : { role: 'region' })}
+      {...attrs}
+    >
+      {children}
+    </SurfaceTag>
+  )
+
+  if (!isModal) {
+    return surfaceNode
+  }
+
+  const portalTarget = typeof document === 'undefined'
+    ? null
+    : (teleportTo === 'body' ? document.body : (document.querySelector(teleportTo) || document.body))
+
+  if (!portalTarget) {
+    return null
+  }
+
+  return createPortal(
+    <>
+      {scrim ? (
+        <div
+          className="m3-surface__scrim"
+          style={{
+            zIndex: zIndex - 1,
+            display: shown ? undefined : 'none',
+          }}
+          onClick={() => {
+            onToggle(false)
+            onDismiss()
+          }}
+        />
+      ) : null}
+      {surfaceNode}
+    </>,
+    portalTarget
+  )
+}
+
+export default M3Surface
diff --git a/m3-react/src/components/surface/index.ts b/m3-react/src/components/surface/index.ts
new file mode 100644
index 0000000..f76f3b4
--- /dev/null
+++ b/m3-react/src/components/surface/index.ts
@@ -0,0 +1,8 @@
+export type {
+  M3SurfaceAnchor,
+  M3SurfaceMode,
+  M3SurfaceProps,
+  M3SurfaceVariant,
+} from './M3Surface'
+
+export { default as M3Surface } from './M3Surface'
diff --git a/m3-react/src/index.ts b/m3-react/src/index.ts
index 05606e1..0491e4f 100644
--- a/m3-react/src/index.ts
+++ b/m3-react/src/index.ts
@@ -81,6 +81,13 @@ export type {
   M3SideSheetProps,
 } from '@/components/side-sheet'
 
+export type {
+  M3SurfaceAnchor,
+  M3SurfaceMode,
+  M3SurfaceProps,
+  M3SurfaceVariant,
+} from '@/components/surface'
+
 export type {
   M3TextFieldMethods,
   M3TextFieldProps,
@@ -150,6 +157,10 @@ export {
   M3SideSheet,
 } from '@/components/side-sheet'
 
+export {
+  M3Surface,
+} from '@/components/surface'
+
 export {
   M3Select,
 } from '@/components/select'
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
new file mode 100644
index 0000000..5650ce0
--- /dev/null
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -0,0 +1,13 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SurfaceStories from './M3Surface.stories'
+
+<Meta of={M3SurfaceStories} />
+
+# Surfaces
+
+- [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
+- [Card Replacing Page](?path=/story/components-m3surface--card-replacing-page)
+- [Side Sheet Modal Dismiss Removes Surface](?path=/story/components-m3surface--side-sheet-modal-dismiss-removes-surface)
+- [Side Sheet Always Modal Toggle](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
+- [Side Sheet Modal To Window](?path=/story/components-m3surface--side-sheet-modal-to-window)
+- [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
diff --git a/m3-react/storybook/components/M3Surface.stories.tsx b/m3-react/storybook/components/M3Surface.stories.tsx
new file mode 100644
index 0000000..440ac1a
--- /dev/null
+++ b/m3-react/storybook/components/M3Surface.stories.tsx
@@ -0,0 +1,52 @@
+import type {
+  Meta,
+  StoryObj,
+} from '@storybook/react'
+
+import { M3Surface } from '@/components/surface'
+
+import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph'
+import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain'
+import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal'
+import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove'
+import SurfaceSideSheetModalToWindow from '../examples/surface/SurfaceSideSheetModalToWindow'
+import SurfaceSideSheetMorph from '../examples/surface/SurfaceSideSheetMorph'
+
+import '../examples/surface/styles.scss'
+
+const meta = {
+  title: 'Components/M3Surface',
+  component: M3Surface,
+
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof M3Surface>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const SideSheetDockedToModal: Story = {
+  render: () => <SurfaceSideSheetMorph />,
+}
+
+export const CardReplacingPage: Story = {
+  render: () => <SurfaceCardPageMorph />,
+}
+
+export const SideSheetModalDismissRemovesSurface: Story = {
+  render: () => <SurfaceSideSheetDismissToRemove />,
+}
+
+export const SideSheetAlwaysModalToggle: Story = {
+  render: () => <SurfaceSideSheetAlwaysModal />,
+}
+
+export const SideSheetModalToWindow: Story = {
+  render: () => <SurfaceSideSheetModalToWindow />,
+}
+
+export const NestedDialogsChain: Story = {
+  render: () => <SurfaceNestedDialogsChain />,
+}
diff --git a/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx b/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
new file mode 100644
index 0000000..76ba141
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
@@ -0,0 +1,379 @@
+import type {
+  CSSProperties,
+  FC,
+} from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import { toClassName } from '@/utils/styling'
+
+import {
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const TRANSITION_MS = m3MotionDurations.medium3
+const TRANSITION_EASING = m3MotionEasings.standard
+
+type NavTab = 'files' | 'timeline' | 'tasks' | 'analytics'
+
+type Motion = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+const SurfaceCardPageMorph: FC = () => {
+  const [expanded, setExpanded, expandedRef] = useStateRef(false)
+  const [busy, setBusy, busyRef] = useStateRef(false)
+  const [navExpanded, setNavExpanded] = useStateRef(false)
+  const [backgroundCollapsed, setBackgroundCollapsed] = useStateRef(false)
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('files')
+  const [originHeight, setOriginHeight] = useStateRef(220)
+
+  const [motion, setMotion] = useStateRef<Motion>({
+    top: 16,
+    left: 16,
+    width: 320,
+    height: 220,
+  })
+
+  const canvas = useRef<HTMLDivElement | null>(null)
+  const originSlot = useRef<HTMLDivElement | null>(null)
+
+  const overlayStyle: CSSProperties = {
+    top: `${motion.top}px`,
+    left: `${motion.left}px`,
+    width: `${motion.width}px`,
+    height: `${motion.height}px`,
+  }
+
+  const measureOrigin = (): Motion | null => {
+    if (!canvas.current || !originSlot.current) {
+      return null
+    }
+
+    const canvasRect = canvas.current.getBoundingClientRect()
+    const originRect = originSlot.current.getBoundingClientRect()
+
+    return {
+      top: originRect.top - canvasRect.top,
+      left: originRect.left - canvasRect.left,
+      width: originRect.width,
+      height: originRect.height,
+    }
+  }
+
+  const measureExpanded = (): Motion | null => {
+    if (!canvas.current) {
+      return null
+    }
+
+    const canvasRect = canvas.current.getBoundingClientRect()
+
+    return {
+      top: 0,
+      left: 0,
+      width: canvasRect.width,
+      height: canvasRect.height,
+    }
+  }
+
+  const initMotion = async () => {
+    await raf()
+
+    const origin = measureOrigin()
+    if (!origin) {
+      return
+    }
+
+    setMotion(origin)
+    setOriginHeight(origin.height)
+  }
+
+  const expandCard = async () => {
+    setBackgroundCollapsed(false)
+
+    const origin = measureOrigin()
+    if (origin) {
+      setMotion(origin)
+      setOriginHeight(origin.height)
+    }
+
+    setExpanded(true)
+    await raf()
+
+    const full = measureExpanded()
+    if (!full) {
+      return
+    }
+
+    setMotion(full)
+    await wait(TRANSITION_MS)
+    setBackgroundCollapsed(true)
+  }
+
+  const collapseCard = async () => {
+    if (backgroundCollapsed) {
+      setBackgroundCollapsed(false)
+      await raf()
+    }
+
+    const full = measureExpanded()
+    if (full) {
+      setMotion(full)
+    }
+
+    const origin = measureOrigin()
+    if (origin) {
+      setOriginHeight(origin.height)
+    }
+
+    setExpanded(false)
+    await raf()
+
+    if (!origin) {
+      return
+    }
+
+    setMotion(origin)
+    await wait(TRANSITION_MS)
+  }
+
+  const toggleCardMode = async () => {
+    if (busyRef.current) {
+      return
+    }
+
+    setBusy(true)
+
+    if (expandedRef.current) {
+      await collapseCard()
+      setBusy(false)
+      return
+    }
+
+    await expandCard()
+    setBusy(false)
+  }
+
+  useEffect(() => {
+    void initMotion()
+  }, [])
+
+  return (
+    <div
+      className="surface-card-page"
+      data-card-expanded={expanded ? 'true' : 'false'}
+      data-testid="surface-card-page-root"
+    >
+      <M3Surface
+        className="surface-card-page__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-card-page__topbar-content">
+          <div>
+            <strong>Surface orchestration: card replacing page</strong>
+            <p>The same surface morphs between compact card and page-like container.</p>
+          </div>
+
+          <M3Button
+            appearance="filled"
+            disabled={busy}
+            data-testid="surface-card-toggle"
+            onClick={() => void toggleCardMode()}
+          >
+            {expanded ? 'Return to card state' : 'Expand card to page state'}
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        expanded={navExpanded}
+        onToggle={setNavExpanded}
+        className="surface-card-page__nav"
+        appearance="auto"
+        alignment="top"
+      >
+        <M3Navigation.Top>
+          <M3IconButton
+            aria-label="Open navigation"
+            onClick={() => setNavExpanded(true)}
+          >
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3NavigationTab
+          label="Files"
+          active={activeNavTab === 'files'}
+          onNavigate={() => {
+            setActiveNavTab('files')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="folder" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Timeline"
+          active={activeNavTab === 'timeline'}
+          onNavigate={() => {
+            setActiveNavTab('timeline')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="schedule" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Tasks"
+          active={activeNavTab === 'tasks'}
+          onNavigate={() => {
+            setActiveNavTab('tasks')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="check_circle" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Analytics"
+          active={activeNavTab === 'analytics'}
+          onNavigate={() => {
+            setActiveNavTab('analytics')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="insights" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-card-page__body">
+        <div className="surface-card-page__workspace">
+          <M3Surface
+            className="surface-card-page__header-card"
+            fillHeight={false}
+            height={120}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Card-to-page transition playground</h3>
+            <p>Original slot remains reserved while the morphing surface overlays the page area.</p>
+          </M3Surface>
+
+          <div
+            ref={canvas}
+            className="surface-card-page__canvas"
+            data-testid="surface-card-canvas"
+          >
+            {!backgroundCollapsed ? (
+              <div
+                className="surface-card-page__grid"
+                data-testid="surface-card-grid"
+              >
+                <div
+                  ref={originSlot}
+                  className="surface-card-page__origin-slot"
+                  style={{ minHeight: `${originHeight}px` }}
+                  data-testid="surface-card-origin"
+                />
+
+                <M3Surface
+                  className="surface-card-page__grid-card"
+                  fillHeight={false}
+                  height={184}
+                  rounding={16}
+                  variant="surface-container-low"
+                  elevation={1}
+                >
+                  <strong>Static card A</strong>
+                  <p>Background content remains in flow.</p>
+                </M3Surface>
+
+                <M3Surface
+                  className="surface-card-page__grid-card"
+                  fillHeight={false}
+                  height={184}
+                  rounding={16}
+                  variant="surface-container"
+                  elevation={2}
+                >
+                  <strong>Static card B</strong>
+                  <p>Independent surface in the same scene.</p>
+                </M3Surface>
+              </div>
+            ) : null}
+
+            <div className="surface-card-page__overlay">
+              <div
+                className="surface-card-page__overlay-wrap"
+                style={overlayStyle}
+                data-testid="surface-card-overlay-wrap"
+              >
+                <M3Surface
+                  className={toClassName([
+                    'surface-card-page__morph-surface',
+                    expanded
+                      ? 'surface-card-page__morph-surface_expanded'
+                      : 'surface-card-page__morph-surface_compact',
+                  ])}
+                  fillWidth={true}
+                  fillHeight={true}
+                  rounding={expanded ? 0 : 24}
+                  transitionMs={TRANSITION_MS}
+                  transitionTiming={TRANSITION_EASING}
+                  variant={expanded ? 'surface' : 'surface-container-low'}
+                  elevation={expanded ? 0 : 1}
+                  overflow="auto"
+                  data-testid="surface-card-morph"
+                >
+                  <h3>Morph target surface</h3>
+                  <p>
+                    In compact mode this surface behaves like a card. In expanded mode it replaces the
+                    page work area while keeping top bar and rail reserved.
+                  </p>
+
+                  <M3Surface
+                    className="surface-card-page__morph-nested"
+                    fillHeight={false}
+                    height={120}
+                    rounding={14}
+                    variant={expanded ? 'surface-container-low' : 'surface-container-high'}
+                    elevation={expanded ? 1 : 3}
+                  >
+                    Nested surface demonstrates composability in both states.
+                  </M3Surface>
+                </M3Surface>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SurfaceCardPageMorph
diff --git a/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
new file mode 100644
index 0000000..a3f27a1
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
@@ -0,0 +1,359 @@
+import type {
+  CSSProperties,
+  FC,
+} from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+import { toClassName } from '@/utils/styling'
+
+import {
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const DIALOG_TRANSITION_MS = m3MotionDurations.medium2
+const DIALOG_TRANSITION_EASING = m3MotionEasings.standard
+const DIALOG_ENTRY_OFFSET_PX = 24
+const DIALOG_Z_INDEX_BASE = 560
+const DIALOG_Z_INDEX_STEP = 40
+
+type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
+
+type DialogSpec = {
+  id: string;
+  width: number;
+  rounding: number;
+  description: string;
+}
+
+const dialogChain: DialogSpec[] = [{
+  id: 'dialog-1',
+  width: 720,
+  rounding: 28,
+  description: 'First layer in the chain. It opens dialog 2.',
+}, {
+  id: 'dialog-2',
+  width: 620,
+  rounding: 26,
+  description: 'Second layer keeps the same controls and opens the next dialog.',
+}, {
+  id: 'dialog-3',
+  width: 520,
+  rounding: 24,
+  description: 'Third layer opens the final nested dialog.',
+}, {
+  id: 'dialog-4',
+  width: 440,
+  rounding: 22,
+  description: 'Final layer in this scenario: close only, no next dialog action.',
+}]
+
+const SurfaceNestedDialogsChain: FC = () => {
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
+  const [dialogMounted, setDialogMounted, dialogMountedRef] = useStateRef<boolean[]>(
+    Array.from({ length: dialogChain.length }, () => false)
+  )
+  const [dialogVisible, setDialogVisible] = useStateRef<boolean[]>(
+    Array.from({ length: dialogChain.length }, () => false)
+  )
+
+  const chainOpened = dialogMounted.some(Boolean)
+
+  const topDialogLevel = (() => {
+    for (let index = dialogChain.length - 1; index >= 0; index -= 1) {
+      if (dialogMounted[index]) {
+        return index
+      }
+    }
+
+    return -1
+  })()
+
+  const hasNextDialog = (level: number) => level < dialogChain.length - 1
+  const isTopDialog = (level: number) => topDialogLevel === level
+
+  const dialogMode = (level: number): 'standard' | 'modal' => {
+    return isTopDialog(level) ? 'modal' : 'standard'
+  }
+
+  const dialogZIndex = (level: number) => DIALOG_Z_INDEX_BASE + (level * DIALOG_Z_INDEX_STEP)
+
+  const dialogElevation = (level: number) => Math.min(5, 2 + level)
+
+  const dialogInlineStyle = (level: number): CSSProperties => {
+    const visible = dialogVisible[level]
+
+    return {
+      position: 'fixed',
+      top: '50%',
+      left: '50%',
+      zIndex: dialogZIndex(level),
+      opacity: visible ? 1 : 0,
+      transform: visible
+        ? 'translate(-50%, -50%)'
+        : `translate(-50%, calc(-50% + ${DIALOG_ENTRY_OFFSET_PX}px))`,
+      transition: `opacity ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_EASING}, transform ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_EASING}`,
+      pointerEvents: visible ? 'auto' : 'none',
+    }
+  }
+
+  const openDialog = async (level: number) => {
+    if (level < 0 || level >= dialogChain.length || dialogMountedRef.current[level]) {
+      return
+    }
+
+    if (level > 0 && !dialogMountedRef.current[level - 1]) {
+      return
+    }
+
+    setDialogMounted((previous) => {
+      const next = [...previous]
+      next[level] = true
+      return next
+    })
+
+    setDialogVisible((previous) => {
+      const next = [...previous]
+      next[level] = false
+      return next
+    })
+
+    await raf()
+
+    setDialogVisible((previous) => {
+      const next = [...previous]
+      next[level] = true
+      return next
+    })
+  }
+
+  const closeFrom = async (level: number) => {
+    if (level < 0 || level >= dialogChain.length) {
+      return
+    }
+
+    let hasMountedDialog = false
+    for (let index = level; index < dialogChain.length; index += 1) {
+      if (dialogMountedRef.current[index]) {
+        hasMountedDialog = true
+        break
+      }
+    }
+
+    if (!hasMountedDialog) {
+      return
+    }
+
+    setDialogVisible((previous) => {
+      const next = [...previous]
+
+      for (let index = dialogChain.length - 1; index >= level; index -= 1) {
+        if (dialogMountedRef.current[index]) {
+          next[index] = false
+        }
+      }
+
+      return next
+    })
+
+    await wait(DIALOG_TRANSITION_MS)
+
+    setDialogMounted((previous) => {
+      const next = [...previous]
+
+      for (let index = level; index < dialogChain.length; index += 1) {
+        next[index] = false
+      }
+
+      return next
+    })
+
+    setDialogVisible((previous) => {
+      const next = [...previous]
+
+      for (let index = level; index < dialogChain.length; index += 1) {
+        next[index] = false
+      }
+
+      return next
+    })
+  }
+
+  return (
+    <div
+      className="surface-dialog-chain"
+      data-top-level={String(topDialogLevel)}
+    >
+      <M3Surface
+        className="surface-dialog-chain__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-dialog-chain__topbar-content">
+          <div>
+            <strong>Surface orchestration: nested dialogs chain</strong>
+            <p>Rail layout opens a nested dialog chain with one active scrim on the topmost dialog.</p>
+          </div>
+
+          <M3Button
+            appearance="filled"
+            disabled={chainOpened}
+            data-testid="surface-dialog-chain-open-root"
+            onClick={() => void openDialog(0)}
+          >
+            {chainOpened ? 'Dialog chain is open' : 'Open dialog chain'}
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        className="surface-dialog-chain__nav"
+        appearance="rail"
+        alignment="top"
+      >
+        <M3NavigationTab
+          label="Inbox"
+          active={activeNavTab === 'inbox'}
+          onNavigate={() => setActiveNavTab('inbox')}
+        >
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Boards"
+          active={activeNavTab === 'boards'}
+          onNavigate={() => setActiveNavTab('boards')}
+        >
+          <M3Icon name="dashboard" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Archive"
+          active={activeNavTab === 'archive'}
+          onNavigate={() => setActiveNavTab('archive')}
+        >
+          <M3Icon name="archive" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Lab"
+          active={activeNavTab === 'lab'}
+          onNavigate={() => setActiveNavTab('lab')}
+        >
+          <M3Icon name="science" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-dialog-chain__body">
+        <div className="surface-dialog-chain__workspace">
+          <M3Surface
+            className="surface-dialog-chain__workspace-intro"
+            fillHeight={false}
+            height={124}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Workspace</h3>
+            <p>Page composition stays stable while dialogs are stacked progressively.</p>
+          </M3Surface>
+
+          <M3Surface
+            className="surface-dialog-chain__canvas"
+            rounding={20}
+            variant="surface-container-low"
+            elevation={0}
+          >
+            <h4>Background content</h4>
+            <p>Open dialog 1 from top action, then continue through the chain.</p>
+          </M3Surface>
+        </div>
+      </div>
+
+      {dialogChain.map((dialog, level) => {
+        if (!dialogMounted[level]) {
+          return null
+        }
+
+        return (
+          <M3Surface
+            key={dialog.id}
+            className={toClassName([
+              'surface-dialog-chain__dialog',
+              `surface-dialog-chain__dialog_level-${level + 1}`,
+            ])}
+            mode={dialogMode(level)}
+            shown={dialogMounted[level]}
+            anchor="center"
+            fillWidth={false}
+            fillHeight={false}
+            width={dialog.width}
+            insetTop={24}
+            insetBottom={24}
+            rounding={dialog.rounding}
+            transitionMs={DIALOG_TRANSITION_MS}
+            transitionTiming={DIALOG_TRANSITION_EASING}
+            zIndex={dialogZIndex(level)}
+            variant="surface-container-highest"
+            elevation={dialogElevation(level)}
+            overflow="visible"
+            style={dialogInlineStyle(level)}
+            data-testid={`surface-dialog-chain-level-${level + 1}`}
+            onDismiss={() => void closeFrom(level)}
+          >
+            <div className="surface-dialog-chain__dialog-head">
+              <h3>Dialog {level + 1} of {dialogChain.length}</h3>
+
+              <M3IconButton
+                appearance="standard"
+                aria-label={`Close dialog ${level + 1}`}
+                onClick={() => void closeFrom(level)}
+              >
+                <M3Icon name="close" />
+              </M3IconButton>
+            </div>
+
+            <p>{dialog.description}</p>
+
+            <div className="surface-dialog-chain__dialog-actions">
+              <M3Button
+                appearance="text"
+                data-testid={`surface-dialog-chain-close-${level + 1}`}
+                onClick={() => void closeFrom(level)}
+              >
+                Close
+              </M3Button>
+
+              {hasNextDialog(level) ? (
+                <M3Button
+                  appearance="filled"
+                  disabled={dialogMounted[level + 1]}
+                  data-testid={`surface-dialog-chain-open-next-${level + 1}`}
+                  onClick={() => void openDialog(level + 1)}
+                >
+                  Open dialog {level + 2}
+                </M3Button>
+              ) : null}
+            </div>
+          </M3Surface>
+        )
+      })}
+    </div>
+  )
+}
+
+export default SurfaceNestedDialogsChain
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
new file mode 100644
index 0000000..f997052
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
@@ -0,0 +1,347 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import {
+  clamp,
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
+
+type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
+
+const SurfaceSideSheetAlwaysModal: FC = () => {
+  const [navExpanded, setNavExpanded] = useStateRef(false)
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
+  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(320)
+  const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
+  const [modalElevation, setModalElevation] = useStateRef(0)
+  const [modalMounted, setModalMounted, modalMountedRef] = useStateRef(false)
+  const [modalVisible, setModalVisible] = useStateRef(false)
+  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
+
+  const layoutRoot = useRef<HTMLDivElement | null>(null)
+
+  const hiddenInsetRight = (width: number) => -(width + 12)
+
+  const resolveSheetWidthFromLayout = () => {
+    const layoutWidth = Math.round(layoutRoot.current?.getBoundingClientRect().width ?? window.innerWidth)
+    const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+    return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+  }
+
+  const syncFixedWidth = () => {
+    const width = resolveSheetWidthFromLayout()
+    setSideSheetWidth(width)
+
+    if (!modalMountedRef.current) {
+      setModalInsetRight(hiddenInsetRight(width))
+    }
+
+    return width
+  }
+
+  const openModal = async () => {
+    if (transitioningRef.current || modalMountedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    const width = syncFixedWidth()
+
+    setModalRadiusLeft(0)
+    setModalElevation(0)
+    setModalInsetRight(hiddenInsetRight(width))
+    setModalMounted(true)
+
+    await raf()
+
+    setModalVisible(true)
+    await raf()
+
+    setModalInsetRight(MODAL_INSET_END)
+    setModalRadiusLeft(28)
+    setModalElevation(1)
+    await wait(PANEL_TRANSITION_MS)
+    setTransitioning(false)
+  }
+
+  const closeModal = async () => {
+    if (transitioningRef.current || !modalMountedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
+    setModalRadiusLeft(0)
+    setModalElevation(0)
+    await wait(PANEL_TRANSITION_MS)
+
+    setModalVisible(false)
+    await wait(SCRIM_FADE_MS)
+    setModalMounted(false)
+    setTransitioning(false)
+  }
+
+  useEffect(() => {
+    const onResize = () => {
+      syncFixedWidth()
+    }
+
+    syncFixedWidth()
+    window.addEventListener('resize', onResize, { passive: true })
+
+    return () => {
+      window.removeEventListener('resize', onResize)
+    }
+  }, [])
+
+  return (
+    <div
+      className="surface-side-sheet"
+      data-modal-mounted={modalMounted ? 'true' : 'false'}
+      data-testid="surface-always-root"
+    >
+      <M3Surface
+        className="surface-side-sheet__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-side-sheet__topbar-content">
+          <div>
+            <strong>Surface orchestration: always-modal side sheet</strong>
+            <p>The side sheet exists only in modal mode and can be shown repeatedly from the page header.</p>
+          </div>
+
+          <M3Button
+            appearance="tonal"
+            disabled={transitioning || modalMounted}
+            data-testid="surface-always-open"
+            onClick={() => void openModal()}
+          >
+            {modalMounted ? 'Modal side sheet is open' : 'Show modal side sheet'}
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        expanded={navExpanded}
+        onToggle={setNavExpanded}
+        className="surface-side-sheet__nav"
+        appearance="auto"
+        alignment="top"
+      >
+        <M3Navigation.Top>
+          <M3IconButton
+            aria-label="Open navigation"
+            onClick={() => setNavExpanded(true)}
+          >
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3NavigationTab
+          label="Inbox"
+          active={activeNavTab === 'inbox'}
+          onNavigate={() => {
+            setActiveNavTab('inbox')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Boards"
+          active={activeNavTab === 'boards'}
+          onNavigate={() => {
+            setActiveNavTab('boards')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="dashboard" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Archive"
+          active={activeNavTab === 'archive'}
+          onNavigate={() => {
+            setActiveNavTab('archive')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="archive" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Lab"
+          active={activeNavTab === 'lab'}
+          onNavigate={() => {
+            setActiveNavTab('lab')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="science" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-side-sheet__body">
+        <div className="surface-side-sheet__workspace">
+          <M3Surface
+            className="surface-side-sheet__header-card"
+            fillHeight={false}
+            height={120}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Workspace surfaces</h3>
+            <p>Background layout stays in flow while the side sheet appears as a modal overlay.</p>
+          </M3Surface>
+
+          <div
+            ref={layoutRoot}
+            className="surface-side-sheet__layout"
+            data-testid="surface-always-layout"
+          >
+            <main
+              className="surface-side-sheet__content-grid"
+              data-testid="surface-always-content-grid"
+            >
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-lowest"
+                elevation={0}
+              >
+                <strong>surface-container-lowest</strong>
+                <p>Read-heavy content block in the page flow.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-low"
+                elevation={1}
+              >
+                <strong>surface-container-low</strong>
+                <p>Secondary block with mild emphasis.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-high"
+                elevation={3}
+              >
+                <strong>surface-container-high</strong>
+                <p>Contextual utility content.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-dim"
+                elevation={0}
+              >
+                <strong>surface-dim</strong>
+                <p>Low-brightness complementary content.</p>
+              </M3Surface>
+            </main>
+
+            {modalMounted ? (
+              <M3Surface
+                className="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                mode="modal"
+                shown={modalVisible}
+                anchor="end"
+                fillWidth={false}
+                fillHeight={false}
+                width={sideSheetWidth}
+                insetTop={MODAL_INSET_TOP}
+                insetRight={modalInsetRight}
+                insetBottom={MODAL_INSET_BOTTOM}
+                roundingTopLeft={modalRadiusLeft}
+                roundingBottomLeft={modalRadiusLeft}
+                roundingTopRight={0}
+                roundingBottomRight={0}
+                transitionMs={PANEL_TRANSITION_MS}
+                transitionTiming={PANEL_TRANSITION_EASING}
+                zIndex={520}
+                variant="surface-container-high"
+                elevation={modalElevation}
+                overflow="auto"
+                data-testid="surface-always-panel"
+                onDismiss={() => void closeModal()}
+              >
+                <div className="surface-side-sheet__modal-header">
+                  <h3>Modal side sheet</h3>
+
+                  <M3IconButton
+                    className="surface-side-sheet__modal-close"
+                    appearance="standard"
+                    aria-label="Close modal side sheet"
+                    disabled={transitioning}
+                    data-testid="surface-always-close"
+                    onClick={() => void closeModal()}
+                  >
+                    <M3Icon name="close" />
+                  </M3IconButton>
+                </div>
+
+                <p>This side sheet is always modal and never returns to a docked state.</p>
+                <p>Close actions: scrim click or close button inside the panel.</p>
+                <p className="surface-side-sheet__meta">
+                  Fixed width: {sideSheetWidth}px
+                </p>
+              </M3Surface>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SurfaceSideSheetAlwaysModal
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
new file mode 100644
index 0000000..ed84dba
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
@@ -0,0 +1,452 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import {
+  clamp,
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
+
+type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
+type ModalRole = 'surface-container-low' | 'surface-container-high'
+
+const SurfaceSideSheetDismissToRemove: FC = () => {
+  const [navExpanded, setNavExpanded] = useStateRef(false)
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
+  const [sideSheetModal, setSideSheetModal, sideSheetModalRef] = useStateRef(false)
+  const [sheetRemoved, setSheetRemoved, sheetRemovedRef] = useStateRef(false)
+  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(320)
+  const [sideSheetDockedWidth, setSideSheetDockedWidth] = useStateRef(sideSheetWidthRef.current)
+  const [modalShown, setModalShown] = useStateRef(false)
+  const [modalVisible, setModalVisible] = useStateRef(false)
+  const [modalWidth, setModalWidth] = useStateRef(sideSheetWidthRef.current)
+  const [modalInsetTop, setModalInsetTop] = useStateRef(MODAL_INSET_TOP)
+  const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
+  const [modalInsetBottom, setModalInsetBottom] = useStateRef(MODAL_INSET_BOTTOM)
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
+  const [modalElevation, setModalElevation] = useStateRef(0)
+  const [modalRole, setModalRole] = useStateRef<ModalRole>('surface-container-low')
+  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
+
+  const dockedHost = useRef<HTMLDivElement | null>(null)
+  const layoutRoot = useRef<HTMLDivElement | null>(null)
+
+  const hiddenInsetRight = (width: number) => -(width + 12)
+
+  const resolveSheetWidthFromLayout = () => {
+    const layoutWidth = Math.round(layoutRoot.current?.getBoundingClientRect().width ?? window.innerWidth)
+    const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+    return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+  }
+
+  const syncFixedWidth = () => {
+    const nextWidth = resolveSheetWidthFromLayout()
+
+    setSideSheetWidth(nextWidth)
+    setModalWidth(nextWidth)
+
+    if (sheetRemovedRef.current) {
+      setSideSheetDockedWidth(0)
+      setModalInsetRight(hiddenInsetRight(nextWidth))
+      return
+    }
+
+    if (!sideSheetModalRef.current) {
+      setSideSheetDockedWidth(nextWidth)
+      setModalInsetRight(hiddenInsetRight(nextWidth))
+    }
+  }
+
+  const measureDockedGeometry = () => {
+    const host = dockedHost.current
+    if (!host) {
+      return null
+    }
+
+    const rect = host.getBoundingClientRect()
+
+    return {
+      width: Math.round(rect.width),
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+  }
+
+  const setModalGeometryFromDocked = () => {
+    const docked = measureDockedGeometry()
+
+    setModalWidth(docked?.width ?? sideSheetWidthRef.current)
+    setModalInsetTop(docked?.insetTop ?? MODAL_INSET_TOP)
+    setModalInsetRight(docked?.insetRight ?? MODAL_INSET_END)
+    setModalInsetBottom(docked?.insetBottom ?? MODAL_INSET_BOTTOM)
+  }
+
+  const setModalGeometryTarget = () => {
+    setModalWidth(sideSheetWidthRef.current)
+    setModalInsetTop(MODAL_INSET_TOP)
+    setModalInsetRight(MODAL_INSET_END)
+    setModalInsetBottom(MODAL_INSET_BOTTOM)
+  }
+
+  const switchDockedToModal = async () => {
+    if (sheetRemovedRef.current) {
+      return
+    }
+
+    syncFixedWidth()
+    setModalGeometryFromDocked()
+
+    setModalRadiusLeft(0)
+    setModalElevation(0)
+    setModalRole('surface-container-low')
+    setModalVisible(false)
+    setModalShown(true)
+
+    await raf()
+
+    setModalVisible(true)
+    await raf()
+
+    setSideSheetModal(true)
+    setSideSheetDockedWidth(0)
+    setModalGeometryTarget()
+    setModalRadiusLeft(28)
+    setModalElevation(1)
+    setModalRole('surface-container-high')
+    await wait(PANEL_TRANSITION_MS)
+  }
+
+  const dismissModalAndRemove = async () => {
+    if (!sideSheetModalRef.current) {
+      return
+    }
+
+    setModalInsetTop(MODAL_INSET_TOP)
+    setModalInsetBottom(MODAL_INSET_BOTTOM)
+    setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
+    setModalElevation(0)
+    setModalRole('surface-container-low')
+    setModalRadiusLeft(0)
+    await wait(PANEL_TRANSITION_MS)
+
+    setModalVisible(false)
+    await wait(SCRIM_FADE_MS)
+    setModalShown(false)
+    setSideSheetModal(false)
+    setSideSheetDockedWidth(0)
+    setSheetRemoved(true)
+  }
+
+  const handleTopbarAction = async () => {
+    if (transitioningRef.current || sheetRemovedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+
+    if (!sideSheetModalRef.current) {
+      await switchDockedToModal()
+      setTransitioning(false)
+      return
+    }
+
+    await dismissModalAndRemove()
+    setTransitioning(false)
+  }
+
+  const closeModalFromPanel = async () => {
+    if (!sideSheetModalRef.current || transitioningRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    await dismissModalAndRemove()
+    setTransitioning(false)
+  }
+
+  useEffect(() => {
+    const onResize = () => {
+      syncFixedWidth()
+    }
+
+    syncFixedWidth()
+    window.addEventListener('resize', onResize, { passive: true })
+
+    return () => {
+      window.removeEventListener('resize', onResize)
+    }
+  }, [])
+
+  return (
+    <div className="surface-side-sheet">
+      <M3Surface
+        className="surface-side-sheet__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-side-sheet__topbar-content">
+          <div>
+            <strong>Surface orchestration: side sheet remove flow</strong>
+            <p>After modal close, the side sheet is removed from the page instead of returning to docked mode.</p>
+          </div>
+
+          <M3Button
+            appearance="tonal"
+            disabled={transitioning || sheetRemoved}
+            onClick={() => void handleTopbarAction()}
+          >
+            {
+              sheetRemoved
+                ? 'Side sheet removed'
+                : (sideSheetModal ? 'Close modal and remove sheet' : 'Switch to modal sheet')
+            }
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        expanded={navExpanded}
+        onToggle={setNavExpanded}
+        className="surface-side-sheet__nav"
+        appearance="auto"
+        alignment="top"
+      >
+        <M3Navigation.Top>
+          <M3IconButton
+            aria-label="Open navigation"
+            onClick={() => setNavExpanded(true)}
+          >
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3NavigationTab
+          label="Inbox"
+          active={activeNavTab === 'inbox'}
+          onNavigate={() => {
+            setActiveNavTab('inbox')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Boards"
+          active={activeNavTab === 'boards'}
+          onNavigate={() => {
+            setActiveNavTab('boards')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="dashboard" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Archive"
+          active={activeNavTab === 'archive'}
+          onNavigate={() => {
+            setActiveNavTab('archive')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="archive" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Lab"
+          active={activeNavTab === 'lab'}
+          onNavigate={() => {
+            setActiveNavTab('lab')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="science" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-side-sheet__body">
+        <div className="surface-side-sheet__workspace">
+          <M3Surface
+            className="surface-side-sheet__header-card"
+            fillHeight={false}
+            height={120}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Workspace surfaces</h3>
+            <p>Static blocks keep flow while side-sheet changes modality.</p>
+          </M3Surface>
+
+          <div
+            ref={layoutRoot}
+            className="surface-side-sheet__layout"
+          >
+            <main className="surface-side-sheet__content-grid">
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-lowest"
+                elevation={0}
+              >
+                <strong>surface-container-lowest</strong>
+                <p>Read-heavy content block in the page flow.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-low"
+                elevation={1}
+              >
+                <strong>surface-container-low</strong>
+                <p>Secondary block with mild emphasis.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-high"
+                elevation={3}
+              >
+                <strong>surface-container-high</strong>
+                <p>Contextual utility content.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-dim"
+                elevation={0}
+              >
+                <strong>surface-dim</strong>
+                <p>Low-brightness complementary content.</p>
+              </M3Surface>
+            </main>
+
+            {!sheetRemoved ? (
+              <div
+                ref={dockedHost}
+                className="surface-side-sheet__docked-host"
+                style={{ width: `${sideSheetDockedWidth}px` }}
+              >
+                {!sideSheetModal && !sheetRemoved ? (
+                  <M3Surface
+                    className="surface-side-sheet__sheet"
+                    fillWidth={true}
+                    fillHeight={true}
+                    rounding={0}
+                    variant="surface-container-low"
+                    elevation={0}
+                    overflow="auto"
+                  >
+                    <h3>Docked side sheet</h3>
+                    <p>Coplanar layout participant with fixed width per layout region.</p>
+                    <p>Main content remains interactive.</p>
+                    <p className="surface-side-sheet__meta">
+                      Fixed width: {sideSheetWidth}px
+                    </p>
+                  </M3Surface>
+                ) : null}
+              </div>
+            ) : null}
+
+            {modalShown ? (
+              <M3Surface
+                className="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                mode="modal"
+                shown={modalVisible}
+                anchor="end"
+                fillWidth={false}
+                fillHeight={false}
+                width={modalWidth}
+                insetTop={modalInsetTop}
+                insetRight={modalInsetRight}
+                insetBottom={modalInsetBottom}
+                roundingTopLeft={modalRadiusLeft}
+                roundingBottomLeft={modalRadiusLeft}
+                roundingTopRight={0}
+                roundingBottomRight={0}
+                transitionMs={PANEL_TRANSITION_MS}
+                transitionTiming={PANEL_TRANSITION_EASING}
+                zIndex={520}
+                variant={modalRole}
+                elevation={modalElevation}
+                overflow="auto"
+                onDismiss={() => void closeModalFromPanel()}
+              >
+                <div className="surface-side-sheet__modal-header">
+                  <h3>Modal side sheet</h3>
+
+                  {sideSheetModal ? (
+                    <M3IconButton
+                      className="surface-side-sheet__modal-close"
+                      appearance="standard"
+                      aria-label="Close modal side sheet"
+                      disabled={transitioning}
+                      onClick={() => void closeModalFromPanel()}
+                    >
+                      <M3Icon name="close" />
+                    </M3IconButton>
+                  ) : null}
+                </div>
+
+                <p>Layer rebind: docked layer to modal layer.</p>
+                <p>Anchored to end/right edge with full-height modal surface.</p>
+                <p>Closing this modal removes the side sheet from the scene.</p>
+                <p className="surface-side-sheet__meta">
+                  Fixed width: {modalWidth}px
+                </p>
+              </M3Surface>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SurfaceSideSheetDismissToRemove
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
new file mode 100644
index 0000000..7969c83
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
@@ -0,0 +1,609 @@
+import type {
+  CSSProperties,
+  FC,
+  FormEvent,
+} from 'react'
+import type { M3SelectOption } from '@/components/select'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Select } from '@/components/select'
+import { M3Surface } from '@/components/surface'
+import { M3TextField } from '@/components/text-field'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import { toClassName } from '@/utils/styling'
+
+import {
+  clamp,
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const WINDOW_WIDTH_MIN = 440
+const WINDOW_WIDTH_MAX = 920
+const WINDOW_WIDTH_RATIO = 0.72
+const WINDOW_WIDTH_STEP = 8
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium4
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
+const DIALOG_HIDE_MS = m3MotionDurations.long2
+
+type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
+type Priority = 'low' | 'normal' | 'high'
+
+type FormState = {
+  project: string;
+  ownerEmail: string;
+  startDate: string;
+  priority: Priority;
+  notes: string;
+}
+
+const DEFAULT_FORM: FormState = {
+  project: 'Q3 Design Refresh',
+  ownerEmail: 'owner@example.com',
+  startDate: '2026-03-01',
+  priority: 'normal',
+  notes: 'Move supplemental workflows into a reusable surface with predictable transitions.',
+}
+
+const priorityOptions: Array<M3SelectOption<Priority>> = [{
+  label: 'Low',
+  value: 'low',
+}, {
+  label: 'Normal',
+  value: 'normal',
+}, {
+  label: 'High',
+  value: 'high',
+}]
+
+const SurfaceSideSheetModalToWindow: FC = () => {
+  const [navExpanded, setNavExpanded] = useStateRef(false)
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
+  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(320)
+  const [windowWidth, setWindowWidth] = useStateRef(720)
+
+  const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
+  const [modalElevationBase, setModalElevationBase] = useStateRef(0)
+
+  const [modalMounted, setModalMounted, modalMountedRef] = useStateRef(false)
+  const [modalVisible, setModalVisible] = useStateRef(false)
+  const [panelAsWindow, setPanelAsWindow, panelAsWindowRef] = useStateRef(false)
+  const [windowClosing, setWindowClosing] = useStateRef(false)
+  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
+  const [form, setForm] = useStateRef<FormState>({ ...DEFAULT_FORM })
+
+  const layoutRoot = useRef<HTMLDivElement | null>(null)
+
+  const panelAnchor = panelAsWindow ? 'center' : 'end'
+  const panelWidth = panelAsWindow ? windowWidth : sideSheetWidth
+  const panelInsetRight = panelAsWindow ? 0 : modalInsetRight
+  const panelRoundingTopLeft = panelAsWindow ? 28 : modalRadiusLeft
+  const panelRoundingBottomLeft = panelAsWindow ? 28 : modalRadiusLeft
+  const panelRoundingTopRight = panelAsWindow ? 28 : 0
+  const panelRoundingBottomRight = panelAsWindow ? 28 : 0
+  const panelSurfaceRole = panelAsWindow ? 'surface-container-highest' : 'surface-container-high'
+  const panelElevation = panelAsWindow ? Math.max(2, modalElevationBase) : modalElevationBase
+  const panelTransitionMs = panelAsWindow && windowClosing
+    ? DIALOG_HIDE_MS
+    : PANEL_TRANSITION_MS
+  const panelTransitionTiming = PANEL_TRANSITION_EASING
+  const panelInlineStyle: CSSProperties = panelAsWindow && windowClosing
+    ? {
+      opacity: 0,
+      transform: 'translate(-50%, calc(-50% - 24px))',
+    }
+    : {}
+
+  const hiddenInsetRight = (width: number) => -(width + 12)
+
+  const resolveSheetWidthFromLayout = () => {
+    const layoutWidth = Math.round(layoutRoot.current?.getBoundingClientRect().width ?? window.innerWidth)
+    const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+    return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+  }
+
+  const resolveWindowWidth = () => {
+    const estimated = Math.round((window.innerWidth * WINDOW_WIDTH_RATIO) / WINDOW_WIDTH_STEP) * WINDOW_WIDTH_STEP
+
+    return clamp(estimated, WINDOW_WIDTH_MIN, WINDOW_WIDTH_MAX)
+  }
+
+  const syncDimensions = () => {
+    const nextSheetWidth = resolveSheetWidthFromLayout()
+    setSideSheetWidth(nextSheetWidth)
+    setWindowWidth(resolveWindowWidth())
+
+    if (!modalMountedRef.current) {
+      setModalInsetRight(hiddenInsetRight(nextSheetWidth))
+    }
+  }
+
+  const openModal = async () => {
+    if (transitioningRef.current || modalMountedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    setPanelAsWindow(false)
+    setWindowClosing(false)
+    syncDimensions()
+
+    setModalRadiusLeft(0)
+    setModalElevationBase(0)
+    setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
+    setModalMounted(true)
+
+    await raf()
+
+    setModalVisible(true)
+    await raf()
+
+    setModalInsetRight(MODAL_INSET_END)
+    setModalRadiusLeft(28)
+    setModalElevationBase(1)
+    await wait(PANEL_TRANSITION_MS)
+    setTransitioning(false)
+  }
+
+  const toggleWindowMode = async () => {
+    if (transitioningRef.current || !modalMountedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+
+    if (!panelAsWindowRef.current) {
+      setPanelAsWindow(true)
+      await wait(PANEL_TRANSITION_MS)
+      setTransitioning(false)
+      return
+    }
+
+    setPanelAsWindow(false)
+    await wait(PANEL_TRANSITION_MS)
+    setTransitioning(false)
+  }
+
+  const closeWindowModal = async () => {
+    setWindowClosing(true)
+    await wait(DIALOG_HIDE_MS)
+
+    setModalVisible(false)
+    await wait(SCRIM_FADE_MS)
+    setModalMounted(false)
+
+    setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
+    setModalRadiusLeft(0)
+    setModalElevationBase(0)
+    setWindowClosing(false)
+    setPanelAsWindow(false)
+  }
+
+  const closeSideSheetModal = async () => {
+    setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
+    setModalRadiusLeft(0)
+    setModalElevationBase(0)
+    await wait(PANEL_TRANSITION_MS)
+
+    setModalVisible(false)
+    await wait(SCRIM_FADE_MS)
+    setModalMounted(false)
+  }
+
+  const closeModal = async () => {
+    if (transitioningRef.current || !modalMountedRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+
+    if (panelAsWindowRef.current) {
+      await closeWindowModal()
+      setTransitioning(false)
+      return
+    }
+
+    await closeSideSheetModal()
+    setTransitioning(false)
+  }
+
+  const resetForm = () => {
+    setForm({ ...DEFAULT_FORM })
+  }
+
+  useEffect(() => {
+    const onResize = () => {
+      syncDimensions()
+    }
+
+    syncDimensions()
+    window.addEventListener('resize', onResize, { passive: true })
+
+    return () => {
+      window.removeEventListener('resize', onResize)
+    }
+  }, [])
+
+  return (
+    <div
+      className="surface-side-sheet-window"
+      data-panel-mode={panelAsWindow ? 'window' : 'sheet'}
+      data-panel-mounted={modalMounted ? 'true' : 'false'}
+      data-testid="surface-window-root"
+    >
+      <M3Surface
+        className="surface-side-sheet-window__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-side-sheet-window__topbar-content">
+          <div>
+            <strong>Surface orchestration: modal side sheet to window</strong>
+            <p>Use the action inside the panel to morph a modal side sheet into a modal window.</p>
+          </div>
+
+          <M3Button
+            appearance="tonal"
+            disabled={transitioning || modalMounted}
+            data-testid="surface-window-open"
+            onClick={() => void openModal()}
+          >
+            {modalMounted ? 'Modal panel is open' : 'Show modal side sheet'}
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        expanded={navExpanded}
+        onToggle={setNavExpanded}
+        className="surface-side-sheet-window__nav"
+        appearance="auto"
+        alignment="top"
+      >
+        <M3Navigation.Top>
+          <M3IconButton
+            aria-label="Open navigation"
+            onClick={() => setNavExpanded(true)}
+          >
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3NavigationTab
+          label="Inbox"
+          active={activeNavTab === 'inbox'}
+          onNavigate={() => {
+            setActiveNavTab('inbox')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Boards"
+          active={activeNavTab === 'boards'}
+          onNavigate={() => {
+            setActiveNavTab('boards')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="dashboard" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Archive"
+          active={activeNavTab === 'archive'}
+          onNavigate={() => {
+            setActiveNavTab('archive')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="archive" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Lab"
+          active={activeNavTab === 'lab'}
+          onNavigate={() => {
+            setActiveNavTab('lab')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="science" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-side-sheet-window__body">
+        <div className="surface-side-sheet-window__workspace">
+          <M3Surface
+            className="surface-side-sheet-window__header-card"
+            fillHeight={false}
+            height={120}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Workspace surfaces</h3>
+            <p>Background layout stays in flow while the modal panel morphs between side-sheet and window geometries.</p>
+          </M3Surface>
+
+          <div
+            ref={layoutRoot}
+            className="surface-side-sheet-window__layout"
+            data-testid="surface-window-layout"
+          >
+            <main
+              className="surface-side-sheet-window__content-grid"
+              data-testid="surface-window-content-grid"
+            >
+              <M3Surface
+                className="surface-side-sheet-window__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-lowest"
+                elevation={0}
+              >
+                <strong>surface-container-lowest</strong>
+                <p>Read-heavy content block in the page flow.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet-window__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-low"
+                elevation={1}
+              >
+                <strong>surface-container-low</strong>
+                <p>Secondary block with mild emphasis.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet-window__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-high"
+                elevation={3}
+              >
+                <strong>surface-container-high</strong>
+                <p>Contextual utility content.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet-window__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-dim"
+                elevation={0}
+              >
+                <strong>surface-dim</strong>
+                <p>Low-brightness complementary content.</p>
+              </M3Surface>
+            </main>
+
+            {modalMounted ? (
+              <M3Surface
+                className={toClassName([
+                  'surface-side-sheet-window__sheet',
+                  panelAsWindow
+                    ? 'surface-side-sheet-window__sheet_window'
+                    : 'surface-side-sheet-window__sheet_sheet',
+                ])}
+                mode="modal"
+                shown={modalVisible}
+                anchor={panelAnchor}
+                fillWidth={false}
+                fillHeight={false}
+                width={panelWidth}
+                insetTop={MODAL_INSET_TOP}
+                insetRight={panelInsetRight}
+                insetBottom={MODAL_INSET_BOTTOM}
+                roundingTopLeft={panelRoundingTopLeft}
+                roundingBottomLeft={panelRoundingBottomLeft}
+                roundingTopRight={panelRoundingTopRight}
+                roundingBottomRight={panelRoundingBottomRight}
+                transitionMs={panelTransitionMs}
+                transitionTiming={panelTransitionTiming}
+                zIndex={520}
+                variant={panelSurfaceRole}
+                elevation={panelElevation}
+                style={panelInlineStyle}
+                overflow="auto"
+                data-panel-mode={panelAsWindow ? 'window' : 'sheet'}
+                data-window-closing={windowClosing ? 'true' : 'false'}
+                data-testid="surface-window-panel"
+                onDismiss={() => void closeModal()}
+              >
+                <div
+                  className="surface-side-sheet-window__panel-content"
+                  data-testid="surface-window-panel-content"
+                >
+                  <div className="surface-side-sheet-window__modal-header">
+                    <h3>{panelAsWindow ? 'Window mode' : 'Modal side sheet'}</h3>
+
+                    <div className="surface-side-sheet-window__modal-actions">
+                      <M3IconButton
+                        className="surface-side-sheet-window__modal-action"
+                        appearance="standard"
+                        aria-label={panelAsWindow ? 'Dock panel to side sheet mode' : 'Open panel in window mode'}
+                        disabled={transitioning}
+                        data-testid="surface-window-toggle-mode"
+                        onClick={() => void toggleWindowMode()}
+                      >
+                        <M3Icon name={panelAsWindow ? 'close_fullscreen' : 'open_in_new'} />
+                      </M3IconButton>
+
+                      <M3IconButton
+                        className="surface-side-sheet-window__modal-action"
+                        appearance="standard"
+                        aria-label="Close modal panel"
+                        disabled={transitioning}
+                        data-testid="surface-window-close"
+                        onClick={() => void closeModal()}
+                      >
+                        <M3Icon name="close" />
+                      </M3IconButton>
+                    </div>
+                  </div>
+
+                  <p>Form layout adapts when switching from side-sheet to window mode.</p>
+
+                  <form
+                    className={toClassName([
+                      'surface-side-sheet-window__form',
+                      {
+                        'surface-side-sheet-window__form_window': panelAsWindow,
+                      },
+                    ])}
+                    onSubmit={(event: FormEvent<HTMLFormElement>) => event.preventDefault()}
+                  >
+                    <div className="surface-side-sheet-window__field">
+                      <M3TextField
+                        value={form.project}
+                        label="Project name"
+                        placeholder="Q3 Design Refresh"
+                        outlined
+                        onUpdate={(value) => {
+                          setForm((previous) => ({
+                            ...previous,
+                            project: value,
+                          }))
+                        }}
+                      />
+                    </div>
+
+                    <div className="surface-side-sheet-window__field">
+                      <M3TextField
+                        value={form.ownerEmail}
+                        type="email"
+                        label="Owner email"
+                        placeholder="owner@example.com"
+                        outlined
+                        onUpdate={(value) => {
+                          setForm((previous) => ({
+                            ...previous,
+                            ownerEmail: value,
+                          }))
+                        }}
+                      />
+                    </div>
+
+                    <div className="surface-side-sheet-window__field">
+                      <M3TextField
+                        value={form.startDate}
+                        label="Start date"
+                        placeholder="YYYY-MM-DD"
+                        outlined
+                        onUpdate={(value) => {
+                          setForm((previous) => ({
+                            ...previous,
+                            startDate: value,
+                          }))
+                        }}
+                      />
+                    </div>
+
+                    <div className="surface-side-sheet-window__field">
+                      <M3Select<Priority>
+                        value={form.priority}
+                        options={priorityOptions}
+                        label="Priority"
+                        outlined
+                        onUpdate={(value) => {
+                          setForm((previous) => ({
+                            ...previous,
+                            priority: value,
+                          }))
+                        }}
+                      />
+                    </div>
+
+                    <div
+                      className={toClassName([
+                        'surface-side-sheet-window__field',
+                        {
+                          'surface-side-sheet-window__field_wide': panelAsWindow,
+                        },
+                      ])}
+                    >
+                      <M3TextField
+                        value={form.notes}
+                        multiline
+                        label="Notes"
+                        placeholder="Describe constraints, risks, and acceptance criteria."
+                        outlined
+                        onUpdate={(value) => {
+                          setForm((previous) => ({
+                            ...previous,
+                            notes: value,
+                          }))
+                        }}
+                      />
+                    </div>
+
+                    <div
+                      className={toClassName([
+                        'surface-side-sheet-window__form-actions',
+                        {
+                          'surface-side-sheet-window__form-actions_window': panelAsWindow,
+                        },
+                      ])}
+                    >
+                      <M3Button
+                        appearance="text"
+                        type="button"
+                        onClick={resetForm}
+                      >
+                        Reset
+                      </M3Button>
+                      <M3Button appearance="filled" type="button">
+                        Save
+                      </M3Button>
+                    </div>
+                  </form>
+                </div>
+              </M3Surface>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SurfaceSideSheetModalToWindow
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
new file mode 100644
index 0000000..a8e72ea
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
@@ -0,0 +1,487 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import {
+  M3Navigation,
+  M3NavigationTab,
+} from '@/components/navigation'
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import {
+  clamp,
+  raf,
+  useStateRef,
+  wait,
+} from './utils'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 0.32
+const SIDE_SHEET_WIDTH_STEP = 4
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_VERTICAL_EXPAND_MS = 120
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+
+type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
+type ModalRole = 'surface-container-low' | 'surface-container-high'
+
+const SurfaceSideSheetMorph: FC = () => {
+  const [navExpanded, setNavExpanded] = useStateRef(false)
+  const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
+  const [sideSheetModal, setSideSheetModal, sideSheetModalRef] = useStateRef(false)
+  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(320)
+  const [sideSheetDockedWidth, setSideSheetDockedWidth] = useStateRef(sideSheetWidthRef.current)
+  const [modalShown, setModalShown] = useStateRef(false)
+  const [modalVisible, setModalVisible] = useStateRef(false)
+  const [modalWidth, setModalWidth, modalWidthRef] = useStateRef(sideSheetWidthRef.current)
+  const [modalInsetTop, setModalInsetTop] = useStateRef(MODAL_INSET_TOP)
+  const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
+  const [modalInsetBottom, setModalInsetBottom] = useStateRef(MODAL_INSET_BOTTOM)
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
+  const [modalElevation, setModalElevation] = useStateRef(0)
+  const [modalRole, setModalRole] = useStateRef<ModalRole>('surface-container-low')
+  const [modalTransitionMs, setModalTransitionMs] = useStateRef(PANEL_TRANSITION_MS)
+  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
+
+  const dockedHost = useRef<HTMLDivElement | null>(null)
+  const layoutRoot = useRef<HTMLDivElement | null>(null)
+
+  const hiddenInsetRight = (width: number) => -(width + 12)
+
+  const resolveSheetWidthFromLayout = () => {
+    const layoutWidth = Math.round(layoutRoot.current?.getBoundingClientRect().width ?? window.innerWidth)
+    const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
+
+    return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
+  }
+
+  const syncFixedWidth = () => {
+    const nextWidth = resolveSheetWidthFromLayout()
+
+    setSideSheetWidth(nextWidth)
+    setModalWidth(nextWidth)
+
+    if (!sideSheetModalRef.current) {
+      setSideSheetDockedWidth(nextWidth)
+      setModalInsetRight(hiddenInsetRight(nextWidth))
+    }
+
+    return nextWidth
+  }
+
+  const measureDockedGeometry = () => {
+    const host = dockedHost.current
+    if (!host) {
+      return null
+    }
+
+    const rect = host.getBoundingClientRect()
+
+    return {
+      width: Math.round(rect.width),
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+  }
+
+  const setModalGeometryFromDocked = (fallbackWidth: number) => {
+    const docked = measureDockedGeometry()
+
+    setModalWidth(docked?.width ?? fallbackWidth)
+    setModalInsetTop(docked?.insetTop ?? MODAL_INSET_TOP)
+    setModalInsetRight(docked?.insetRight ?? MODAL_INSET_END)
+    setModalInsetBottom(docked?.insetBottom ?? MODAL_INSET_BOTTOM)
+  }
+
+  const setModalGeometryTarget = (width: number) => {
+    setModalWidth(width)
+    setModalInsetTop(MODAL_INSET_TOP)
+    setModalInsetRight(MODAL_INSET_END)
+    setModalInsetBottom(MODAL_INSET_BOTTOM)
+  }
+
+  const expandModalToViewportHeight = async (width: number) => {
+    setModalTransitionMs(PANEL_VERTICAL_EXPAND_MS)
+    await raf()
+    setModalGeometryTarget(width)
+    await wait(PANEL_VERTICAL_EXPAND_MS)
+    setModalTransitionMs(PANEL_TRANSITION_MS)
+  }
+
+  const resolveDockedTargetGeometry = (width: number) => {
+    const layout = layoutRoot.current?.getBoundingClientRect()
+
+    if (!layout) {
+      return {
+        width,
+        insetTop: MODAL_INSET_TOP,
+        insetRight: MODAL_INSET_END,
+        insetBottom: MODAL_INSET_BOTTOM,
+      }
+    }
+
+    return {
+      width,
+      insetTop: Math.round(layout.top),
+      insetRight: Math.round(window.innerWidth - layout.right),
+      insetBottom: Math.round(window.innerHeight - layout.bottom),
+    }
+  }
+
+  const switchDockedToModal = async () => {
+    const nextWidth = syncFixedWidth()
+    setModalGeometryFromDocked(nextWidth)
+
+    setModalTransitionMs(PANEL_TRANSITION_MS)
+    setModalRadiusLeft(0)
+    setModalElevation(0)
+    setModalRole('surface-container-low')
+    setModalVisible(false)
+    setModalShown(true)
+
+    await raf()
+
+    setModalVisible(true)
+    await raf()
+
+    setSideSheetModal(true)
+    setSideSheetDockedWidth(0)
+    setModalWidth(nextWidth)
+    setModalInsetRight(MODAL_INSET_END)
+    setModalRadiusLeft(28)
+    setModalElevation(1)
+    setModalRole('surface-container-high')
+    await wait(PANEL_TRANSITION_MS)
+
+    await expandModalToViewportHeight(nextWidth)
+  }
+
+  const switchModalToDocked = async () => {
+    const nextWidth = syncFixedWidth()
+    const dockedTarget = resolveDockedTargetGeometry(nextWidth)
+
+    setModalTransitionMs(PANEL_TRANSITION_MS)
+    setModalElevation(0)
+    setModalRole('surface-container-low')
+    setModalRadiusLeft(0)
+
+    setSideSheetDockedWidth(nextWidth)
+    setModalWidth(dockedTarget.width)
+    setModalInsetTop(dockedTarget.insetTop)
+    setModalInsetRight(dockedTarget.insetRight)
+    setModalInsetBottom(dockedTarget.insetBottom)
+
+    await wait(PANEL_TRANSITION_MS)
+
+    setSideSheetModal(false)
+    setModalVisible(false)
+    setModalShown(false)
+
+    setModalInsetTop(MODAL_INSET_TOP)
+    setModalInsetRight(hiddenInsetRight(nextWidth))
+    setModalInsetBottom(MODAL_INSET_BOTTOM)
+  }
+
+  const toggleSideSheetMode = async () => {
+    if (transitioningRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+
+    if (!sideSheetModalRef.current) {
+      await switchDockedToModal()
+      setTransitioning(false)
+      return
+    }
+
+    await switchModalToDocked()
+    setTransitioning(false)
+  }
+
+  const closeModalFromPanel = async () => {
+    if (!sideSheetModalRef.current || transitioningRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    await switchModalToDocked()
+    setTransitioning(false)
+  }
+
+  useEffect(() => {
+    const onResize = () => {
+      syncFixedWidth()
+    }
+
+    syncFixedWidth()
+    window.addEventListener('resize', onResize, { passive: true })
+
+    return () => {
+      window.removeEventListener('resize', onResize)
+    }
+  }, [])
+
+  return (
+    <div
+      className="surface-side-sheet"
+      data-sheet-modal={sideSheetModal ? 'true' : 'false'}
+      data-testid="surface-morph-root"
+    >
+      <M3Surface
+        className="surface-side-sheet__topbar"
+        fillHeight={false}
+        height={72}
+        variant="surface-container"
+        elevation={0}
+      >
+        <div className="surface-side-sheet__topbar-content">
+          <div>
+            <strong>Surface orchestration: side sheet morph</strong>
+            <p>Docked sheet transitions into modal sheet with fixed width, right-edge anchoring, and full-height modal target.</p>
+          </div>
+
+          <M3Button
+            appearance="tonal"
+            disabled={transitioning}
+            data-testid="surface-morph-toggle"
+            onClick={() => void toggleSideSheetMode()}
+          >
+            {sideSheetModal ? 'Switch to docked sheet' : 'Switch to modal sheet'}
+          </M3Button>
+        </div>
+      </M3Surface>
+
+      <M3Navigation
+        expanded={navExpanded}
+        onToggle={setNavExpanded}
+        className="surface-side-sheet__nav"
+        appearance="auto"
+        alignment="top"
+      >
+        <M3Navigation.Top>
+          <M3IconButton
+            aria-label="Open navigation"
+            onClick={() => setNavExpanded(true)}
+          >
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3NavigationTab
+          label="Inbox"
+          active={activeNavTab === 'inbox'}
+          onNavigate={() => {
+            setActiveNavTab('inbox')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Boards"
+          active={activeNavTab === 'boards'}
+          onNavigate={() => {
+            setActiveNavTab('boards')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="dashboard" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Archive"
+          active={activeNavTab === 'archive'}
+          onNavigate={() => {
+            setActiveNavTab('archive')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="archive" />
+        </M3NavigationTab>
+
+        <M3NavigationTab
+          label="Lab"
+          active={activeNavTab === 'lab'}
+          onNavigate={() => {
+            setActiveNavTab('lab')
+            setNavExpanded(false)
+          }}
+        >
+          <M3Icon name="science" />
+        </M3NavigationTab>
+      </M3Navigation>
+
+      <div className="surface-side-sheet__body">
+        <div className="surface-side-sheet__workspace">
+          <M3Surface
+            className="surface-side-sheet__header-card"
+            fillHeight={false}
+            height={120}
+            rounding={20}
+            variant="surface-container-lowest"
+            elevation={0}
+          >
+            <h3>Workspace surfaces</h3>
+            <p>Static blocks keep flow while side-sheet changes modality.</p>
+          </M3Surface>
+
+          <div
+            ref={layoutRoot}
+            className="surface-side-sheet__layout"
+            data-testid="surface-morph-layout"
+          >
+            <main
+              className="surface-side-sheet__content-grid"
+              data-testid="surface-morph-content-grid"
+            >
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-lowest"
+                elevation={0}
+              >
+                <strong>surface-container-lowest</strong>
+                <p>Read-heavy content block in the page flow.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-low"
+                elevation={1}
+              >
+                <strong>surface-container-low</strong>
+                <p>Secondary block with mild emphasis.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-container-high"
+                elevation={3}
+              >
+                <strong>surface-container-high</strong>
+                <p>Contextual utility content.</p>
+              </M3Surface>
+
+              <M3Surface
+                className="surface-side-sheet__grid-surface"
+                fillHeight={false}
+                height={136}
+                rounding={18}
+                variant="surface-dim"
+                elevation={0}
+              >
+                <strong>surface-dim</strong>
+                <p>Low-brightness complementary content.</p>
+              </M3Surface>
+            </main>
+
+            <div
+              ref={dockedHost}
+              className="surface-side-sheet__docked-host"
+              style={{ width: `${sideSheetDockedWidth}px` }}
+              data-testid="surface-morph-docked-host"
+            >
+              {!sideSheetModal ? (
+                <M3Surface
+                  className="surface-side-sheet__sheet"
+                  fillWidth={true}
+                  fillHeight={true}
+                  rounding={0}
+                  variant="surface-container-low"
+                  elevation={0}
+                  overflow="auto"
+                  data-testid="surface-morph-docked-sheet"
+                >
+                  <h3>Docked side sheet</h3>
+                  <p>Coplanar layout participant with fixed width per layout region.</p>
+                  <p>Main content remains interactive.</p>
+                  <p className="surface-side-sheet__meta">
+                    Fixed width: {sideSheetWidth}px
+                  </p>
+                </M3Surface>
+              ) : null}
+            </div>
+
+            {modalShown ? (
+              <M3Surface
+                className="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
+                mode="modal"
+                shown={modalVisible}
+                anchor="end"
+                fillWidth={false}
+                fillHeight={false}
+                width={modalWidth}
+                insetTop={modalInsetTop}
+                insetRight={modalInsetRight}
+                insetBottom={modalInsetBottom}
+                roundingTopLeft={modalRadiusLeft}
+                roundingBottomLeft={modalRadiusLeft}
+                roundingTopRight={0}
+                roundingBottomRight={0}
+                transitionMs={modalTransitionMs}
+                transitionTiming={PANEL_TRANSITION_EASING}
+                zIndex={520}
+                variant={modalRole}
+                elevation={modalElevation}
+                overflow="auto"
+                data-testid="surface-morph-modal-sheet"
+                onDismiss={() => void closeModalFromPanel()}
+              >
+                <div className="surface-side-sheet__modal-header">
+                  <h3>Modal side sheet</h3>
+
+                  {sideSheetModal ? (
+                    <M3IconButton
+                      className="surface-side-sheet__modal-close"
+                      appearance="standard"
+                      aria-label="Close modal side sheet"
+                      disabled={transitioning}
+                      data-testid="surface-morph-close"
+                      onClick={() => void closeModalFromPanel()}
+                    >
+                      <M3Icon name="close" />
+                    </M3IconButton>
+                  ) : null}
+                </div>
+
+                <p>Layer rebind: docked layer to modal layer.</p>
+                <p>Anchored to end/right edge with full-height modal surface.</p>
+                <p className="surface-side-sheet__meta">
+                  Fixed width: {modalWidth}px
+                </p>
+              </M3Surface>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default SurfaceSideSheetMorph
diff --git a/m3-react/storybook/examples/surface/styles.scss b/m3-react/storybook/examples/surface/styles.scss
new file mode 100644
index 0000000..9712ca0
--- /dev/null
+++ b/m3-react/storybook/examples/surface/styles.scss
@@ -0,0 +1,628 @@
+@use '@modulify/m3-foundation/assets/stylesheets/basics/motion' as m3-motion;
+
+.surface-card-page {
+  --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+  --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  --surface-accent-a: rgba(103, 80, 164, 0.14);
+  --surface-accent-b: rgba(96, 125, 139, 0.16);
+  --surface-border: var(--m3-sys-outline-variant, rgba(73, 69, 79, 0.2));
+  --surface-shadow: var(--m3-elevation-1, 0 2px 6px rgba(0, 0, 0, 0.14));
+  --surface-canvas-bg: var(--m3-sys-surface-container-low, var(--m3-sys-surface, #fef7ff));
+  --surface-origin-slot: color-mix(in srgb, var(--m3-sys-primary, #6750a4) 12%, transparent);
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 14% 4%, var(--surface-accent-a), transparent 38%),
+    radial-gradient(circle at 90% 8%, var(--surface-accent-b), transparent 38%),
+    linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+  color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+html.m3-theme-dark .surface-card-page {
+  --surface-accent-a: rgba(208, 188, 255, 0.18);
+  --surface-accent-b: rgba(128, 203, 196, 0.16);
+}
+
+.surface-card-page__topbar-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.surface-card-page__topbar-content strong {
+  display: block;
+  font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__topbar-content p {
+  margin: 4px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+  opacity: 0.8;
+}
+
+.surface-card-page__body {
+  display: flex;
+  height: calc(100vh - 72px);
+  padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+  .surface-card-page__body {
+    padding-left: var(--m3-navigation-drawer-width, 360px);
+  }
+}
+
+.surface-card-page__nav.m3-navigation {
+  top: 72px;
+  height: calc(100vh - 72px);
+}
+
+.surface-card-page__workspace {
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.surface-card-page__topbar {
+  padding: 16px;
+}
+
+.surface-card-page__header-card {
+  padding: 18px;
+}
+
+.surface-card-page__header-card h3 {
+  margin: 0 0 8px;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__header-card p {
+  margin: 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__canvas {
+  flex: 1 1 auto;
+  position: relative;
+  min-height: 0;
+  border-radius: 20px;
+  overflow: hidden;
+  background: var(--surface-canvas-bg);
+  box-shadow: 0 14px 28px var(--surface-shadow);
+}
+
+.surface-card-page__grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  padding: 14px;
+}
+
+.surface-card-page__grid > .surface-card-page__grid-card {
+  padding: 16px;
+}
+
+.surface-card-page__grid p {
+  margin: 6px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__origin-slot {
+  border-radius: 24px;
+  border: 1px dashed var(--surface-border);
+  background: var(--surface-origin-slot);
+}
+
+.surface-card-page__overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.surface-card-page__overlay-wrap {
+  position: absolute;
+  transition:
+    top #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+    left #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+    width #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+    height #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')};
+}
+
+.surface-card-page__morph-surface {
+  pointer-events: auto;
+}
+
+.surface-card-page__morph-surface_compact {
+  padding: 20px;
+}
+
+.surface-card-page__morph-surface_expanded {
+  padding: 28px;
+}
+
+.surface-card-page__morph-nested {
+  padding: 14px;
+}
+
+.surface-card-page__morph-surface h3 {
+  margin: 0 0 8px;
+  font: 700 18px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-card-page__morph-surface p {
+  margin: 0 0 12px;
+  font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+  max-width: 70ch;
+}
+
+.surface-dialog-chain {
+  --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+  --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+  --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+  --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+    radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+    linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+  color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-dialog-chain__topbar-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.surface-dialog-chain__topbar-content strong {
+  display: block;
+  font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__topbar-content p {
+  margin: 4px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+  opacity: 0.82;
+}
+
+.surface-dialog-chain__body {
+  display: flex;
+  height: calc(100vh - 72px);
+  padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+.surface-dialog-chain__nav.m3-navigation {
+  top: 72px;
+  height: calc(100vh - 72px);
+}
+
+.surface-dialog-chain__workspace {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.surface-dialog-chain__topbar {
+  padding: 16px;
+}
+
+.surface-dialog-chain__workspace-intro {
+  padding: 20px;
+}
+
+.surface-dialog-chain__workspace h3,
+.surface-dialog-chain__workspace h4 {
+  margin: 0 0 8px;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__workspace p {
+  margin: 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__canvas {
+  flex: 1 1 auto;
+  min-height: 220px;
+  padding: 18px;
+  background: var(--surface-layout-bg);
+}
+
+.surface-dialog-chain__dialog {
+  overflow: visible;
+}
+
+.surface-dialog-chain__dialog_level-1 {
+  padding: 24px;
+}
+
+.surface-dialog-chain__dialog_level-2 {
+  padding: 22px;
+}
+
+.surface-dialog-chain__dialog_level-3 {
+  padding: 20px;
+}
+
+.surface-dialog-chain__dialog_level-4 {
+  padding: 18px;
+}
+
+.surface-dialog-chain__dialog-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.surface-dialog-chain__dialog-head h3 {
+  margin: 0;
+  font: 700 18px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__dialog p {
+  margin: 8px 0 0;
+  font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-dialog-chain__dialog-actions {
+  margin-top: 14px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.surface-side-sheet {
+  --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+  --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+  --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+  --surface-border: var(--m3-sys-outline-variant, var(--md-sys-color-outline-variant, rgba(73, 69, 79, 0.2)));
+  --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+  --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+  --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  --surface-panel-transition-ms: #{m3-motion.duration('medium2')};
+  --surface-panel-transition-easing: #{m3-motion.easing('standard')};
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+    radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+    linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+  color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet__topbar-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.surface-side-sheet__topbar-content strong {
+  display: block;
+  font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__topbar-content p {
+  margin: 4px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+  opacity: 0.82;
+}
+
+.surface-side-sheet__body {
+  display: flex;
+  height: calc(100vh - 72px);
+  padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+  .surface-side-sheet__body {
+    padding-left: var(--m3-navigation-drawer-width, 360px);
+  }
+}
+
+.surface-side-sheet__nav.m3-navigation {
+  top: 72px;
+  height: calc(100vh - 72px);
+}
+
+.surface-side-sheet__workspace {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.surface-side-sheet__topbar {
+  padding: 16px;
+}
+
+.surface-side-sheet__header-card {
+  padding: 18px;
+}
+
+.surface-side-sheet__header-card h3 {
+  margin: 0 0 8px;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__header-card p {
+  margin: 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__layout {
+  min-height: 440px;
+  display: flex;
+  overflow: hidden;
+  border-radius: 20px;
+  background: var(--surface-layout-bg);
+  box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet__content-grid {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-auto-rows: min-content;
+  gap: 12px;
+  padding: 14px;
+  align-content: flex-start;
+  align-items: start;
+  background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet__content-grid > .surface-side-sheet__grid-surface {
+  padding: 18px;
+}
+
+.surface-side-sheet__content-grid p {
+  margin: 6px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__docked-host {
+  flex: 0 0 auto;
+  min-width: 0;
+  overflow: hidden;
+  border-left: 1px solid var(--surface-border);
+  transition: width var(--surface-panel-transition-ms) var(--surface-panel-transition-easing);
+}
+
+.surface-side-sheet__sheet h3 {
+  margin: 0 0 8px;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__sheet {
+  padding: 20px;
+}
+
+.surface-side-sheet__sheet_modal {
+  padding: 24px;
+}
+
+.surface-side-sheet__modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.surface-side-sheet__modal-close {
+  flex: 0 0 auto;
+}
+
+.surface-side-sheet__sheet p {
+  margin: 0 0 8px;
+  font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet__sheet .surface-side-sheet__meta {
+  margin-top: 14px;
+  font: 600 11px/1.2 'Trebuchet MS', 'Segoe UI', sans-serif;
+  letter-spacing: 0.04em;
+  opacity: 0.76;
+  text-transform: uppercase;
+}
+
+.surface-side-sheet-window {
+  --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
+  --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  --surface-accent-a: color-mix(in srgb, var(--m3-sys-primary, var(--md-sys-color-primary, #6750a4)) 18%, transparent);
+  --surface-accent-b: color-mix(in srgb, var(--m3-sys-secondary, var(--md-sys-color-secondary, #625b71)) 16%, transparent);
+  --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
+  --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
+  --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
+    radial-gradient(circle at 92% 0%, var(--surface-accent-b), transparent 44%),
+    linear-gradient(180deg, var(--surface-scene-bg-0) 0%, var(--surface-scene-bg-1) 100%);
+  color: var(--m3-sys-on-surface, var(--md-sys-color-on-surface, #1d1b20));
+}
+
+.surface-side-sheet-window__topbar-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.surface-side-sheet-window__topbar-content strong {
+  display: block;
+  font: 700 15px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__topbar-content p {
+  margin: 4px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+  opacity: 0.82;
+}
+
+.surface-side-sheet-window__body {
+  display: flex;
+  height: calc(100vh - 72px);
+  padding-left: var(--m3-navigation-rail-width, 80px);
+}
+
+@media (min-width: 1200px) {
+  .surface-side-sheet-window__body {
+    padding-left: var(--m3-navigation-drawer-width, 360px);
+  }
+}
+
+.surface-side-sheet-window__nav.m3-navigation {
+  top: 72px;
+  height: calc(100vh - 72px);
+}
+
+.surface-side-sheet-window__workspace {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.surface-side-sheet-window__topbar {
+  padding: 16px;
+}
+
+.surface-side-sheet-window__header-card {
+  padding: 18px;
+}
+
+.surface-side-sheet-window__header-card h3 {
+  margin: 0 0 8px;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__header-card p {
+  margin: 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__layout {
+  min-height: 440px;
+  display: flex;
+  overflow: hidden;
+  border-radius: 20px;
+  background: var(--surface-layout-bg);
+  box-shadow: 0 14px 28px var(--surface-shadow-color);
+}
+
+.surface-side-sheet-window__content-grid {
+  flex: 1 1 auto;
+  min-width: 0;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-auto-rows: min-content;
+  gap: 12px;
+  padding: 14px;
+  align-content: flex-start;
+  align-items: start;
+  background: var(--surface-grid-bg);
+}
+
+.surface-side-sheet-window__content-grid > .surface-side-sheet-window__grid-surface {
+  padding: 18px;
+}
+
+.surface-side-sheet-window__content-grid p {
+  margin: 6px 0 0;
+  font: 400 12px/1.35 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.surface-side-sheet-window__sheet_sheet {
+  padding: 24px;
+}
+
+.surface-side-sheet-window__sheet_window {
+  padding: 20px;
+}
+
+.surface-side-sheet-window__modal-header h3 {
+  margin: 0;
+  font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__modal-actions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.surface-side-sheet-window__modal-action {
+  flex: 0 0 auto;
+}
+
+.surface-side-sheet-window__sheet p {
+  margin: 8px 0 0;
+  font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
+}
+
+.surface-side-sheet-window__panel-content {
+  min-height: 0;
+}
+
+.surface-side-sheet-window__form {
+  margin-top: 14px;
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 12px;
+}
+
+.surface-side-sheet-window__form_window {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.surface-side-sheet-window__field {
+  display: grid;
+  gap: 6px;
+}
+
+.surface-side-sheet-window__field_wide {
+  grid-column: 1 / -1;
+}
+
+.surface-side-sheet-window__field .m3-text-field,
+.surface-side-sheet-window__field .m3-select {
+  width: 100%;
+}
+
+.surface-side-sheet-window__field_wide .m3-text-field textarea {
+  min-height: 120px;
+}
+
+.surface-side-sheet-window__form-actions {
+  display: flex;
+  gap: 10px;
+  justify-content: flex-start;
+}
+
+.surface-side-sheet-window__form-actions_window {
+  grid-column: 1 / -1;
+  justify-content: flex-end;
+}
diff --git a/m3-react/storybook/examples/surface/utils.ts b/m3-react/storybook/examples/surface/utils.ts
new file mode 100644
index 0000000..3cb24ad
--- /dev/null
+++ b/m3-react/storybook/examples/surface/utils.ts
@@ -0,0 +1,51 @@
+import {
+  useRef,
+  useState,
+} from 'react'
+
+import type {
+  MutableRefObject,
+  SetStateAction,
+} from 'react'
+
+export function wait (ms: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+export function raf (): Promise<void> {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+export function clamp (value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+export function useLatest<T> (value: T): MutableRefObject<T> {
+  const ref = useRef(value)
+  ref.current = value
+  return ref
+}
+
+export function useStateRef<T> (
+  initial: T
+): [T, (next: SetStateAction<T>) => void, MutableRefObject<T>] {
+  const [state, setState] = useState<T>(initial)
+  const ref = useRef(state)
+
+  const set = (next: SetStateAction<T>) => {
+    setState((prev) => {
+      const resolved = typeof next === 'function'
+        ? (next as (previous: T) => T)(prev)
+        : next
+
+      ref.current = resolved
+      return resolved
+    })
+  }
+
+  return [state, set, ref]
+}
diff --git a/m3-react/tests/M3Surface.test.tsx b/m3-react/tests/M3Surface.test.tsx
new file mode 100644
index 0000000..7307efc
--- /dev/null
+++ b/m3-react/tests/M3Surface.test.tsx
@@ -0,0 +1,112 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react'
+
+import { M3Surface } from '@/components/surface'
+
+describe('m3-react/surface', () => {
+  test('applies deterministic default contract', () => {
+    render(
+      <M3Surface>
+        Surface body
+      </M3Surface>
+    )
+
+    const surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface')).toBe(true)
+    expect(surface.style.width).toBe('100%')
+    expect(surface.style.height).toBe('100%')
+    expect(surface.style.margin).toBe('')
+    expect(surface.style.padding).toBe('')
+    expect(surface.style.borderTopLeftRadius).toBe('0px')
+    expect(surface.style.borderTopRightRadius).toBe('0px')
+    expect(surface.style.borderBottomRightRadius).toBe('0px')
+    expect(surface.style.borderBottomLeftRadius).toBe('0px')
+    expect(surface.style.boxSizing).toBe('')
+  })
+
+  test('supports global and per-corner rounding overrides', () => {
+    render(
+      <M3Surface
+        rounding={16}
+        roundingTopLeft={4}
+        roundingBottomRight="24px"
+      />
+    )
+
+    const surface = screen.getByRole('region')
+
+    expect(surface.style.borderTopLeftRadius).toBe('4px')
+    expect(surface.style.borderTopRightRadius).toBe('16px')
+    expect(surface.style.borderBottomRightRadius).toBe('24px')
+    expect(surface.style.borderBottomLeftRadius).toBe('16px')
+  })
+
+  test('emits close request and dismiss on scrim click in modal mode', () => {
+    const onToggle = vi.fn()
+    const onDismiss = vi.fn()
+
+    render(
+      <M3Surface
+        mode="modal"
+        shown={true}
+        onToggle={onToggle}
+        onDismiss={onDismiss}
+      >
+        Modal body
+      </M3Surface>
+    )
+
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
+
+    fireEvent.click(scrim)
+
+    expect(onToggle).toHaveBeenCalledWith(false)
+    expect(onDismiss).toHaveBeenCalledTimes(1)
+  })
+
+  test('anchors modal surface to center with fixed positioning', () => {
+    render(
+      <M3Surface
+        mode="modal"
+        shown={true}
+        anchor="center"
+        width={320}
+        height={240}
+        fillWidth={false}
+        fillHeight={false}
+      />
+    )
+
+    const surface = screen.getByRole('dialog')
+
+    expect(surface.style.position).toBe('fixed')
+    expect(surface.style.top).toBe('50%')
+    expect(surface.style.left).toBe('50%')
+    expect(surface.style.transform).toContain('translate(-50%, -50%)')
+    expect(surface.style.width).toBe('320px')
+    expect(surface.style.height).toBe('240px')
+  })
+
+  test('maps auto role from elevation and allows explicit variant override', () => {
+    const { rerender } = render(
+      <M3Surface elevation={3} />
+    )
+
+    let surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(true)
+
+    rerender(
+      <M3Surface elevation={3} variant="surface-bright" />
+    )
+
+    surface = screen.getByRole('region')
+
+    expect(surface.classList.contains('m3-surface_role-surface-bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(false)
+  })
+})

From 3216ee7d70d095ade65d85ed24189e3ba368e953 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 14:56:57 +0400
Subject: [PATCH 16/37] feat(m3-vue): Stabilized M3Surface And Updated Surface
 Stories

---
 .../surface}/M3Surface.vue                    | 163 ++++--------------
 m3-vue/src/components/surface/index.ts        |   1 +
 m3-vue/src/index.ts                           |   6 +-
 .../storybook/components/M3Surface.stories.ts |   2 +-
 .../examples/surface/SurfaceCardPageMorph.vue |  35 ++--
 .../surface/SurfaceNestedDialogsChain.vue     |  18 +-
 .../surface/SurfaceSideSheetAlwaysModal.vue   |  26 +--
 .../SurfaceSideSheetDismissToRemove.vue       |  36 ++--
 .../surface/SurfaceSideSheetModalToWindow.vue |  28 +--
 .../surface/SurfaceSideSheetMorph.vue         | 100 ++++++++---
 m3-vue/tests/M3Surface.test.ts                |   4 +-
 11 files changed, 205 insertions(+), 214 deletions(-)
 rename m3-vue/src/{experimental => components/surface}/M3Surface.vue (54%)
 create mode 100644 m3-vue/src/components/surface/index.ts

diff --git a/m3-vue/src/experimental/M3Surface.vue b/m3-vue/src/components/surface/M3Surface.vue
similarity index 54%
rename from m3-vue/src/experimental/M3Surface.vue
rename to m3-vue/src/components/surface/M3Surface.vue
index 37acd88..b04f651 100644
--- a/m3-vue/src/experimental/M3Surface.vue
+++ b/m3-vue/src/components/surface/M3Surface.vue
@@ -1,6 +1,6 @@
 <template>
     <Teleport v-if="isModal" :to="teleportTo">
-        <Transition name="m3-transition-fade">
+        <Transition v-if="scrim" name="m3-transition-fade">
             <div
                 v-show="shown"
                 :style="{ zIndex: zIndex - 1 }"
@@ -36,6 +36,12 @@
 
 <script lang="ts" setup>
 import type { PropType } from 'vue'
+import type {
+  Anchor as SurfaceAnchor,
+  Length as SurfaceLength,
+  Mode as SurfaceMode,
+  Variant as SurfaceVariant,
+} from '@modulify/m3-foundation/types/components/surface'
 
 import {
   computed,
@@ -47,6 +53,7 @@ import {
   isUndefined,
   Or,
 } from '@modulify/m3-foundation/lib/predicates'
+import { m3MotionEasings } from '@modulify/m3-foundation/lib/motion'
 
 import useId from '@/composables/id'
 
@@ -54,33 +61,6 @@ defineOptions({
   inheritAttrs: false,
 })
 
-type Length = string | number
-
-type SurfaceMode = 'standard' | 'modal'
-
-type SurfaceRole =
-  | 'auto'
-  | 'surface'
-  | 'surface-dim'
-  | 'surface-bright'
-  | 'surface-container-lowest'
-  | 'surface-container-low'
-  | 'surface-container'
-  | 'surface-container-high'
-  | 'surface-container-highest'
-
-type Anchor =
-  | 'none'
-  | 'center'
-  | 'start'
-  | 'end'
-  | 'top'
-  | 'bottom'
-  | 'top-start'
-  | 'top-end'
-  | 'bottom-start'
-  | 'bottom-end'
-
 type AnchorStyleFactory = (inset: {
   top: string,
   right: string,
@@ -88,7 +68,7 @@ type AnchorStyleFactory = (inset: {
   left: string,
 }) => Record<string, string>
 
-const MODAL_ANCHOR_STYLE: Record<Anchor, AnchorStyleFactory> = {
+const MODAL_ANCHOR_STYLE: Record<SurfaceAnchor, AnchorStyleFactory> = {
   none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
   center: () => ({
     top: '50%',
@@ -134,14 +114,19 @@ const props = defineProps({
     default: 'body',
   },
 
+  scrim: {
+    type: Boolean,
+    default: true,
+  },
+
   elevation: {
     type: Number,
     default: 0,
     validator: (value: number) => Number.isInteger(value) && value >= 0 && value <= 5,
   },
 
-  surfaceRole: {
-    type: String as PropType<SurfaceRole>,
+  variant: {
+    type: String as PropType<SurfaceVariant>,
     default: 'auto',
   },
 
@@ -156,82 +141,82 @@ const props = defineProps({
   },
 
   width: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   height: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   minWidth: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   maxWidth: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   minHeight: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   maxHeight: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   rounding: {
-    type: null as unknown as PropType<Length>,
+    type: null as unknown as PropType<SurfaceLength>,
     default: 0,
   },
 
   roundingTopLeft: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   roundingTopRight: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   roundingBottomRight: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   roundingBottomLeft: {
-    type: null as unknown as PropType<Length | null>,
+    type: null as unknown as PropType<SurfaceLength | null>,
     default: null,
   },
 
   anchor: {
-    type: String as PropType<Anchor>,
+    type: String as PropType<SurfaceAnchor>,
     default: 'none',
   },
 
   insetTop: {
-    type: null as unknown as PropType<Length>,
+    type: null as unknown as PropType<SurfaceLength>,
     default: 0,
   },
 
   insetRight: {
-    type: null as unknown as PropType<Length>,
+    type: null as unknown as PropType<SurfaceLength>,
     default: 0,
   },
 
   insetBottom: {
-    type: null as unknown as PropType<Length>,
+    type: null as unknown as PropType<SurfaceLength>,
     default: 0,
   },
 
   insetLeft: {
-    type: null as unknown as PropType<Length>,
+    type: null as unknown as PropType<SurfaceLength>,
     default: 0,
   },
 
@@ -247,7 +232,7 @@ const props = defineProps({
 
   transitionTiming: {
     type: String,
-    default: 'cubic-bezier(0.2, 0, 0, 1)',
+    default: m3MotionEasings.standard,
   },
 
   overflow: {
@@ -263,7 +248,7 @@ const emit = defineEmits([
 
 const attrs = useAttrs()
 
-function toLength(value: Length | null | undefined, fallback: string): string {
+function toLength(value: SurfaceLength | null | undefined, fallback: string): string {
   if (value == null) {
     return fallback
   }
@@ -281,8 +266,8 @@ const _id = useId('m3-surface', computed(() => props.id))
 
 const isModal = computed(() => props.mode === 'modal')
 
-const resolvedRole = computed<Exclude<SurfaceRole, 'auto'>>(() => {
-  if (props.surfaceRole !== 'auto') return props.surfaceRole
+const resolvedVariant = computed<Exclude<SurfaceVariant, 'auto'>>(() => {
+  if (props.variant !== 'auto') return props.variant
 
   switch (props.elevation) {
     case 0: return 'surface'
@@ -349,7 +334,6 @@ const transition = computed(() => {
     `max-width ${duration} ${props.transitionTiming}`,
     `min-height ${duration} ${props.transitionTiming}`,
     `max-height ${duration} ${props.transitionTiming}`,
-    `border-radius ${duration} ${props.transitionTiming}`,
     `top ${duration} ${props.transitionTiming}`,
     `right ${duration} ${props.transitionTiming}`,
     `bottom ${duration} ${props.transitionTiming}`,
@@ -375,7 +359,7 @@ const surfaceAttrs = computed(() => {
 const surfaceClass = computed(() => ({
   'm3-surface': true,
   'm3-surface_modal': isModal.value,
-  [`m3-surface_role-${resolvedRole.value}`]: true,
+  [`m3-surface_role-${resolvedVariant.value}`]: true,
   [`m3-surface_anchor-${props.anchor}`]: true,
   [`m3-surface_elevation-${props.elevation}`]: true,
 }))
@@ -385,6 +369,7 @@ const surfaceStyle = computed(() => {
     ...resolvedSizeStyle.value,
     ...cornerRadiusStyle.value,
     ...anchorStyle.value,
+    '--m3-surface-radius-transition-duration': `${props.transitionMs}ms`,
     overflow: props.overflow,
     transition: transition.value,
     position: isModal.value ? 'fixed' : 'relative',
@@ -397,75 +382,3 @@ function onScrimClick() {
   emit('dismiss')
 }
 </script>
-
-<style scoped lang="scss">
-@use '../../../m3-foundation/assets/stylesheets/basics/palette' as palette;
-@use '../../../m3-foundation/assets/stylesheets/themes/dark' as dark;
-@use '../../../m3-foundation/assets/stylesheets/themes/light' as light;
-
-.m3-surface {
-  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{light.$m3-sys-light-surface});
-  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
-  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
-  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{palette.$m3-palette-neutral-100});
-  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
-  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{light.$m3-sys-light-surface-container});
-  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{light.$m3-sys-light-surface-container-high});
-  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
-  --m3-surface-elevation-1: var(--m3-elevation-1, #{light.$m3-elevation-light-1});
-  --m3-surface-elevation-2: var(--m3-elevation-2, #{light.$m3-elevation-light-2});
-  --m3-surface-elevation-3: var(--m3-elevation-3, #{light.$m3-elevation-light-3});
-  --m3-surface-elevation-4: var(--m3-elevation-4, #{light.$m3-elevation-light-4});
-  --m3-surface-elevation-5: var(--m3-elevation-5, #{light.$m3-elevation-light-5});
-
-  display: block;
-  isolation: isolate;
-  box-sizing: border-box;
-
-  &_modal {
-    max-width: 100vw;
-    max-height: 100vh;
-  }
-
-  &_role-surface {
-    background-color: var(--m3-surface-role-surface-bg);
-  }
-
-  &_role-surface-dim               { background-color: var(--m3-surface-role-surface-dim-bg); }
-  &_role-surface-bright            { background-color: var(--m3-surface-role-surface-bright-bg); }
-  &_role-surface-container-lowest  { background-color: var(--m3-surface-role-container-lowest-bg); }
-  &_role-surface-container-low     { background-color: var(--m3-surface-role-container-low-bg); }
-  &_role-surface-container         { background-color: var(--m3-surface-role-container-bg); }
-  &_role-surface-container-high    { background-color: var(--m3-surface-role-container-high-bg); }
-  &_role-surface-container-highest { background-color: var(--m3-surface-role-container-highest-bg); }
-
-  &_elevation-0 { box-shadow: none; }
-  &_elevation-1 { box-shadow: var(--m3-surface-elevation-1); }
-  &_elevation-2 { box-shadow: var(--m3-surface-elevation-2); }
-  &_elevation-3 { box-shadow: var(--m3-surface-elevation-3); }
-  &_elevation-4 { box-shadow: var(--m3-surface-elevation-4); }
-  &_elevation-5 { box-shadow: var(--m3-surface-elevation-5); }
-
-  &__scrim {
-    position: fixed;
-    inset: 0;
-    background: color-mix(in srgb, var(--m3-sys-shadow, #{palette.$m3-palette-neutral-0}) 38%, transparent);
-  }
-}
-
-:global(html.m3-theme-dark) .m3-surface {
-  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
-  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
-  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
-  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
-  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
-  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{dark.$m3-sys-dark-surface-container});
-  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{dark.$m3-sys-dark-surface-container-high});
-  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
-  --m3-surface-elevation-1: var(--m3-elevation-1, #{dark.$m3-elevation-dark-1});
-  --m3-surface-elevation-2: var(--m3-elevation-2, #{dark.$m3-elevation-dark-2});
-  --m3-surface-elevation-3: var(--m3-elevation-3, #{dark.$m3-elevation-dark-3});
-  --m3-surface-elevation-4: var(--m3-elevation-4, #{dark.$m3-elevation-dark-4});
-  --m3-surface-elevation-5: var(--m3-elevation-5, #{dark.$m3-elevation-dark-5});
-}
-</style>
diff --git a/m3-vue/src/components/surface/index.ts b/m3-vue/src/components/surface/index.ts
new file mode 100644
index 0000000..6f5e46b
--- /dev/null
+++ b/m3-vue/src/components/surface/index.ts
@@ -0,0 +1 @@
+export { default as M3Surface } from './M3Surface.vue'
diff --git a/m3-vue/src/index.ts b/m3-vue/src/index.ts
index 43ff0f8..542a779 100644
--- a/m3-vue/src/index.ts
+++ b/m3-vue/src/index.ts
@@ -78,6 +78,10 @@ export {
   M3SideSheet,
 } from '@/components/side-sheet'
 
+export {
+  M3Surface,
+} from '@/components/surface'
+
 export {
   M3Slider,
 } from '@/components/slider'
@@ -89,4 +93,4 @@ export {
 export {
   M3TextField,
   M3TextFieldSupportText,
-} from '@/components/text-field'
\ No newline at end of file
+} from '@/components/text-field'
diff --git a/m3-vue/storybook/components/M3Surface.stories.ts b/m3-vue/storybook/components/M3Surface.stories.ts
index dd0af65..6757270 100644
--- a/m3-vue/storybook/components/M3Surface.stories.ts
+++ b/m3-vue/storybook/components/M3Surface.stories.ts
@@ -3,7 +3,7 @@ import type {
   StoryObj,
 } from '@storybook/vue3'
 
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph.vue'
 import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain.vue'
diff --git a/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
index eaddf14..48b5e8b 100644
--- a/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
@@ -8,7 +8,7 @@
             class="surface-card-page__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-card-page__topbar-content">
@@ -83,7 +83,7 @@
                     :fill-height="false"
                     :height="120"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Card-to-page transition playground</h3>
@@ -112,7 +112,7 @@
                             :fill-height="false"
                             :height="184"
                             :rounding="16"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="1"
                         >
                             <strong>Static card A</strong>
@@ -124,7 +124,7 @@
                             :fill-height="false"
                             :height="184"
                             :rounding="16"
-                            surface-role="surface-container"
+                            variant="surface-container"
                             :elevation="2"
                         >
                             <strong>Static card B</strong>
@@ -149,8 +149,8 @@
                                 :fill-height="true"
                                 :rounding="expanded ? 0 : 24"
                                 :transition-ms="TRANSITION_MS"
-                                transition-timing="cubic-bezier(0.2, 0, 0, 1)"
-                                :surface-role="expanded ? 'surface' : 'surface-container-low'"
+                                :transition-timing="TRANSITION_EASING"
+                                :variant="expanded ? 'surface' : 'surface-container-low'"
                                 :elevation="expanded ? 0 : 1"
                                 overflow="auto"
                                 data-testid="surface-card-morph"
@@ -166,7 +166,7 @@
                                     :fill-height="false"
                                     :height="120"
                                     :rounding="14"
-                                    :surface-role="expanded ? 'surface-container-low' : 'surface-container-high'"
+                                    :variant="expanded ? 'surface-container-low' : 'surface-container-high'"
                                     :elevation="expanded ? 1 : 3"
                                 >
                                     Nested surface demonstrates composability in both states.
@@ -188,7 +188,7 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   computed,
@@ -196,13 +196,18 @@ import {
   onMounted,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
 const expanded = ref(false)
 const busy = ref(false)
 const navExpanded = ref(false)
 const backgroundCollapsed = ref(false)
 const activeNavTab = ref<'files' | 'timeline' | 'tasks' | 'analytics'>('files')
-const TRANSITION_MS = 340
+const TRANSITION_MS = m3MotionDurations.medium3
+const TRANSITION_EASING = m3MotionEasings.standard
 
 const canvas = ref<HTMLElement | null>(null)
 const originSlot = ref<HTMLElement | null>(null)
@@ -352,7 +357,9 @@ onMounted(() => {
 })
 </script>
 
-<style scoped>
+<style lang="scss" scoped>
+@use '@modulify/m3-foundation/assets/stylesheets/basics/motion' as m3-motion;
+
 .surface-card-page {
     --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
     --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
@@ -479,10 +486,10 @@ onMounted(() => {
 .surface-card-page__overlay-wrap {
     position: absolute;
     transition:
-        top 340ms cubic-bezier(0.2, 0, 0, 1),
-        left 340ms cubic-bezier(0.2, 0, 0, 1),
-        width 340ms cubic-bezier(0.2, 0, 0, 1),
-        height 340ms cubic-bezier(0.2, 0, 0, 1);
+        top #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+        left #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+        width #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')},
+        height #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')};
 }
 
 .surface-card-page__morph-surface {
diff --git a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
index c4e2838..8d2039e 100644
--- a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
@@ -7,7 +7,7 @@
             class="surface-dialog-chain__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-dialog-chain__topbar-content">
@@ -72,7 +72,7 @@
                     :fill-height="false"
                     :height="124"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Workspace</h3>
@@ -82,7 +82,7 @@
                 <M3Surface
                     class="surface-dialog-chain__canvas"
                     :rounding="20"
-                    surface-role="surface-container-low"
+                    variant="surface-container-low"
                     :elevation="0"
                 >
                     <h4>Background content</h4>
@@ -113,7 +113,7 @@
                 :transition-ms="DIALOG_TRANSITION_MS"
                 :transition-timing="DIALOG_TRANSITION_EASING"
                 :z-index="dialogZIndex(level)"
-                surface-role="surface-container-highest"
+                variant="surface-container-highest"
                 :elevation="dialogElevation(level)"
                 overflow="visible"
                 :style="dialogInlineStyle(level)"
@@ -166,16 +166,20 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   computed,
   nextTick,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
-const DIALOG_TRANSITION_MS = 300
-const DIALOG_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
+const DIALOG_TRANSITION_MS = m3MotionDurations.medium2
+const DIALOG_TRANSITION_EASING = m3MotionEasings.standard
 const DIALOG_ENTRY_OFFSET_PX = 24
 const DIALOG_Z_INDEX_BASE = 560
 const DIALOG_Z_INDEX_STEP = 40
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
index 560df11..e84a027 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
@@ -8,7 +8,7 @@
             class="surface-side-sheet__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-side-sheet__topbar-content">
@@ -83,7 +83,7 @@
                     :fill-height="false"
                     :height="120"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Workspace surfaces</h3>
@@ -104,7 +104,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-lowest"
+                            variant="surface-container-lowest"
                             :elevation="0"
                         >
                             <strong>surface-container-lowest</strong>
@@ -116,7 +116,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="1"
                         >
                             <strong>surface-container-low</strong>
@@ -128,7 +128,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-high"
+                            variant="surface-container-high"
                             :elevation="3"
                         >
                             <strong>surface-container-high</strong>
@@ -140,7 +140,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-dim"
+                            variant="surface-dim"
                             :elevation="0"
                         >
                             <strong>surface-dim</strong>
@@ -167,7 +167,7 @@
                         :transition-ms="PANEL_TRANSITION_MS"
                         :transition-timing="PANEL_TRANSITION_EASING"
                         :z-index="520"
-                        surface-role="surface-container-high"
+                        variant="surface-container-high"
                         :elevation="modalElevation"
                         overflow="auto"
                         data-testid="surface-always-panel"
@@ -208,7 +208,7 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   onBeforeUnmount,
@@ -216,6 +216,10 @@ import {
   nextTick,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
@@ -225,9 +229,9 @@ const SIDE_SHEET_WIDTH_STEP = 4
 const MODAL_INSET_TOP = 0
 const MODAL_INSET_BOTTOM = 0
 const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = 300
-const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
-const SCRIM_FADE_MS = 500
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
index 12b7199..199ca6c 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
@@ -4,7 +4,7 @@
             class="surface-side-sheet__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-side-sheet__topbar-content">
@@ -82,7 +82,7 @@
                     :fill-height="false"
                     :height="120"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Workspace surfaces</h3>
@@ -99,7 +99,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-lowest"
+                            variant="surface-container-lowest"
                             :elevation="0"
                         >
                             <strong>surface-container-lowest</strong>
@@ -111,7 +111,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="1"
                         >
                             <strong>surface-container-low</strong>
@@ -123,7 +123,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-high"
+                            variant="surface-container-high"
                             :elevation="3"
                         >
                             <strong>surface-container-high</strong>
@@ -135,7 +135,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-dim"
+                            variant="surface-dim"
                             :elevation="0"
                         >
                             <strong>surface-dim</strong>
@@ -155,7 +155,7 @@
                             :fill-width="true"
                             :fill-height="true"
                             :rounding="0"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="0"
                             overflow="auto"
                         >
@@ -187,7 +187,7 @@
                         :transition-ms="PANEL_TRANSITION_MS"
                         :transition-timing="PANEL_TRANSITION_EASING"
                         :z-index="520"
-                        :surface-role="modalRole"
+                        :variant="modalRole"
                         :elevation="modalElevation"
                         overflow="auto"
                         @dismiss="closeModalFromPanel"
@@ -228,7 +228,7 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   onBeforeUnmount,
@@ -236,6 +236,10 @@ import {
   nextTick,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
@@ -245,9 +249,9 @@ const SIDE_SHEET_WIDTH_STEP = 4
 const MODAL_INSET_TOP = 0
 const MODAL_INSET_BOTTOM = 0
 const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = 300
-const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
-const SCRIM_FADE_MS = 500
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
@@ -441,7 +445,9 @@ onBeforeUnmount(() => {
 })
 </script>
 
-<style scoped>
+<style lang="scss" scoped>
+@use '@modulify/m3-foundation/assets/stylesheets/basics/motion' as m3-motion;
+
 .surface-side-sheet {
     --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
     --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
@@ -451,8 +457,8 @@ onBeforeUnmount(() => {
     --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
     --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
     --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
-    --surface-panel-transition-ms: 300ms;
-    --surface-panel-transition-easing: cubic-bezier(0.2, 0, 0, 1);
+    --surface-panel-transition-ms: #{m3-motion.duration('medium2')};
+    --surface-panel-transition-easing: #{m3-motion.easing('standard')};
     min-height: 100vh;
     background:
         radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
index ccf6649..a554bf4 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
@@ -9,7 +9,7 @@
             class="surface-side-sheet-window__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-side-sheet-window__topbar-content">
@@ -84,7 +84,7 @@
                     :fill-height="false"
                     :height="120"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Workspace surfaces</h3>
@@ -105,7 +105,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-lowest"
+                            variant="surface-container-lowest"
                             :elevation="0"
                         >
                             <strong>surface-container-lowest</strong>
@@ -117,7 +117,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="1"
                         >
                             <strong>surface-container-low</strong>
@@ -129,7 +129,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-high"
+                            variant="surface-container-high"
                             :elevation="3"
                         >
                             <strong>surface-container-high</strong>
@@ -141,7 +141,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-dim"
+                            variant="surface-dim"
                             :elevation="0"
                         >
                             <strong>surface-dim</strong>
@@ -171,7 +171,7 @@
                         :transition-ms="panelTransitionMs"
                         :transition-timing="panelTransitionTiming"
                         :z-index="520"
-                        :surface-role="panelSurfaceRole"
+                        :variant="panelSurfaceRole"
                         :elevation="panelElevation"
                         :style="panelInlineStyle"
                         overflow="auto"
@@ -303,7 +303,7 @@ import {
 } from '@/components/navigation'
 import { M3Select } from '@/components/select'
 import { M3TextField } from '@/components/text-field'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   computed,
@@ -313,6 +313,10 @@ import {
   reactive,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
@@ -327,10 +331,10 @@ const WINDOW_WIDTH_STEP = 8
 const MODAL_INSET_TOP = 0
 const MODAL_INSET_BOTTOM = 0
 const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = 300
-const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
-const SCRIM_FADE_MS = 500
-const DIALOG_HIDE_MS = 500
+const PANEL_TRANSITION_MS = m3MotionDurations.medium4
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
+const SCRIM_FADE_MS = m3MotionDurations.long2
+const DIALOG_HIDE_MS = m3MotionDurations.long2
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
index 72e3f59..787b53d 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
@@ -8,7 +8,7 @@
             class="surface-side-sheet__topbar"
             :fill-height="false"
             :height="72"
-            surface-role="surface-container"
+            variant="surface-container"
             :elevation="0"
         >
             <div class="surface-side-sheet__topbar-content">
@@ -83,7 +83,7 @@
                     :fill-height="false"
                     :height="120"
                     :rounding="20"
-                    surface-role="surface-container-lowest"
+                    variant="surface-container-lowest"
                     :elevation="0"
                 >
                     <h3>Workspace surfaces</h3>
@@ -104,7 +104,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-lowest"
+                            variant="surface-container-lowest"
                             :elevation="0"
                         >
                             <strong>surface-container-lowest</strong>
@@ -116,7 +116,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="1"
                         >
                             <strong>surface-container-low</strong>
@@ -128,7 +128,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-container-high"
+                            variant="surface-container-high"
                             :elevation="3"
                         >
                             <strong>surface-container-high</strong>
@@ -140,7 +140,7 @@
                             :fill-height="false"
                             :height="136"
                             :rounding="18"
-                            surface-role="surface-dim"
+                            variant="surface-dim"
                             :elevation="0"
                         >
                             <strong>surface-dim</strong>
@@ -160,7 +160,7 @@
                             :fill-width="true"
                             :fill-height="true"
                             :rounding="0"
-                            surface-role="surface-container-low"
+                            variant="surface-container-low"
                             :elevation="0"
                             overflow="auto"
                             data-testid="surface-morph-docked-sheet"
@@ -190,10 +190,10 @@
                         :rounding-bottom-left="modalRadiusLeft"
                         :rounding-top-right="0"
                         :rounding-bottom-right="0"
-                        :transition-ms="PANEL_TRANSITION_MS"
+                        :transition-ms="modalTransitionMs"
                         :transition-timing="PANEL_TRANSITION_EASING"
                         :z-index="520"
-                        :surface-role="modalRole"
+                        :variant="modalRole"
                         :elevation="modalElevation"
                         overflow="auto"
                         data-testid="surface-morph-modal-sheet"
@@ -235,7 +235,7 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 import {
   onBeforeUnmount,
@@ -243,6 +243,10 @@ import {
   nextTick,
   ref,
 } from 'vue'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
 
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
@@ -252,9 +256,9 @@ const SIDE_SHEET_WIDTH_STEP = 4
 const MODAL_INSET_TOP = 0
 const MODAL_INSET_BOTTOM = 0
 const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = 300
-const PANEL_TRANSITION_EASING = 'cubic-bezier(0.2, 0, 0, 1)'
-const SCRIM_FADE_MS = 500
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const PANEL_VERTICAL_EXPAND_MS = 120
+const PANEL_TRANSITION_EASING = m3MotionEasings.standard
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
@@ -270,6 +274,7 @@ const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
 const modalRadiusLeft = ref(0)
 const modalElevation = ref(0)
 const modalRole = ref<'surface-container-low' | 'surface-container-high'>('surface-container-low')
+const modalTransitionMs = ref(PANEL_TRANSITION_MS)
 const transitioning = ref(false)
 const dockedHost = ref<HTMLElement | null>(null)
 const layoutRoot = ref<HTMLElement | null>(null)
@@ -345,10 +350,40 @@ function setModalGeometryTarget() {
   modalInsetBottom.value = MODAL_INSET_BOTTOM
 }
 
+async function expandModalToViewportHeight() {
+  // Delay vertical expansion so the morph starts with an X-axis transition.
+  modalTransitionMs.value = PANEL_VERTICAL_EXPAND_MS
+  await nextTick()
+  await raf()
+  setModalGeometryTarget()
+  await wait(PANEL_VERTICAL_EXPAND_MS)
+  modalTransitionMs.value = PANEL_TRANSITION_MS
+}
+
+function resolveDockedTargetGeometry() {
+  const layout = layoutRoot.value?.getBoundingClientRect()
+  if (!layout) {
+    return {
+      width: sideSheetWidth.value,
+      insetTop: MODAL_INSET_TOP,
+      insetRight: MODAL_INSET_END,
+      insetBottom: MODAL_INSET_BOTTOM,
+    }
+  }
+
+  return {
+    width: sideSheetWidth.value,
+    insetTop: Math.round(layout.top),
+    insetRight: Math.round(window.innerWidth - layout.right),
+    insetBottom: Math.round(window.innerHeight - layout.bottom),
+  }
+}
+
 async function switchDockedToModal() {
   syncFixedWidth()
   setModalGeometryFromDocked()
 
+  modalTransitionMs.value = PANEL_TRANSITION_MS
   modalRadiusLeft.value = 0
   modalElevation.value = 0
   modalRole.value = 'surface-container-low'
@@ -364,31 +399,42 @@ async function switchDockedToModal() {
 
   sideSheetModal.value = true
   sideSheetDockedWidth.value = 0
-  setModalGeometryTarget()
+  modalWidth.value = sideSheetWidth.value
+  modalInsetRight.value = MODAL_INSET_END
   modalRadiusLeft.value = 28
   modalElevation.value = 1
   modalRole.value = 'surface-container-high'
   await wait(PANEL_TRANSITION_MS)
+
+  await expandModalToViewportHeight()
 }
 
 async function switchModalToDocked() {
   syncFixedWidth()
+  const dockedTarget = resolveDockedTargetGeometry()
 
+  modalTransitionMs.value = PANEL_TRANSITION_MS
   modalElevation.value = 0
   modalRole.value = 'surface-container-low'
   modalRadiusLeft.value = 0
-  modalInsetTop.value = MODAL_INSET_TOP
-  modalInsetBottom.value = MODAL_INSET_BOTTOM
-  modalInsetRight.value = hiddenInsetRight()
+
+  // Start returning flow slot first, then morph modal panel into that geometry.
+  sideSheetDockedWidth.value = sideSheetWidth.value
+  modalWidth.value = dockedTarget.width
+  modalInsetTop.value = dockedTarget.insetTop
+  modalInsetRight.value = dockedTarget.insetRight
+  modalInsetBottom.value = dockedTarget.insetBottom
+
   await wait(PANEL_TRANSITION_MS)
+
+  // Swap to docked instance at the end position without extra hide animation.
+  sideSheetModal.value = false
   modalVisible.value = false
-  await wait(SCRIM_FADE_MS)
   modalShown.value = false
-  sideSheetModal.value = false
-  await nextTick()
-  await raf()
-  sideSheetDockedWidth.value = sideSheetWidth.value
-  await wait(PANEL_TRANSITION_MS)
+
+  modalInsetTop.value = MODAL_INSET_TOP
+  modalInsetRight.value = hiddenInsetRight()
+  modalInsetBottom.value = MODAL_INSET_BOTTOM
 }
 
 async function toggleSideSheetMode() {
@@ -432,7 +478,9 @@ onBeforeUnmount(() => {
 })
 </script>
 
-<style scoped>
+<style lang="scss" scoped>
+@use '@modulify/m3-foundation/assets/stylesheets/basics/motion' as m3-motion;
+
 .surface-side-sheet {
     --surface-scene-bg-0: var(--m3-sys-surface, var(--md-sys-color-surface, #fef7ff));
     --surface-scene-bg-1: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
@@ -442,8 +490,8 @@ onBeforeUnmount(() => {
     --surface-shadow-color: color-mix(in srgb, var(--m3-sys-shadow, #000000) 22%, transparent);
     --surface-layout-bg: var(--m3-sys-surface-container, var(--md-sys-color-surface-container, #f3edf7));
     --surface-grid-bg: var(--m3-sys-surface-container-low, var(--md-sys-color-surface-container-low, #f7f2fa));
-    --surface-panel-transition-ms: 300ms;
-    --surface-panel-transition-easing: cubic-bezier(0.2, 0, 0, 1);
+    --surface-panel-transition-ms: #{m3-motion.duration('medium2')};
+    --surface-panel-transition-easing: #{m3-motion.easing('standard')};
     min-height: 100vh;
     background:
         radial-gradient(circle at 8% 0%, var(--surface-accent-a), transparent 42%),
diff --git a/m3-vue/tests/M3Surface.test.ts b/m3-vue/tests/M3Surface.test.ts
index f02992e..a527e22 100644
--- a/m3-vue/tests/M3Surface.test.ts
+++ b/m3-vue/tests/M3Surface.test.ts
@@ -4,7 +4,7 @@ import {
   screen,
 } from '@testing-library/vue'
 
-import M3Surface from '@/experimental/M3Surface.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
 
 describe('m3-vue/experimental/surface', () => {
   test('applies deterministic default contract', () => {
@@ -100,7 +100,7 @@ describe('m3-vue/experimental/surface', () => {
 
     await view.rerender({
       elevation: 3,
-      surfaceRole: 'surface-bright',
+      variant: 'surface-bright',
     })
 
     surface = screen.getByRole('region')

From 53529d0e7a99a7bd9efd8d0745cdf97e5c6196be Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 18:13:24 +0400
Subject: [PATCH 17/37] build: Recipe-based developer tooling was reorganized

---
 AGENTS.md                                     |  41 ++
 Makefile                                      | 359 ++++++++++--------
 recipes/common.mk                             |  19 +
 recipes/help.sh                               | 134 +++++++
 recipes/lint.mk                               |  46 +++
 recipes/research.mk                           |  90 +++++
 recipes/research/capture.sh                   | 207 ++++++++++
 recipes/research/fetch.sh                     | 153 ++++++++
 recipes/research/packs/surfaces.page-data.tsv |   9 +
 recipes/research/packs/surfaces.urls.txt      |   9 +
 recipes/storybook.mk                          |  17 +
 recipes/tests.mk                              |  76 ++++
 scripts/playwright-capture.mjs                | 141 +++++++
 13 files changed, 1141 insertions(+), 160 deletions(-)
 create mode 100644 recipes/common.mk
 create mode 100755 recipes/help.sh
 create mode 100644 recipes/lint.mk
 create mode 100644 recipes/research.mk
 create mode 100755 recipes/research/capture.sh
 create mode 100755 recipes/research/fetch.sh
 create mode 100644 recipes/research/packs/surfaces.page-data.tsv
 create mode 100644 recipes/research/packs/surfaces.urls.txt
 create mode 100644 recipes/storybook.mk
 create mode 100644 recipes/tests.mk
 create mode 100644 scripts/playwright-capture.mjs

diff --git a/AGENTS.md b/AGENTS.md
index 3cffad9..932862a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,13 @@
   without requiring explicit user confirmation.
 - For `drafts/` work, automatically maintain links from the main draft
   markdown file to related YAML sidecars.
+- During experimental component development, do not modify current production
+  components in `src/components` unless explicitly requested.
+- For agent-driven experimental components, create and use `src/experiment`
+  directories at the same level as `src/components` inside each workspace.
+- Experimental implementation order is mandatory: implement in
+  `m3-vue/src/experiment` first; port to `m3-react/src/experiment` only after
+  the experiment is explicitly confirmed as successful.
 - Getter/helper functions must be side-effect free. Side effects are allowed
   only by prior agreement and only when there are strong, explicit reasons.
 
@@ -33,6 +40,40 @@
 - Always mention blockers, failed required checks, or other omissions that can
   affect correctness, safety, or reproducibility.
 
+## Experiment Workflow
+- Before starting any non-trivial experiment, explicitly ask the user for a
+  time budget/timeout for the run (for example 30, 60, 120 minutes).
+- Record experiment start immediately in `drafts/experiment.md` with:
+  start timestamp, agreed timeout, current goal, and planned checkpoints.
+- Keep a milestone log in `drafts/milestones.md`:
+  create an entry before validating each sub-hypothesis/side-hypothesis and
+  create a matching completion entry after validation with outcomes.
+- Log missing inputs in `drafts/milestones.md` as separate "missing" notes
+  (for example unavailable data, blocked tools/access, unclear acceptance
+  criteria, missing artifacts).
+- In experiment mode, escalations are forbidden by default.
+- Exception: escalations are allowed only after explicit user sanction for the
+  current experiment scope.
+- Before any sanctioned escalation phase, define and log an escalation window:
+  exact command set, start marker, and freeze condition.
+- When sanctioned, log `escalation-needed` before request and
+  `escalation-result` after execution in `drafts/milestones.md`.
+- Prefer one-shot privileged bootstrap (`make m3/experiment/bootstrap/evidence`)
+  over multiple incremental escalation requests.
+- During experiments, use `m3/experiment/*` wrappers only; avoid direct
+  `research-fetch-*` and `research-capture-*` calls to keep escalation scope
+  predictable.
+- If not sanctioned, log `escalation-blocked` and `missing`, then continue
+  with non-escalated steps only.
+- After escalation freeze is declared, do not issue new escalation requests.
+  If a required action would need escalation, log `escalation-blocked` +
+  `missing` and continue only with local/safe targets.
+- During experiments, periodically check elapsed time against the agreed
+  timeout and record time checks in `drafts/milestones.md`.
+- If timeout is reached or at risk, stop/slow down and ask the user whether to
+  extend, narrow scope, or finish with current findings to avoid open-ended
+  runs.
+
 ## Purpose
 This file defines practical instructions for working in the
 `modulify/m3-web` repository, with a focus on test execution and commit
diff --git a/Makefile b/Makefile
index 824cfbf..da0694c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,20 +1,32 @@
+.DEFAULT_GOAL := help
+
 TARGET_HEADER=@echo -e '===== \e[34m' $@ '\e[0m'
 TARGET_OK=@echo -e '\e[32mOK\e[0m'
 YARN=@docker-compose run --rm node yarn
 YARN_PLAYWRIGHT=@docker-compose run --rm playwright yarn
+PLAYWRIGHT_NODE=@docker-compose run --rm playwright node
+PLAYWRIGHT_NODE_CMD=$(patsubst @%,%,$(PLAYWRIGHT_NODE))
 COVERAGE_PARTS_DIR=coverage/.parts
 COVERAGE_UNIT_DIR=coverage/unit
 COVERAGE_E2E_REACT_DIR=coverage/e2e-react
 COVERAGE_E2E_VUE_DIR=coverage/e2e-vue
 NYC_OUTPUT_DIR=.nyc_output
+M3_FETCH_OUT_DIR?=/tmp/m3-fetch
+M3_UA?=m3-web-research/1.0
+M3_CAPTURE_OUT_DIR?=drafts/screenshots
+M3_RESEARCH_PACKS_DIR?=recipes/research/packs
+M3_DEFAULT_RESEARCH_PACK?=surfaces
+M3_EXPERIMENT_ROOT?=drafts/experiment
+M3_EXPERIMENT_URLS_DIR?=$(M3_EXPERIMENT_ROOT)/urls
+M3_EXPERIMENT_BOOTSTRAP_PROFILES?=compact medium expanded
 
 .PHONY: up
-up: ## Starts storybook
+up: ## [Dev][docker] Starts storybook
 	$(TARGET_HEADER)
 	docker-compose up -d
 
 .PHONY: restart
-restart: ## Restarts all docker services or a particular service, if argument "service" is specified (example: make restart service="storybook").
+restart: ## [Dev][docker] Restarts all docker services or a particular service, if argument "service" is specified (example: make restart service="storybook")
 	$(TARGET_HEADER)
 
 ifdef service
@@ -24,168 +36,24 @@ else
 endif
 
 .PHONY: stop
-stop: ## Stops all docker services
+stop: ## [Dev][docker] Stops all docker services
 	$(TARGET_HEADER)
 	docker-compose stop
 
-.PHONY: .yarnrc.yml
-.yarnrc.yml: ## Creates yarn configuration
-	@cp .yarnrc.yml.dist .yarnrc.yml
-
-.PHONY: node_modules
-node_modules: package.json yarn.lock ## Installs dependencies
-	$(TARGET_HEADER)
-	$(YARN) install
-	@touch node_modules || true
-	@echo ""
+include recipes/common.mk
 
 .PHONY: build
-build: node_modules ## Creates a dist catalogue with library build
+build: node_modules ## [Build][docker] Creates a dist catalogue with library build
 	$(TARGET_HEADER)
 	$(YARN) build
 
-.PHONY: storybook-build-test
-storybook-build-test: node_modules ## Builds Storybook in --test mode for all UI workspaces
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-react storybook:build --test --quiet
-	$(YARN) workspace @modulify/m3-vue storybook:build --test --quiet
-
-.PHONY: storybook-build-test-react
-storybook-build-test-react: node_modules ## Builds Storybook in --test mode for @modulify/m3-react
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-react storybook:build --test --quiet
-
-.PHONY: storybook-build-test-vue
-storybook-build-test-vue: node_modules ## Builds Storybook in --test mode for @modulify/m3-vue
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-vue storybook:build --test --quiet
-
-.PHONY: test-smoke
-test-smoke: node_modules ## Runs smoke tests for all UI workspaces
-	$(TARGET_HEADER)
-	$(YARN) test:smoke
-
-.PHONY: test-runtime-parity
-test-runtime-parity: ## Checks Node/Yarn parity across docker services (node, storybook, playwright)
-	$(TARGET_HEADER)
-	./runtime-parity.test.sh
-
-.PHONY: husky
-husky: node_modules ## Adds husky git hooks with commit content checks
-	@docker-compose run --rm node npx husky init
-
-.PHONY: eslint
-eslint: node_modules ## Runs eslint
-	$(TARGET_HEADER)
-	$(YARN) eslint
-
-.PHONY: tsc
-tsc: node_modules ## Runs type checks in all workspaces
-	$(TARGET_HEADER)
-	$(YARN) tsc
-
-.PHONY: tsc-foundation
-tsc-foundation: node_modules ## Runs type checks in @modulify/m3-foundation
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-foundation tsc
-
-.PHONY: tsc-react
-tsc-react: node_modules ## Runs type checks in @modulify/m3-react
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-react tsc
-
-.PHONY: tsc-vue
-tsc-vue: node_modules ## Runs type checks in @modulify/m3-vue
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-vue tsc
-
-.PHONY: tsc-tests
-tsc-tests: node_modules ## Runs type checks for tests in all UI workspaces
-	$(TARGET_HEADER)
-	$(YARN) tsc:tests
-
-.PHONY: tsc-tests-react
-tsc-tests-react: node_modules ## Runs type checks for tests in @modulify/m3-react
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-react tsc:tests
-
-.PHONY: tsc-tests-vue
-tsc-tests-vue: node_modules ## Runs type checks for tests in @modulify/m3-vue
-	$(TARGET_HEADER)
-	$(YARN) workspace @modulify/m3-vue tsc:tests
-
-.PHONY: tsc-e2e
-tsc-e2e: node_modules ## Runs type checks for Playwright Vitest configs
-	$(TARGET_HEADER)
-	$(YARN) exec tsc -p tsconfig.e2e.json --skipLibCheck
-
-.PHONY: test
-test: node_modules ## Runs autotests
-	$(TARGET_HEADER)
-
-ifdef cli
-	@echo "${YARN} test ${cli}"
-	$(YARN) test $(cli)
-else
-	@echo "${YARN} test"
-	$(YARN) test
-endif
-
-.PHONY: test-coverage
-test-coverage: node_modules ## Runs merged coverage for unit and Playwright e2e tests
-	$(TARGET_HEADER)
-	@rm -rf coverage $(NYC_OUTPUT_DIR) artifacts
-	@mkdir -p $(COVERAGE_PARTS_DIR) $(NYC_OUTPUT_DIR)
-	$(YARN) test --coverage --coverage.provider=istanbul --coverage.reporter=json --coverage.reportsDirectory=$(COVERAGE_UNIT_DIR)
-	$(YARN_PLAYWRIGHT) test:e2e:coverage
-	@cp $(COVERAGE_UNIT_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/unit.json
-	@cp $(COVERAGE_E2E_REACT_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/e2e-react.json
-	@cp $(COVERAGE_E2E_VUE_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/e2e-vue.json
-	@$(YARN) nyc merge $(COVERAGE_PARTS_DIR) $(NYC_OUTPUT_DIR)/coverage-final.json >/dev/null
-	$(YARN) nyc report
-	@$(YARN) nyc report --reporter=json-summary >/dev/null
-	@$(YARN) node --experimental-strip-types scripts/show-total-coverage.ts
-
-.PHONY: test-e2e
-test-e2e: node_modules ## Runs Playwright-based e2e tests (Vitest browser mode)
-	$(TARGET_HEADER)
-
-ifdef cli
-	@$(YARN_PLAYWRIGHT) test:e2e $(cli)
-else
-	@$(YARN_PLAYWRIGHT) test:e2e
-endif
-
-.PHONY: test-e2e-react
-test-e2e-react: node_modules ## Runs Playwright-based e2e tests for @modulify/m3-react
-	$(TARGET_HEADER)
-
-ifdef cli
-	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-react test:e2e $(cli)
-else
-	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-react test:e2e
-endif
-
-.PHONY: test-e2e-vue
-test-e2e-vue: node_modules ## Runs Playwright-based e2e tests for @modulify/m3-vue
-	$(TARGET_HEADER)
-
-ifdef cli
-	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-vue test:e2e $(cli)
-else
-	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-vue test:e2e
-endif
-
-.PHONY: test-e2e-stop
-test-e2e-stop: ## Stops stuck Playwright E2E host processes and run containers
-	$(TARGET_HEADER)
-	@pkill -TERM -f "docker-compose run --rm playwright yarn test:[e]2e" || true
-	@pkill -TERM -f "docker-compose run --rm playwright yarn workspace @modulify/m3-react test:[e]2e" || true
-	@pkill -TERM -f "docker-compose run --rm playwright yarn workspace @modulify/m3-vue test:[e]2e" || true
-	@docker ps -q --filter "name=m3-web-playwright-run" | xargs -r docker rm -f
+include recipes/storybook.mk
+include recipes/lint.mk
+include recipes/tests.mk
+include recipes/research.mk
 
 .PHONY: ci-actionlint
-ci-actionlint: ## Lints GitHub Actions workflows locally (actionlint binary or docker image)
+ci-actionlint: ## [CI][docker][lint] Lints GitHub Actions workflows locally (actionlint binary or docker image)
 	$(TARGET_HEADER)
 	@if command -v actionlint >/dev/null 2>&1; then \
 		actionlint; \
@@ -198,7 +66,7 @@ ci-actionlint: ## Lints GitHub Actions workflows locally (actionlint binary or d
 	$(TARGET_OK)
 
 .PHONY: ci-act-plan
-ci-act-plan: ## Shows act execution plan for tests workflow without running jobs
+ci-act-plan: ## [CI][docker] Shows act execution plan for tests workflow without running jobs
 	$(TARGET_HEADER)
 	@if command -v act >/dev/null 2>&1; then \
 		act -P ubuntu-latest=catthehacker/ubuntu:act-latest -n pull_request -W .github/workflows/tests.yml; \
@@ -211,7 +79,7 @@ ci-act-plan: ## Shows act execution plan for tests workflow without running jobs
 	$(TARGET_OK)
 
 .PHONY: ci-act-tests
-ci-act-tests: ## Runs tests workflow locally via act (pr-check, eslint, tests, storybook-tests)
+ci-act-tests: ## [CI][docker][heavy][network] Runs tests workflow locally via act (pr-check, eslint, tests, storybook-tests)
 	$(TARGET_HEADER)
 	@if command -v act >/dev/null 2>&1; then \
 		act -P ubuntu-latest=catthehacker/ubuntu:act-latest pull_request -W .github/workflows/tests.yml -j pr-check -j eslint -j tests -j storybook-tests; \
@@ -224,13 +92,184 @@ ci-act-tests: ## Runs tests workflow locally via act (pr-check, eslint, tests, s
 	$(TARGET_OK)
 
 .PHONY: ci-check
-ci-check: ci-actionlint ci-act-plan ## Validates CI workflow config and prints local act plan
+ci-check: ci-actionlint ci-act-plan ## [CI][alias] Validates CI workflow config and prints local act plan
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/list
+m3/experiment/list: ## [Experiment][safe] Lists experiment-tagged recipes and their purpose
+	@$(MAKE) --no-print-directory help filter=experiment
+
+.PHONY: m3/experiment/list-escalation
+m3/experiment/list-escalation: ## [Experiment][safe] Lists recipes blocked in no-escalation experiment mode
+	@$(MAKE) --no-print-directory help filter='[escalated]'
+
+.PHONY: m3/experiment/list-safe
+m3/experiment/list-safe: ## [Experiment][safe] Lists local-only recipes safe in no-escalation mode
+	@$(MAKE) --no-print-directory help filter='[safe]'
+
+.PHONY: m3/experiment/init
+m3/experiment/init: ## [Experiment][safe] Creates an experiment run directory with standard subfolders
+	$(TARGET_HEADER)
+	@RUN_DIR="$(if $(run_dir),$(run_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S))"; \
+	mkdir -p "$$RUN_DIR"/screenshots "$$RUN_DIR"/fetch "$$RUN_DIR"/notes; \
+	echo "$$RUN_DIR"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/preflight
+m3/experiment/preflight: ## [Experiment][escalated][docker][network] Validates docker/playwright/network prerequisites for long runs
+	$(TARGET_HEADER)
+	@set -e; \
+	command -v jq >/dev/null; \
+	command -v rg >/dev/null; \
+	docker-compose ps >/dev/null; \
+	$(PLAYWRIGHT_NODE_CMD) -e "console.log('playwright node', process.version)"; \
+	curl -fLsS -A "$(M3_UA)" "https://m3.material.io/" -o /dev/null; \
+	echo "preflight:ok"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/bootstrap
+m3/experiment/bootstrap: ## [Experiment][escalated][docker] One-shot setup: list recipes, init run dir, run preflight checks
+	$(TARGET_HEADER)
+	@$(MAKE) --no-print-directory m3/experiment/list
+	@$(MAKE) --no-print-directory m3/experiment/init $(if $(run_dir),run_dir="$(run_dir)",)
+	@$(MAKE) --no-print-directory m3/experiment/preflight
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/bootstrap/evidence
+# Example:
+#   make m3/experiment/bootstrap/evidence pack=surfaces profiles='compact medium expanded'
+m3/experiment/bootstrap/evidence: ## [Experiment][escalated][docker][network][heavy] One-shot privileged bootstrap: preflight + fetch + multi-profile capture
+	$(TARGET_HEADER)
+	@set -e; \
+	RUN_DIR="$(if $(run_dir),$(run_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S))"; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	PROFILES="$(if $(profiles),$(profiles),$(M3_EXPERIMENT_BOOTSTRAP_PROFILES))"; \
+	$(MAKE) --no-print-directory m3/experiment/init run_dir="$$RUN_DIR"; \
+	$(MAKE) --no-print-directory m3/experiment/preflight; \
+	$(MAKE) --no-print-directory m3/experiment/fetch/pack pack="$$PACK" out_dir="$$RUN_DIR/fetch"; \
+	for profile in $$PROFILES; do \
+		$(MAKE) --no-print-directory m3/experiment/capture/pack \
+			pack="$$PACK" \
+			profile="$$profile" \
+			out_dir="$$RUN_DIR/screenshots/$${profile}-$${PACK}" \
+			wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
+			full_page="$(if $(full_page),$(full_page),true)"; \
+	done; \
+	echo "$$RUN_DIR"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/capture/pack
+# Example:
+#   make m3/experiment/capture/pack pack=surfaces profile=compact
+#   make m3/experiment/capture/pack manifest=recipes/research/packs/surfaces.urls.txt profile=expanded
+m3/experiment/capture/pack: ## [Experiment][escalated][docker][playwright] Captures a research URL pack with viewport profile (compact|medium|expanded)
+	$(TARGET_HEADER)
+	@set -e; \
+	PROFILE="$(if $(profile),$(profile),expanded)"; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
+	case "$$PROFILE" in \
+		compact) WIDTH=390; HEIGHT=844 ;; \
+		medium) WIDTH=840; HEIGHT=1080 ;; \
+		expanded) WIDTH=1440; HEIGHT=1024 ;; \
+		*) echo "unsupported profile: $$PROFILE (expected compact|medium|expanded)"; exit 2 ;; \
+	esac; \
+	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/screenshots/$$PROFILE-$${PACK})"; \
+	$(MAKE) --no-print-directory research-capture-batch \
+		manifest="$$MANIFEST" \
+		out_dir="$$OUT_DIR" \
+		width="$$WIDTH" \
+		height="$$HEIGHT" \
+		wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
+		full_page="$(if $(full_page),$(full_page),true)"; \
+	echo "$$OUT_DIR"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/capture/urls-file
+m3/experiment/capture/urls-file: ## [Experiment][escalated][docker][playwright] Captures URLs from a file with viewport profile (compact|medium|expanded)
+	$(TARGET_HEADER)
+	@if [ -z "$(in)" ]; then echo "usage: make m3/experiment/capture/urls-file in=$(M3_EXPERIMENT_URLS_DIR)/<pack>.txt [profile=compact|medium|expanded] [out_dir=...]"; exit 2; fi
+	@set -e; \
+	PROFILE="$(if $(profile),$(profile),expanded)"; \
+	case "$$PROFILE" in \
+		compact) WIDTH=390; HEIGHT=844 ;; \
+		medium) WIDTH=840; HEIGHT=1080 ;; \
+		expanded) WIDTH=1440; HEIGHT=1024 ;; \
+		*) echo "unsupported profile: $$PROFILE (expected compact|medium|expanded)"; exit 2 ;; \
+	esac; \
+	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/screenshots/$$PROFILE)"; \
+	$(MAKE) --no-print-directory research-capture-batch \
+		in="$(in)" \
+		out_dir="$$OUT_DIR" \
+		width="$$WIDTH" \
+		height="$$HEIGHT" \
+		wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
+		full_page="$(if $(full_page),$(full_page),true)" \
+		$(if $(wait_selector),wait_selector="$(wait_selector)",); \
+	echo "$$OUT_DIR"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/fetch/pack
+# Example:
+#   make m3/experiment/fetch/pack pack=surfaces out_dir=drafts/experiment/run-1/fetch
+#   make m3/experiment/fetch/pack manifest=recipes/research/packs/surfaces.page-data.tsv
+m3/experiment/fetch/pack: ## [Experiment][escalated][network][fetch] Fetches a research page-data pack into an experiment run directory
+	$(TARGET_HEADER)
+	@set -e; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.page-data.tsv)"; \
+	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/fetch)"; \
+	mkdir -p "$$OUT_DIR"; \
+	$(MAKE) --no-print-directory research-fetch-batch format=json manifest="$$MANIFEST" out_dir="$$OUT_DIR"; \
+	echo "$$OUT_DIR"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/urls-template
+# Example:
+#   make m3/experiment/urls-template pack=surfaces
+#   make m3/experiment/urls-template manifest=recipes/research/packs/surfaces.urls.txt out=drafts/experiment/urls/custom.txt
+m3/experiment/urls-template: ## [Experiment][safe] Creates a starter URL list for batch captures from a research pack
+	$(TARGET_HEADER)
+	@set -e; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
+	OUT="$(if $(out),$(out),$(M3_EXPERIMENT_URLS_DIR)/$${PACK}.txt)"; \
+	mkdir -p "$$(dirname "$$OUT")"; \
+	cp "$$MANIFEST" "$$OUT"; \
+	echo "$$OUT"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/manifest
+m3/experiment/manifest: ## [Experiment][safe] Prints recommended order for a long experiment run
+	$(TARGET_HEADER)
+	@printf '%s\n' \
+		"1) make m3/experiment/list && make m3/experiment/list-escalation" \
+		"2) (if sanctioned) make m3/experiment/bootstrap/evidence [pack=surfaces] [run_dir=...] [profiles='compact medium expanded']" \
+		"3) switch to no-escalation mode and keep only local analysis" \
+		"4) make m3/experiment/analyze/local-summary run_dir=..." \
+		"5) continue milestones/decisions based on local artifacts"
+	$(TARGET_OK)
+
+.PHONY: m3/experiment/analyze/local-summary
+m3/experiment/analyze/local-summary: ## [Experiment][safe] Prints local artifact summary for a completed/ongoing run (no escalation)
+	$(TARGET_HEADER)
+	@if [ -z "$(run_dir)" ]; then echo "usage: make m3/experiment/analyze/local-summary run_dir=drafts/experiment/runs/<id>"; exit 2; fi
+	@set -e; \
+	FETCH_DIR="$(run_dir)/fetch"; \
+	SCREEN_DIR="$(run_dir)/screenshots"; \
+	FETCH_COUNT=$$(find "$$FETCH_DIR" -maxdepth 1 -type f -name '*.json' 2>/dev/null | wc -l); \
+	echo "fetch_json=$$FETCH_COUNT"; \
+	find "$$SCREEN_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort | while IFS= read -r dir; do \
+		name="$$(basename "$$dir")"; \
+		META_COUNT=$$(find "$$dir" -maxdepth 1 -type f -name '*.meta.json' 2>/dev/null | wc -l); \
+		PNG_COUNT=$$(find "$$dir" -maxdepth 1 -type f -name '*.png' 2>/dev/null | wc -l); \
+		echo "$$name: png=$$PNG_COUNT meta=$$META_COUNT"; \
+	done
 	$(TARGET_OK)
 
 .PHONY: help
-help: ## Calls recipes list
-	@cat $(MAKEFILE_LIST) | grep -e "^[-a-zA-Z_\.]*: *.*## *" | awk '\
-            BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+help: ## [General] Shows grouped command help
+	@HELP_FILTER="$(value filter)" HELP_SHOW_INTERNAL="$(value show_internal)" ./recipes/help.sh $(MAKEFILE_LIST)
 
 # Colors
 $(call computable,CC_BLACK,$(shell tput -Txterm setaf 0 2>/dev/null))
diff --git a/recipes/common.mk b/recipes/common.mk
new file mode 100644
index 0000000..8b4bca6
--- /dev/null
+++ b/recipes/common.mk
@@ -0,0 +1,19 @@
+ifndef RECIPES_COMMON_MK_INCLUDED
+RECIPES_COMMON_MK_INCLUDED := 1
+
+.PHONY: .yarnrc.yml
+.yarnrc.yml: ## [Setup][local] Creates yarn configuration
+	@cp .yarnrc.yml.dist .yarnrc.yml
+
+.PHONY: node_modules
+node_modules: package.json yarn.lock ## [Setup][docker][heavy] Installs dependencies
+	$(TARGET_HEADER)
+	$(YARN) install
+	@touch node_modules || true
+	@echo ""
+
+.PHONY: husky
+husky: node_modules ## [Setup][docker][git] Adds husky git hooks with commit content checks
+	@docker-compose run --rm node npx husky init
+
+endif
diff --git a/recipes/help.sh b/recipes/help.sh
new file mode 100755
index 0000000..85bd75d
--- /dev/null
+++ b/recipes/help.sh
@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+	set -- Makefile
+fi
+
+declare -A seen_files=()
+unique_files=()
+
+for file in "$@"; do
+	if [ -n "${seen_files[$file]:-}" ]; then
+		continue
+	fi
+	seen_files["$file"]=1
+	unique_files+=("$file")
+done
+
+set -- "${unique_files[@]}"
+
+if [ -t 1 ] && [ -z "${CI:-}" ] && [ -z "${NO_COLOR:-}" ]; then
+	C_HEAD="$(printf '\033[1;37m')"
+	C_TGT="$(printf '\033[34m')"
+	C_TAG="$(printf '\033[90m')"
+	C_WARN="$(printf '\033[33m')"
+	C_RST="$(printf '\033[0m')"
+else
+	C_HEAD=''
+	C_TGT=''
+	C_TAG=''
+	C_WARN=''
+	C_RST=''
+fi
+
+FILTER="$(printf '%s' "${HELP_FILTER:-}" | tr '[:upper:]' '[:lower:]')"
+SHOW_INTERNAL="${HELP_SHOW_INTERNAL:-}"
+TAB="$(printf '\t')"
+
+entries="$(
+	awk -v filter="$FILTER" -v show_internal="$SHOW_INTERNAL" '
+		function trim(s){ sub(/^[ \t\r\n]+/, "", s); sub(/[ \t\r\n]+$/, "", s); return s }
+		function group_order(g){
+			if (g=="General") return 1;
+			if (g=="Setup") return 2;
+			if (g=="Dev") return 3;
+			if (g=="Build") return 4;
+			if (g=="Quality") return 5;
+			if (g=="Tests") return 6;
+			if (g=="CI") return 7;
+			if (g=="Research") return 8;
+			if (g=="Experiment") return 9;
+			return 99;
+		}
+		/^[a-zA-Z0-9_./-]+:.*##[[:space:]]+/ {
+			target = $1; sub(/:.*/, "", target);
+			if (show_internal != "1" && target ~ /^\./) next;
+			desc = $0; sub(/^.*##[[:space:]]*/, "", desc);
+			group = "Other"; tags = "";
+			if (match(desc, /^\[[^]]+\]/)) {
+				group = substr(desc, 2, RLENGTH - 2);
+				desc = substr(desc, RLENGTH + 1);
+			}
+			while (match(desc, /^[[:space:]]*\[[^]]+\]/)) {
+				sub(/^[[:space:]]*/, "", desc);
+				rb = index(desc, "]");
+				if (rb == 0) break;
+				tags = tags "[" substr(desc, 2, rb - 2) "]";
+				desc = substr(desc, rb + 1);
+			}
+			desc = trim(desc);
+			hay = tolower(target " " group " " tags " " desc);
+			if (filter != "" && index(hay, filter) == 0) next;
+			printf "%02d\t%s\t%s\t%s\t%s\n", group_order(group), group, target, tags, desc;
+		}
+	' "$@" | sort -t "$TAB" -k1,1n -k3,3
+)"
+
+if [ -n "$entries" ]; then
+	printf '%s\n' "$entries" | awk -F "$TAB" -v c_head="$C_HEAD" -v c_tgt="$C_TGT" -v c_tag="$C_TAG" -v c_rst="$C_RST" '
+		{
+			rows[NR] = $0;
+			if (length($3) > width) width = length($3);
+		}
+		END {
+			current = "";
+			for (i = 1; i <= NR; i++) {
+				split(rows[i], cols, FS);
+				if (cols[2] != current) {
+					if (current != "") print "";
+					printf "%s%s%s\n", c_head, cols[2], c_rst;
+					current = cols[2];
+				}
+				printf "  %s%-*s%s %s", c_tgt, width, cols[3], c_rst, cols[5];
+				if (cols[4] != "") printf " %s%s%s", c_tag, cols[4], c_rst;
+				printf "\n";
+			}
+		}
+	'
+else
+	printf 'No targets matched the current filter.\n'
+fi
+
+printf '\n'
+printf '%sQuick Start%s\n' "$C_HEAD" "$C_RST"
+printf '  make up\n'
+printf '  make test\n'
+printf '  make eslint\n'
+printf '  make help filter=experiment\n'
+
+printf '\n'
+printf '%sExamples%s\n' "$C_HEAD" "$C_RST"
+printf '  make help filter=playwright\n'
+printf "  make help filter='[safe]'\n"
+printf '  make help show_internal=1\n'
+printf "  make test cli='m3-react'\n"
+
+dup_targets="$(
+	awk -F: '/^[a-zA-Z0-9_./-]+:/ && $1 != ".PHONY" { print $1 }' "$@" | sort | uniq -d | tr '\n' ' '
+)"
+dup_phony="$(
+	awk '/^\.PHONY:[[:space:]]*/ { for (i = 2; i <= NF; i++) print $i }' "$@" | sort | uniq -d | tr '\n' ' '
+)"
+
+if [ -n "$dup_targets$dup_phony" ]; then
+	printf '\n'
+	printf '%sWarnings%s\n' "$C_WARN" "$C_RST"
+	if [ -n "$dup_targets" ]; then
+		printf '  duplicate targets: %s\n' "$dup_targets"
+	fi
+	if [ -n "$dup_phony" ]; then
+		printf '  duplicate .PHONY entries: %s\n' "$dup_phony"
+	fi
+fi
diff --git a/recipes/lint.mk b/recipes/lint.mk
new file mode 100644
index 0000000..c70a357
--- /dev/null
+++ b/recipes/lint.mk
@@ -0,0 +1,46 @@
+include recipes/common.mk
+
+.PHONY: eslint
+eslint: node_modules ## [Quality][docker][lint] Runs eslint
+	$(TARGET_HEADER)
+	$(YARN) eslint
+
+.PHONY: tsc
+tsc: node_modules ## [Quality][docker][types] Runs type checks in all workspaces
+	$(TARGET_HEADER)
+	$(YARN) tsc
+
+.PHONY: tsc-foundation
+tsc-foundation: node_modules ## [Quality][docker][types] Runs type checks in @modulify/m3-foundation
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-foundation tsc
+
+.PHONY: tsc-react
+tsc-react: node_modules ## [Quality][docker][types] Runs type checks in @modulify/m3-react
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-react tsc
+
+.PHONY: tsc-vue
+tsc-vue: node_modules ## [Quality][docker][types] Runs type checks in @modulify/m3-vue
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-vue tsc
+
+.PHONY: tsc-tests
+tsc-tests: node_modules ## [Quality][docker][types] Runs type checks for tests in all UI workspaces
+	$(TARGET_HEADER)
+	$(YARN) tsc:tests
+
+.PHONY: tsc-tests-react
+tsc-tests-react: node_modules ## [Quality][docker][types] Runs type checks for tests in @modulify/m3-react
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-react tsc:tests
+
+.PHONY: tsc-tests-vue
+tsc-tests-vue: node_modules ## [Quality][docker][types] Runs type checks for tests in @modulify/m3-vue
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-vue tsc:tests
+
+.PHONY: tsc-e2e
+tsc-e2e: node_modules ## [Quality][docker][types] Runs type checks for Playwright Vitest configs
+	$(TARGET_HEADER)
+	$(YARN) exec tsc -p tsconfig.e2e.json --skipLibCheck
diff --git a/recipes/research.mk b/recipes/research.mk
new file mode 100644
index 0000000..405ad46
--- /dev/null
+++ b/recipes/research.mk
@@ -0,0 +1,90 @@
+# Example:
+#   make research-fetch url='https://m3.material.io/'
+#   make research-fetch format=json collection=ComponentsM3 document=5634981699387392
+.PHONY: research-fetch
+research-fetch: ## [Research][network][fetch] Fetches a raw URL or page-data JSON (set format=json with collection/document)
+	$(TARGET_HEADER)
+	@M3_UA='$(M3_UA)' M3_FETCH_OUT_DIR='$(M3_FETCH_OUT_DIR)' ./recipes/research/fetch.sh \
+		--format "$(if $(format),$(format),raw)" \
+		$(if $(url),--url "$(url)",) \
+		$(if $(collection),--collection "$(collection)",) \
+		$(if $(document),--document "$(document)",) \
+		$(if $(out),--out "$(out)",)
+	$(TARGET_OK)
+
+# Example:
+#   make research-fetch-batch format=json manifest=recipes/research/packs/surfaces.page-data.tsv out_dir=/tmp/m3-research
+# Manifest format for format=json:
+#   <slug>\t<collection>\t<document_id>
+.PHONY: research-fetch-batch
+research-fetch-batch: ## [Research][network][fetch] Fetches a batch by format; use format=json for page-data TSV manifests
+	$(TARGET_HEADER)
+	@M3_UA='$(M3_UA)' M3_FETCH_OUT_DIR='$(M3_FETCH_OUT_DIR)' ./recipes/research/fetch.sh \
+		--format "$(if $(format),$(format),json)" \
+		--manifest "$(manifest)" \
+		$(if $(out_dir),--out-dir "$(out_dir)",)
+	$(TARGET_OK)
+
+.PHONY: research-inspect
+research-inspect: ## [Research][inspect] Prints quick summary for page-data JSON (requires: in)
+	$(TARGET_HEADER)
+	@if [ -z "$(in)" ]; then echo "usage: make research-inspect in=/tmp/page.json"; exit 2; fi
+	@jq -r '"title=\(.title // "")", "document_id=\(.document_id // "")", "modified_date=\(.modified_date // "")", "mdc_android_markdown_len=\((.mdc_android.markdown_content // "" | length))", "jetpack_markdown_len=\((.jetpack.markdown_content // "" | length))", "mdc_web_markdown_len=\((.mdc_web.markdown_content // "" | length))"' "$(in)"
+	$(TARGET_OK)
+
+.PHONY: research-extract-markdown
+research-extract-markdown: ## [Research][extract] Extracts markdown_content from page-data JSON (requires: in, optional: platform, out)
+	$(TARGET_HEADER)
+	@if [ -z "$(in)" ]; then echo "usage: make research-extract-markdown in=/tmp/page.json [platform=mdc_android] [out=/tmp/page.md]"; exit 2; fi
+	@PLATFORM="$(if $(platform),$(platform),mdc_android)"; \
+	OUT="$(if $(out),$(out),$(M3_FETCH_OUT_DIR)/$$(basename "$(in)" .json)_$${PLATFORM}.md)"; \
+	mkdir -p "$$(dirname "$$OUT")"; \
+	jq -r --arg p "$$PLATFORM" '.[$$p].markdown_content // ""' "$(in)" > "$$OUT"; \
+	echo "$$OUT"
+	$(TARGET_OK)
+
+.PHONY: research-extract-search-snippets
+research-extract-search-snippets: ## [Research][extract][search] Prints title/link/snippet from saved custom-search JSON (requires: in, optional: filter)
+	$(TARGET_HEADER)
+	@if [ -z "$(in)" ]; then echo "usage: make research-extract-search-snippets in=/tmp/search.json [filter='side-sheets|menus']"; exit 2; fi
+	@if [ -n "$(filter)" ]; then \
+		jq -r '.items[] | "TITLE: \(.title)\nLINK: \(.link)\nSNIPPET: \(.snippet)\n---"' "$(in)" | rg -n "$(filter)|TITLE:|LINK:|SNIPPET:"; \
+	else \
+		jq -r '.items[] | "TITLE: \(.title)\nLINK: \(.link)\nSNIPPET: \(.snippet)\n---"' "$(in)"; \
+	fi
+	$(TARGET_OK)
+
+.PHONY: research-capture
+research-capture: ## [Research][docker][playwright][capture] Captures screenshot+meta via Playwright (requires: url, optional: out/out_dir/wait_ms/wait_selector/width/height/full_page/wait_until)
+	$(TARGET_HEADER)
+	@PLAYWRIGHT_NODE_CMD='$(PLAYWRIGHT_NODE_CMD)' ./recipes/research/capture.sh \
+		--url "$(url)" \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(full_page),--full-page "$(full_page)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+# Example:
+#   make research-capture-batch manifest=recipes/research/packs/surfaces.urls.txt out_dir=drafts/screenshots/surfaces
+#   make research-capture-batch in=drafts/experiment/urls/surfaces.txt out_dir=drafts/screenshots/custom
+# Input format:
+#   One URL per line; empty lines and #comments are ignored.
+.PHONY: research-capture-batch
+research-capture-batch: ## [Research][docker][playwright][capture] Captures screenshots from a URL manifest or input file
+	$(TARGET_HEADER)
+	@PLAYWRIGHT_NODE_CMD='$(PLAYWRIGHT_NODE_CMD)' ./recipes/research/capture.sh \
+		$(if $(manifest),--manifest "$(manifest)",) \
+		$(if $(in),--in "$(in)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(full_page),--full-page "$(full_page)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
diff --git a/recipes/research/capture.sh b/recipes/research/capture.sh
new file mode 100755
index 0000000..c3e2927
--- /dev/null
+++ b/recipes/research/capture.sh
@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+	printf '%s\n' \
+		"usage:" \
+		"  recipes/research/capture.sh --url https://... [--out path.png] [--out-dir dir]" \
+		"  recipes/research/capture.sh --manifest recipes/research/packs/<pack>.urls.txt [--out-dir dir]" \
+		"  recipes/research/capture.sh --in drafts/urls.txt [--out-dir dir]" \
+		"" \
+		"options:" \
+		"  --url URL              capture one URL; may be repeated for batch mode" \
+		"  --manifest FILE        URL manifest file (one URL per line)" \
+		"  --in FILE              arbitrary URL file (one URL per line)" \
+		"  --out FILE             output path for single-URL mode only" \
+		"  --out-dir DIR          output directory for generated images/meta" \
+		"  --width PX             viewport width (default: 1440)" \
+		"  --height PX            viewport height (default: 1024)" \
+		"  --wait-ms MS           extra wait before screenshot (default: 1200)" \
+		"  --wait-until STATE     Playwright waitUntil (default: networkidle)" \
+		"  --full-page BOOL       full-page screenshot flag (default: true)" \
+		"  --wait-selector CSS    optional selector to wait for before capture"
+}
+
+node_cmd_string="${PLAYWRIGHT_NODE_CMD:-docker-compose run --rm playwright node}"
+read -r -a node_cmd <<< "$node_cmd_string"
+
+urls=()
+input_file=''
+manifest_file=''
+out=''
+out_dir=''
+width='1440'
+height='1024'
+wait_ms='1200'
+wait_until='networkidle'
+full_page='true'
+wait_selector=''
+
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+		--url)
+			[ "$#" -ge 2 ] || { echo "missing value for --url" >&2; usage >&2; exit 2; }
+			urls+=("$2")
+			shift 2
+			;;
+		--in)
+			[ "$#" -ge 2 ] || { echo "missing value for --in" >&2; usage >&2; exit 2; }
+			input_file="$2"
+			shift 2
+			;;
+		--manifest)
+			[ "$#" -ge 2 ] || { echo "missing value for --manifest" >&2; usage >&2; exit 2; }
+			manifest_file="$2"
+			shift 2
+			;;
+		--out)
+			[ "$#" -ge 2 ] || { echo "missing value for --out" >&2; usage >&2; exit 2; }
+			out="$2"
+			shift 2
+			;;
+		--out-dir)
+			[ "$#" -ge 2 ] || { echo "missing value for --out-dir" >&2; usage >&2; exit 2; }
+			out_dir="$2"
+			shift 2
+			;;
+		--width)
+			[ "$#" -ge 2 ] || { echo "missing value for --width" >&2; usage >&2; exit 2; }
+			width="$2"
+			shift 2
+			;;
+		--height)
+			[ "$#" -ge 2 ] || { echo "missing value for --height" >&2; usage >&2; exit 2; }
+			height="$2"
+			shift 2
+			;;
+		--wait-ms)
+			[ "$#" -ge 2 ] || { echo "missing value for --wait-ms" >&2; usage >&2; exit 2; }
+			wait_ms="$2"
+			shift 2
+			;;
+		--wait-until)
+			[ "$#" -ge 2 ] || { echo "missing value for --wait-until" >&2; usage >&2; exit 2; }
+			wait_until="$2"
+			shift 2
+			;;
+		--full-page)
+			[ "$#" -ge 2 ] || { echo "missing value for --full-page" >&2; usage >&2; exit 2; }
+			full_page="$2"
+			shift 2
+			;;
+		--wait-selector)
+			[ "$#" -ge 2 ] || { echo "missing value for --wait-selector" >&2; usage >&2; exit 2; }
+			wait_selector="$2"
+			shift 2
+			;;
+		-h|--help)
+			usage
+			exit 0
+			;;
+		*)
+			echo "unknown argument: $1" >&2
+			usage >&2
+			exit 2
+			;;
+	esac
+done
+
+source_modes=0
+[ "${#urls[@]}" -gt 0 ] && source_modes=$((source_modes + 1))
+[ -n "$input_file" ] && source_modes=$((source_modes + 1))
+[ -n "$manifest_file" ] && source_modes=$((source_modes + 1))
+
+if [ "$source_modes" -eq 0 ]; then
+	echo "expected one source: --url, --in, or --manifest" >&2
+	usage >&2
+	exit 2
+fi
+
+if [ "$source_modes" -gt 1 ]; then
+	echo "use exactly one source mode: --url, --in, or --manifest" >&2
+	usage >&2
+	exit 2
+fi
+
+if [ -n "$input_file" ] && [ ! -f "$input_file" ]; then
+	echo "input file not found: $input_file" >&2
+	exit 2
+fi
+
+if [ -n "$manifest_file" ] && [ ! -f "$manifest_file" ]; then
+	echo "manifest file not found: $manifest_file" >&2
+	exit 2
+fi
+
+if [ -n "$out" ] && [ "${#urls[@]}" -ne 1 ]; then
+	echo "--out is supported only with a single --url" >&2
+	exit 2
+fi
+
+capture_one() {
+	local url="$1"
+	local -a cmd=("${node_cmd[@]}" "scripts/playwright-capture.mjs" "--url" "$url" "--width" "$width" "--height" "$height" "--wait-ms" "$wait_ms" "--wait-until" "$wait_until" "--full-page" "$full_page")
+
+	if [ -n "$out" ]; then
+		cmd+=("--out" "$out")
+	elif [ -n "$out_dir" ]; then
+		cmd+=("--out-dir" "$out_dir")
+	fi
+
+	if [ -n "$wait_selector" ]; then
+		cmd+=("--wait-selector" "$wait_selector")
+	fi
+
+	"${cmd[@]}"
+}
+
+collect_file_urls() {
+	local file="$1"
+	local line
+	while IFS= read -r line; do
+		[ -z "$line" ] && continue
+		case "$line" in
+			\#*) continue ;;
+		esac
+		urls+=("$line")
+	done < "$file"
+}
+
+if [ -n "$input_file" ]; then
+	collect_file_urls "$input_file"
+elif [ -n "$manifest_file" ]; then
+	collect_file_urls "$manifest_file"
+fi
+
+if [ "${#urls[@]}" -eq 0 ]; then
+	echo "no URLs found to capture" >&2
+	exit 2
+fi
+
+if [ "${#urls[@]}" -gt 1 ] && [ -n "$out" ]; then
+	echo "--out cannot be used for multi-URL capture" >&2
+	exit 2
+fi
+
+if [ -z "$out_dir" ] && [ -z "$out" ]; then
+	source_name="${manifest_file:-$input_file}"
+	if [ -n "$source_name" ]; then
+		pack_name="$(basename "$source_name")"
+		pack_name="${pack_name%.urls.txt}"
+		pack_name="${pack_name%.txt}"
+		out_dir="drafts/screenshots/${pack_name}-$(date +%Y%m%d-%H%M%S)"
+	elif [ "${#urls[@]}" -gt 1 ]; then
+		out_dir="drafts/screenshots/capture-batch-$(date +%Y%m%d-%H%M%S)"
+	fi
+fi
+
+for url in "${urls[@]}"; do
+	capture_one "$url"
+done
+
+if [ "${#urls[@]}" -gt 1 ] || [ -n "$input_file" ] || [ -n "$manifest_file" ]; then
+	if [ -n "$out_dir" ]; then
+		echo "$out_dir"
+	fi
+fi
diff --git a/recipes/research/fetch.sh b/recipes/research/fetch.sh
new file mode 100755
index 0000000..7ac63e3
--- /dev/null
+++ b/recipes/research/fetch.sh
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+	printf '%s\n' \
+		"usage:" \
+		"  recipes/research/fetch.sh --format raw --url https://... [--out file]" \
+		"  recipes/research/fetch.sh --format json --collection ComponentsM3 --document 5634981699387392 [--out file.json]" \
+		"  recipes/research/fetch.sh --format json --manifest recipes/research/packs/<pack>.page-data.tsv [--out-dir dir]" \
+		"" \
+		"options:" \
+		"  --format VALUE         fetch format: raw or json" \
+		"  --manifest FILE        TSV manifest for format=json: <slug><TAB><collection><TAB><document_id>" \
+		"  --collection VALUE     page-data collection name" \
+		"  --document VALUE       page-data document id" \
+		"  --url URL              arbitrary URL for format=raw" \
+		"  --out FILE             explicit output file path" \
+		"  --out-dir DIR          output directory for manifest mode" \
+		"  --user-agent VALUE     override HTTP user agent"
+}
+
+user_agent="${M3_UA:-m3-web-research/1.0}"
+fetch_root="${M3_FETCH_OUT_DIR:-/tmp/m3-fetch}"
+format='raw'
+manifest_file=''
+collection=''
+document=''
+url=''
+out=''
+out_dir=''
+
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+		--format)
+			[ "$#" -ge 2 ] || { echo "missing value for --format" >&2; usage >&2; exit 2; }
+			format="$2"
+			shift 2
+			;;
+		--manifest)
+			[ "$#" -ge 2 ] || { echo "missing value for --manifest" >&2; usage >&2; exit 2; }
+			manifest_file="$2"
+			shift 2
+			;;
+		--collection)
+			[ "$#" -ge 2 ] || { echo "missing value for --collection" >&2; usage >&2; exit 2; }
+			collection="$2"
+			shift 2
+			;;
+		--document)
+			[ "$#" -ge 2 ] || { echo "missing value for --document" >&2; usage >&2; exit 2; }
+			document="$2"
+			shift 2
+			;;
+		--url)
+			[ "$#" -ge 2 ] || { echo "missing value for --url" >&2; usage >&2; exit 2; }
+			url="$2"
+			shift 2
+			;;
+		--out)
+			[ "$#" -ge 2 ] || { echo "missing value for --out" >&2; usage >&2; exit 2; }
+			out="$2"
+			shift 2
+			;;
+		--out-dir)
+			[ "$#" -ge 2 ] || { echo "missing value for --out-dir" >&2; usage >&2; exit 2; }
+			out_dir="$2"
+			shift 2
+			;;
+		--user-agent)
+			[ "$#" -ge 2 ] || { echo "missing value for --user-agent" >&2; usage >&2; exit 2; }
+			user_agent="$2"
+			shift 2
+			;;
+		-h|--help)
+			usage
+			exit 0
+			;;
+		*)
+			echo "unknown argument: $1" >&2
+			usage >&2
+			exit 2
+			;;
+	esac
+done
+
+case "$format" in
+	raw|json) ;;
+	*)
+		echo "unsupported --format: $format (expected raw or json)" >&2
+		usage >&2
+		exit 2
+		;;
+esac
+
+fetch_to_file() {
+	local source_url="$1"
+	local output_path="$2"
+	mkdir -p "$(dirname "$output_path")"
+	curl -fLsS -A "$user_agent" "$source_url" -o "$output_path"
+	printf '%s\n' "$output_path"
+}
+
+if [ "$format" = "raw" ]; then
+	if [ -n "$manifest_file" ] || [ -n "$collection" ] || [ -n "$document" ]; then
+		echo "format=raw only supports --url" >&2
+		usage >&2
+		exit 2
+	fi
+	if [ -z "$url" ]; then
+		echo "format=raw requires --url" >&2
+		usage >&2
+		exit 2
+	fi
+	output_path="${out:-$fetch_root/raw-response.txt}"
+	fetch_to_file "$url" "$output_path"
+	exit 0
+fi
+
+if [ -n "$url" ] && { [ -n "$manifest_file" ] || [ -n "$collection" ] || [ -n "$document" ]; }; then
+	echo "format=json does not support combining --url with page-data options" >&2
+	usage >&2
+	exit 2
+fi
+
+if [ -n "$manifest_file" ]; then
+	[ -f "$manifest_file" ] || { echo "manifest file not found: $manifest_file" >&2; exit 2; }
+	[ -z "$out" ] || { echo "--out is not supported with --manifest; use --out-dir" >&2; exit 2; }
+	output_dir="${out_dir:-$fetch_root}"
+	mkdir -p "$output_dir"
+	while IFS="$(printf '\t')" read -r slug manifest_collection manifest_document; do
+		[ -z "$slug" ] && continue
+		case "$slug" in
+			\#*) continue ;;
+		esac
+		if [ -z "$manifest_collection" ] || [ -z "$manifest_document" ]; then
+			echo "invalid manifest row in $manifest_file: $slug" >&2
+			exit 2
+		fi
+		fetch_to_file "https://m3.material.io/page-data/$manifest_collection/$manifest_document.json" "$output_dir/$slug.json" >/dev/null
+	done < "$manifest_file"
+	printf '%s\n' "$output_dir"
+	exit 0
+fi
+
+if [ -z "$collection" ] || [ -z "$document" ]; then
+	echo "format=json requires either --manifest or both --collection and --document" >&2
+	usage >&2
+	exit 2
+fi
+
+output_path="${out:-$fetch_root/page-data_${collection}_${document}.json}"
+fetch_to_file "https://m3.material.io/page-data/$collection/$document.json" "$output_path"
diff --git a/recipes/research/packs/surfaces.page-data.tsv b/recipes/research/packs/surfaces.page-data.tsv
new file mode 100644
index 0000000..a451aef
--- /dev/null
+++ b/recipes/research/packs/surfaces.page-data.tsv
@@ -0,0 +1,9 @@
+# slug	collection	document_id
+menus	ComponentsM3	4984542628413440
+bottom-sheets	ComponentsM3	5317529291587584
+navigation-drawer	ComponentsM3	5584597953544192
+side-sheets	ComponentsM3	5634981699387392
+dialogs	ComponentsM3	5732087063379968
+layout-applying	GuidelinesM3	6396979944620032
+motion-transitions	GuidelinesM3	4701069397590016
+motion-easing-duration	GuidelinesM3	5485575272529920
diff --git a/recipes/research/packs/surfaces.urls.txt b/recipes/research/packs/surfaces.urls.txt
new file mode 100644
index 0000000..925124b
--- /dev/null
+++ b/recipes/research/packs/surfaces.urls.txt
@@ -0,0 +1,9 @@
+# One URL per line. Empty lines and #comments are ignored.
+https://m3.material.io/components/dialogs/overview
+https://m3.material.io/components/menus/guidelines
+https://m3.material.io/components/bottom-sheets/guidelines
+https://m3.material.io/components/side-sheets/overview
+https://m3.material.io/components/side-sheets/guidelines
+https://m3.material.io/components/navigation-drawer/guidelines
+https://m3.material.io/styles/motion/transitions
+https://m3.material.io/foundations/layout/applying-layout
diff --git a/recipes/storybook.mk b/recipes/storybook.mk
new file mode 100644
index 0000000..4d3ec09
--- /dev/null
+++ b/recipes/storybook.mk
@@ -0,0 +1,17 @@
+include recipes/common.mk
+
+.PHONY: storybook-build-test
+storybook-build-test: node_modules ## [Build][docker][storybook] Builds Storybook in --test mode for all UI workspaces
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-react storybook:build --test --quiet
+	$(YARN) workspace @modulify/m3-vue storybook:build --test --quiet
+
+.PHONY: storybook-build-test-react
+storybook-build-test-react: node_modules ## [Build][docker][storybook] Builds Storybook in --test mode for @modulify/m3-react
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-react storybook:build --test --quiet
+
+.PHONY: storybook-build-test-vue
+storybook-build-test-vue: node_modules ## [Build][docker][storybook] Builds Storybook in --test mode for @modulify/m3-vue
+	$(TARGET_HEADER)
+	$(YARN) workspace @modulify/m3-vue storybook:build --test --quiet
diff --git a/recipes/tests.mk b/recipes/tests.mk
new file mode 100644
index 0000000..7c36431
--- /dev/null
+++ b/recipes/tests.mk
@@ -0,0 +1,76 @@
+include recipes/common.mk
+
+.PHONY: test-smoke
+test-smoke: node_modules ## [Tests][docker][smoke] Runs smoke tests for all UI workspaces
+	$(TARGET_HEADER)
+	$(YARN) test:smoke
+
+.PHONY: test-runtime-parity
+test-runtime-parity: ## [Tests][local] Checks Node/Yarn parity across docker services (node, storybook, playwright)
+	$(TARGET_HEADER)
+	./runtime-parity.test.sh
+
+.PHONY: test
+test: node_modules ## [Tests][docker] Runs autotests
+	$(TARGET_HEADER)
+
+ifdef cli
+	@echo "${YARN} test ${cli}"
+	$(YARN) test $(cli)
+else
+	@echo "${YARN} test"
+	$(YARN) test
+endif
+
+.PHONY: test-coverage
+test-coverage: node_modules ## [Tests][docker][coverage][heavy] Runs merged coverage for unit and Playwright e2e tests
+	$(TARGET_HEADER)
+	@rm -rf coverage $(NYC_OUTPUT_DIR) artifacts
+	@mkdir -p $(COVERAGE_PARTS_DIR) $(NYC_OUTPUT_DIR)
+	$(YARN) test --coverage --coverage.provider=istanbul --coverage.reporter=json --coverage.reportsDirectory=$(COVERAGE_UNIT_DIR)
+	$(YARN_PLAYWRIGHT) test:e2e:coverage
+	@cp $(COVERAGE_UNIT_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/unit.json
+	@cp $(COVERAGE_E2E_REACT_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/e2e-react.json
+	@cp $(COVERAGE_E2E_VUE_DIR)/coverage-final.json $(COVERAGE_PARTS_DIR)/e2e-vue.json
+	@$(YARN) nyc merge $(COVERAGE_PARTS_DIR) $(NYC_OUTPUT_DIR)/coverage-final.json >/dev/null
+	$(YARN) nyc report
+	@$(YARN) nyc report --reporter=json-summary >/dev/null
+	@$(YARN) node --experimental-strip-types scripts/show-total-coverage.ts
+
+.PHONY: test-e2e
+test-e2e: node_modules ## [Tests][docker][e2e][playwright] Runs Playwright-based e2e tests (Vitest browser mode)
+	$(TARGET_HEADER)
+
+ifdef cli
+	@$(YARN_PLAYWRIGHT) test:e2e $(cli)
+else
+	@$(YARN_PLAYWRIGHT) test:e2e
+endif
+
+.PHONY: test-e2e-react
+test-e2e-react: node_modules ## [Tests][docker][e2e][playwright] Runs Playwright-based e2e tests for @modulify/m3-react
+	$(TARGET_HEADER)
+
+ifdef cli
+	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-react test:e2e $(cli)
+else
+	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-react test:e2e
+endif
+
+.PHONY: test-e2e-vue
+test-e2e-vue: node_modules ## [Tests][docker][e2e][playwright] Runs Playwright-based e2e tests for @modulify/m3-vue
+	$(TARGET_HEADER)
+
+ifdef cli
+	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-vue test:e2e $(cli)
+else
+	@$(YARN_PLAYWRIGHT) workspace @modulify/m3-vue test:e2e
+endif
+
+.PHONY: test-e2e-stop
+test-e2e-stop: ## [Tests][local][cleanup] Stops stuck Playwright E2E host processes and run containers
+	$(TARGET_HEADER)
+	@pkill -TERM -f "docker-compose run --rm playwright yarn test:[e]2e" || true
+	@pkill -TERM -f "docker-compose run --rm playwright yarn workspace @modulify/m3-react test:[e]2e" || true
+	@pkill -TERM -f "docker-compose run --rm playwright yarn workspace @modulify/m3-vue test:[e]2e" || true
+	@docker ps -q --filter "name=m3-web-playwright-run" | xargs -r docker rm -f
diff --git a/scripts/playwright-capture.mjs b/scripts/playwright-capture.mjs
new file mode 100644
index 0000000..17a63d4
--- /dev/null
+++ b/scripts/playwright-capture.mjs
@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { chromium } from 'playwright'
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith('--')) {
+      continue
+    }
+    const key = token.slice(2)
+    const next = argv[i + 1]
+    if (!next || next.startsWith('--')) {
+      args[key] = 'true'
+      continue
+    }
+    args[key] = next
+    i += 1
+  }
+  return args
+}
+
+function toBool(value, fallback = true) {
+  if (value == null) {
+    return fallback
+  }
+  return !['0', 'false', 'no', 'off'].includes(String(value).toLowerCase())
+}
+
+function sanitizePart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')
+}
+
+function parseHttpUrl(value) {
+  let parsed
+  try {
+    parsed = new URL(value)
+  } catch (error) {
+    throw new Error(`Invalid --url value: ${value}`)
+  }
+
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Unsupported URL protocol in --url: ${value}`)
+  }
+
+  return parsed
+}
+
+function defaultFileName(parsed, rawUrl) {
+  const base = sanitizePart(`${parsed.hostname}${parsed.pathname || '/index'}`.toLowerCase()) || 'page'
+  const hash = crypto.createHash('sha1').update(rawUrl).digest('hex').slice(0, 8)
+  return `${base}-${hash}.png`
+}
+
+function metaPathFor(imagePath) {
+  const ext = path.extname(imagePath)
+  const withoutExt = ext ? imagePath.slice(0, -ext.length) : imagePath
+  return `${withoutExt}.meta.json`
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  const requestedUrl = args.url
+  if (!requestedUrl) {
+    console.error('usage: node scripts/playwright-capture.mjs --url https://... [--out path.png] [--out-dir dir]')
+    process.exit(2)
+  }
+  const parsedUrl = parseHttpUrl(requestedUrl)
+  const url = parsedUrl.toString()
+
+  const width = Number(args.width ?? 1440)
+  const height = Number(args.height ?? 1024)
+  const waitMs = Number(args['wait-ms'] ?? 1200)
+  const timeoutMs = Number(args.timeout ?? 45000)
+  const waitUntil = args['wait-until'] ?? 'networkidle'
+  const waitSelector = args['wait-selector'] ?? null
+  const fullPage = toBool(args['full-page'], true)
+
+  const outDir = args['out-dir'] ?? 'drafts/screenshots'
+  const outPath = args.out ? args.out : path.join(outDir, defaultFileName(parsedUrl, url))
+
+  await mkdir(path.dirname(outPath), { recursive: true })
+
+  const browser = await chromium.launch({ headless: true })
+  const context = await browser.newContext({
+    viewport: { width, height },
+  })
+  const page = await context.newPage()
+
+  try {
+    await page.goto(url, { waitUntil, timeout: timeoutMs })
+    if (waitSelector) {
+      await page.waitForSelector(waitSelector, { timeout: timeoutMs })
+    }
+    if (waitMs > 0) {
+      await page.waitForTimeout(waitMs)
+    }
+
+    await page.screenshot({
+      path: outPath,
+      fullPage,
+    })
+
+    const meta = {
+      captured_at: new Date().toISOString(),
+      url_requested: url,
+      url_final: page.url(),
+      title: await page.title(),
+      viewport: { width, height },
+      full_page: fullPage,
+      wait_until: waitUntil,
+      wait_ms: waitMs,
+      wait_selector: waitSelector,
+      image_path: outPath,
+    }
+
+    const metaPath = metaPathFor(outPath)
+    await writeFile(metaPath, `${JSON.stringify(meta, null, 2)}\n`, 'utf8')
+
+    console.log(outPath)
+    console.log(metaPath)
+  } finally {
+    await page.close().catch(() => {})
+    await context.close().catch(() => {})
+    await browser.close().catch(() => {})
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof Error) {
+    console.error(error.message)
+  } else {
+    console.error(String(error))
+  }
+  process.exit(1)
+})

From 6bbd03547c88589096cb02a532d6c62eb81d4eec Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 18:19:34 +0400
Subject: [PATCH 18/37] docs(m3-vue): Storybook surface styling was aligned

---
 m3-vue/storybook/components/M3RichTooltip.mdx |  5 ++++-
 .../components/M3ScrollRail.stories.ts        | 13 +++++++++++--
 m3-vue/storybook/components/M3Switch.mdx      |  5 ++++-
 .../examples/checkbox/CheckboxList.vue        | 19 ++++++++++++++++---
 m3-vue/storybook/utils/mdxCodeBlock.ts        |  2 +-
 5 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index 8d02f3a..509192b 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -14,7 +14,10 @@ Rich tooltips provide contextual, supplementary information near a trigger eleme
 - Avoid using tooltips as the only way to convey critical information.
 
 <Unstyled>
-  <div className="m3-panel m3-panel_elevated-1 my-4" style={{ maxWidth: '360px' }}>
+  <div
+    className="m3-surface m3-surface_role-surface-container m3-surface_elevation-0 my-4"
+    style={{ maxWidth: '360px', padding: '32px', borderRadius: '16px', color: 'var(--m3-sys-on-surface)' }}
+  >
     <Inline is={DeleteTooltip} />
   </div>
 </Unstyled>
diff --git a/m3-vue/storybook/components/M3ScrollRail.stories.ts b/m3-vue/storybook/components/M3ScrollRail.stories.ts
index e871082..fccaa15 100644
--- a/m3-vue/storybook/components/M3ScrollRail.stories.ts
+++ b/m3-vue/storybook/components/M3ScrollRail.stories.ts
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/vue3'
 
 import { M3ScrollRail } from '@/components/scroll-rail'
+import { M3Surface } from '@/components/surface'
 
 const meta = {
   title: 'Components/M3ScrollRail',
@@ -27,6 +28,7 @@ const meta = {
 
     components: {
       M3ScrollRail,
+      M3Surface,
     },
 
     setup () {
@@ -37,7 +39,14 @@ const meta = {
     },
 
     template: `
-        <div class="m3-panel m3-panel_elevated-1" style="padding: 4px;">
+        <M3Surface
+            :fill-width="false"
+            :fill-height="false"
+            :rounding="16"
+            :elevation="0"
+            variant="surface-container"
+            style="padding: 4px;"
+        >
             <div
                 class="m3-scroll-box m3-scroll-box_scroll-x m3-scroll-box_scroll-y"
                 style="max-width: 360px; max-height: 360px;"
@@ -50,7 +59,7 @@ const meta = {
                     </div>
                 </div>
             </div>
-        </div>
+        </M3Surface>
     `,
   }),
 
diff --git a/m3-vue/storybook/components/M3Switch.mdx b/m3-vue/storybook/components/M3Switch.mdx
index 9ced597..4c08932 100644
--- a/m3-vue/storybook/components/M3Switch.mdx
+++ b/m3-vue/storybook/components/M3Switch.mdx
@@ -27,7 +27,10 @@ import * as M3SwitchStories from './M3Switch.stories'
 ### Demo
 
 <Unstyled>
-  <div className="m3-panel m3-panel_elevated-1 my-4" style={{maxWidth: '360px'}}>
+  <div
+    className="m3-surface m3-surface_role-surface-container m3-surface_elevation-0 my-4"
+    style={{ maxWidth: '360px', padding: '32px', borderRadius: '16px', color: 'var(--m3-sys-on-surface)' }}
+  >
     <Inline is={FieldSwitch} label="Wi-Fi" class="mb-4" />
     <Inline is={FieldSwitch} label="Bluetooth" />
   </div>
diff --git a/m3-vue/storybook/examples/checkbox/CheckboxList.vue b/m3-vue/storybook/examples/checkbox/CheckboxList.vue
index 382f534..530f650 100644
--- a/m3-vue/storybook/examples/checkbox/CheckboxList.vue
+++ b/m3-vue/storybook/examples/checkbox/CheckboxList.vue
@@ -1,5 +1,12 @@
 <template>
-    <div class="m3-panel m3-panel_elevated-1">
+    <M3Surface
+        :class="$style['panel']"
+        :fill-width="false"
+        :fill-height="false"
+        :rounding="16"
+        :elevation="0"
+        variant="surface-container"
+    >
         <template v-for="(o, i) in options" :key="id + '-option-' + i">
             <template v-if="'subordinates' in o">
                 <div :class="$style['line']">
@@ -49,13 +56,14 @@
                 </label>
             </div>
         </template>
-    </div>
+    </M3Surface>
 </template>
 
 <script lang="ts" setup>
 import type { PropType } from 'vue'
 
 import { M3Checkbox } from '@/components/checkbox'
+import { M3Surface } from '@/components/surface'
 
 import { ref } from 'vue'
 import useId from '@/composables/id'
@@ -100,8 +108,13 @@ const toggle = (option: Required<OptionWithSubordinates>, checked: boolean) => {
 </script>
 
 <style module>
+.panel {
+    padding: 32px;
+    color: var(--m3-sys-on-surface);
+}
+
 .line {
     display: flex;
     align-items: center;
 }
-</style>
\ No newline at end of file
+</style>
diff --git a/m3-vue/storybook/utils/mdxCodeBlock.ts b/m3-vue/storybook/utils/mdxCodeBlock.ts
index 17d22c7..86d2211 100644
--- a/m3-vue/storybook/utils/mdxCodeBlock.ts
+++ b/m3-vue/storybook/utils/mdxCodeBlock.ts
@@ -53,7 +53,7 @@ const COPY_SUCCESS_TEXT = 'Copied'
 const COPY_TEXT = 'Copy code'
 const LANGUAGE_BADGE_CLASS = 'm3-docs-code-language'
 const LANGUAGE_PREFIXES = ['language-', 'lang-']
-const PANEL_CLASS = 'm3-panel m3-panel_elevated-1'
+const PANEL_CLASS = 'm3-surface m3-surface_role-surface-container m3-surface_elevation-0'
 const NON_SPECIFIC_LANGUAGES = new Set(['plain', 'plaintext', 'text', 'txt'])
 
 const HIGHLIGHT_LANGUAGE_ALIASES: Record<string, string> = {

From 7acd4b9c5a3df75222b06d4bd54ae38cb2d4c591 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 21:05:18 +0400
Subject: [PATCH 19/37] docs: AGENTS.md was reorganized

Updated purpose wording and moved setup steps into a dedicated section.
Added architecture rules for workspace test ownership and package-based cross-workspace imports.
---
 AGENTS.md | 164 ++++++++++++++++++------------------------------------
 1 file changed, 53 insertions(+), 111 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 932862a..267506d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,27 +11,6 @@
   respond in that language.
 - If a message is mixed-language, reply in the dominant language unless the
   user specifies otherwise.
-- Run `make eslint` before handoff or commit preparation only when changed
-  files include code covered by eslint rules (for example `*.js`, `*.ts`,
-  and similar source files). Do not run `make eslint` for markdown-only
-  changes (for example `*.md`).
-- When working on files under `drafts/`, keep documentation mixed-format:
-  narrative context in `*.md` plus machine-readable `*.yaml` sidecars for
-  structured entities (for example tokens, decisions, boundaries, variation
-  axes, invariants, confidence, and source references).
-- For `drafts/` work, create and update these YAML sidecars proactively
-  without requiring explicit user confirmation.
-- For `drafts/` work, automatically maintain links from the main draft
-  markdown file to related YAML sidecars.
-- During experimental component development, do not modify current production
-  components in `src/components` unless explicitly requested.
-- For agent-driven experimental components, create and use `src/experiment`
-  directories at the same level as `src/components` inside each workspace.
-- Experimental implementation order is mandatory: implement in
-  `m3-vue/src/experiment` first; port to `m3-react/src/experiment` only after
-  the experiment is explicitly confirmed as successful.
-- Getter/helper functions must be side-effect free. Side effects are allowed
-  only by prior agreement and only when there are strong, explicit reasons.
 
 ## Reporting
 - Keep handoff reports natural and outcome-focused: describe what was done.
@@ -40,44 +19,10 @@
 - Always mention blockers, failed required checks, or other omissions that can
   affect correctness, safety, or reproducibility.
 
-## Experiment Workflow
-- Before starting any non-trivial experiment, explicitly ask the user for a
-  time budget/timeout for the run (for example 30, 60, 120 minutes).
-- Record experiment start immediately in `drafts/experiment.md` with:
-  start timestamp, agreed timeout, current goal, and planned checkpoints.
-- Keep a milestone log in `drafts/milestones.md`:
-  create an entry before validating each sub-hypothesis/side-hypothesis and
-  create a matching completion entry after validation with outcomes.
-- Log missing inputs in `drafts/milestones.md` as separate "missing" notes
-  (for example unavailable data, blocked tools/access, unclear acceptance
-  criteria, missing artifacts).
-- In experiment mode, escalations are forbidden by default.
-- Exception: escalations are allowed only after explicit user sanction for the
-  current experiment scope.
-- Before any sanctioned escalation phase, define and log an escalation window:
-  exact command set, start marker, and freeze condition.
-- When sanctioned, log `escalation-needed` before request and
-  `escalation-result` after execution in `drafts/milestones.md`.
-- Prefer one-shot privileged bootstrap (`make m3/experiment/bootstrap/evidence`)
-  over multiple incremental escalation requests.
-- During experiments, use `m3/experiment/*` wrappers only; avoid direct
-  `research-fetch-*` and `research-capture-*` calls to keep escalation scope
-  predictable.
-- If not sanctioned, log `escalation-blocked` and `missing`, then continue
-  with non-escalated steps only.
-- After escalation freeze is declared, do not issue new escalation requests.
-  If a required action would need escalation, log `escalation-blocked` +
-  `missing` and continue only with local/safe targets.
-- During experiments, periodically check elapsed time against the agreed
-  timeout and record time checks in `drafts/milestones.md`.
-- If timeout is reached or at risk, stop/slow down and ask the user whether to
-  extend, narrow scope, or finish with current findings to avoid open-ended
-  runs.
-
 ## Purpose
-This file defines practical instructions for working in the
-`modulify/m3-web` repository, with a focus on test execution and commit
-workflow.
+This file defines practical instructions for day-to-day work in the
+`modulify/m3-web` repository, with a focus on repository conventions,
+test execution, and standard local commands.
 
 ## Repository Structure
 - This project is a Yarn Workspaces monorepo.
@@ -87,13 +32,27 @@ workflow.
 - Vitest workspace targets are declared in `vitest.workspace.ts`:
   `m3-react`, `m3-vue`.
 
-## Local Environment Prerequisites
+## Architecture Rules
+- Getter/helper functions must be side-effect free. Side effects are allowed
+  only by prior agreement and only when there are strong, explicit reasons.
+- Tests inside a workspace must cover only code owned by that workspace. In
+  `m3-foundation`, `m3-react`, `m3-vue`, and any future workspace, do not add
+  tests for implementation that belongs to another workspace.
+- Cross-workspace imports must go through the target workspace package name as
+  declared in `package.json`. Relative or absolute filesystem imports into
+  another workspace are forbidden. For example,
+  `import type { Appearance } from '@modulify/m3-foundation/types/components/button'`
+  is allowed, but
+  `import type { Appearance } from '../../../m3-foundation/types/components/button'`
+  is not.
+
+## Local setup
 - Yarn version is `4.6.0` (see `packageManager` in `package.json`).
-- Local `.yarnrc.yml` is generated from `.yarnrc.yml.dist` using:
+- Generate local `.yarnrc.yml` from `.yarnrc.yml.dist`:
 ```bash
 make .yarnrc.yml
 ```
-- Install dependencies with:
+- Install dependencies:
 ```bash
 make node_modules
 # or
@@ -103,16 +62,6 @@ yarn install
 ## Running Tests
 
 ### Local Path
-- Generate local Yarn config:
-```bash
-make .yarnrc.yml
-```
-- Install dependencies:
-```bash
-make node_modules
-# or
-yarn install
-```
 - Run all tests:
 ```bash
 make test
@@ -153,44 +102,37 @@ make help
 ```
 
 ## Important Project Rules
-- Commit messages follow Conventional Commits.
-- Commitlint configuration is in `.commitlintrc.json` with:
-  `header-max-length=200`, `body-max-line-length=200`,
-  `footer-max-line-length=200`, `subject-case=never`.
-- Getter/helper functions must be side-effect free. Side effects are allowed
-  only by prior agreement and only when there are strong, explicit reasons.
+- Before performing actions, analyze whether there is a suitable local skill
+  for the task and consult it for detailed instructions.
+- Before performing repeated or operational actions, inspect `make help` and
+  its output to see whether an existing recipe already covers the task.
+- If a suitable recipe exists, prefer it over ad hoc commands to reduce extra
+  work, keep workflows standardized, and avoid unnecessary escalations.
+- Run eslint before handoff or commit preparation only when changed files
+  include code covered by eslint rules (for example `*.js`, `*.ts`, and
+  similar source files). Do not run eslint for markdown-only changes.
+- Prefer running eslint with `--fix` when available so autofixable issues are
+  resolved automatically before manual follow-up.
+
+## Skills
+The skills listed below are stored locally in this repository under `skills/`.
+
+If the context was compacted and you see `Context compacted`, reread any skill
+whose description below starts with `[reread]` after the colon before
+continuing.
 
-## Commit Workflow
-- Default commit message language is English (unless explicitly requested
-  otherwise).
-- Commit style is Conventional Commits.
-- Write commit subjects as historical facts (not intentions).
-- Start commit subject description with an uppercase letter.
-- Keep commit subject description concise.
-- Move long details to commit body; lists in body are allowed for enumerations.
-- Use past/perfective wording; prefer passive voice for changelog-friendly phrasing.
-Examples: `Added ...`, `Removed ...`, `Refactored ...`, `Fixed ...`.
-- Respect commitlint limits from `.commitlintrc.json`:
-  `header-max-length=200`, `body-max-line-length=200`,
-  `footer-max-line-length=200`.
-- For workspace commits, use scope equal to the workspace directory name:
-  `m3-foundation`, `m3-react`, `m3-vue`.
-- Split commits by logical change. Workspace-local changes should stay in
-  their workspace scope.
-- Changes in `yarn.lock` must always be committed separately from all other files.
-- Commit message for `yarn.lock`-only commit must be exactly:
-`chore: Updated yarn.lock`.
-- Exception for intentional dependency updates:
-if commit purpose is dependency update (`yarn up`, `yarn add`, `yarn remove`, etc.),
-after rebase conflict resolution rerun the original dependency command and recreate separate
-`chore: Updated yarn.lock` commit.
-- Exception: global workspace-level changes can be combined in one commit.
-Global examples: eslint rule updates, shared dependency updates, repository-level infra/config changes.
-- For commit tasks, use the local skill:
-`skills/commit-workflow/SKILL.md`.
-- For `yarn.lock` merge/rebase conflict resolution, use the local skill:
-`skills/yarn-lock-conflict-resolution/SKILL.md`.
-- For coverage deficit analysis and recovery strategy, use the local skill:
-`skills/coverage-recovery/SKILL.md`.
-- For documentation creation or edits under `docs/` with locale parity, use the local skill:
-`skills/docs-parity/SKILL.md`.
+- `commit-workflow`: [reread] Use when creating or splitting git commits in
+  this repository. Reread it before every commit creation; it standardizes
+  commit grouping, Conventional Commits, workspace scopes, and commitlint
+  limits.
+- `coverage-recovery`: Use when coverage is below target or uncovered code must
+  be analyzed and closed without adding artificial tests.
+- `docs-parity`: Use when creating or editing files under `docs/`. Keeps
+  English-first edits, locale parity, and locale index updates aligned.
+- `exploration-workflow`: [reread] Use only when the user explicitly switches
+  the task into exploration mode: autonomous hypothesis-driven work on
+  uncertain functionality, with timeboxing, milestone logging, and tightly
+  controlled pre-agreed escalation windows, plus `drafts/current.yml` and a
+  dedicated `drafts/` activity directory for logs, facts, and artifact links.
+- `yarn-lock-conflict-resolution`: Use when resolving merge or rebase conflicts
+  in `yarn.lock` according to repository policy.

From 155fc59b1d3ff28411ae30272fa3d622cbb44a8d Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 21:39:36 +0400
Subject: [PATCH 20/37] docs: Surface evidence and exploration skill were added

---
 evidence/surface/fetch/bottom-sheets.json     |   1 +
 evidence/surface/fetch/dialogs.json           |   1 +
 evidence/surface/fetch/layout-applying.json   |   1 +
 evidence/surface/fetch/manifest.yaml          |  17 ++
 evidence/surface/fetch/menus.json             |   1 +
 .../surface/fetch/motion-easing-duration.json |   1 +
 .../surface/fetch/motion-transitions.json     |   1 +
 evidence/surface/fetch/navigation-drawer.json |   1 +
 evidence/surface/fetch/side-sheets.json       |   1 +
 evidence/surface/model/layers.yaml            |  76 +++++
 evidence/surface/model/requirements.yaml      | 129 ++++++++
 evidence/surface/model/spec-findings.yaml     | 178 +++++++++++
 evidence/surface/model/transitions.yaml       | 143 +++++++++
 evidence/surface/panel/boundaries.yaml        |  74 +++++
 evidence/surface/panel/decisions.yaml         |  79 +++++
 evidence/surface/panel/side-sheet-guidance.md |  30 ++
 evidence/surface/panel/side-sheet-modal.yaml  |  59 ++++
 evidence/surface/panel/tokens.yaml            | 277 ++++++++++++++++++
 evidence/surface/summary.md                   | 194 ++++++++++++
 skills/exploration-workflow/SKILL.md          | 272 +++++++++++++++++
 20 files changed, 1536 insertions(+)
 create mode 100644 evidence/surface/fetch/bottom-sheets.json
 create mode 100644 evidence/surface/fetch/dialogs.json
 create mode 100644 evidence/surface/fetch/layout-applying.json
 create mode 100644 evidence/surface/fetch/manifest.yaml
 create mode 100644 evidence/surface/fetch/menus.json
 create mode 100644 evidence/surface/fetch/motion-easing-duration.json
 create mode 100644 evidence/surface/fetch/motion-transitions.json
 create mode 100644 evidence/surface/fetch/navigation-drawer.json
 create mode 100644 evidence/surface/fetch/side-sheets.json
 create mode 100644 evidence/surface/model/layers.yaml
 create mode 100644 evidence/surface/model/requirements.yaml
 create mode 100644 evidence/surface/model/spec-findings.yaml
 create mode 100644 evidence/surface/model/transitions.yaml
 create mode 100644 evidence/surface/panel/boundaries.yaml
 create mode 100644 evidence/surface/panel/decisions.yaml
 create mode 100644 evidence/surface/panel/side-sheet-guidance.md
 create mode 100644 evidence/surface/panel/side-sheet-modal.yaml
 create mode 100644 evidence/surface/panel/tokens.yaml
 create mode 100644 evidence/surface/summary.md
 create mode 100644 skills/exploration-workflow/SKILL.md

diff --git a/evidence/surface/fetch/bottom-sheets.json b/evidence/surface/fetch/bottom-sheets.json
new file mode 100644
index 0000000..3f8310e
--- /dev/null
+++ b/evidence/surface/fetch/bottom-sheets.json
@@ -0,0 +1 @@
+{"category": "containment", "component_image_1x1": {}, "component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/341c3402df784b026de4b8b6fe23f3eeddcfc45e753bc872f59861c10edde81bfb0410c8b1838a86255f0f66b47581ff3621044502dee57db2fb365ca71021da", "height": 560, "url": "https://lh3.googleusercontent.com/UIUrt9wQoicIdyQ4IjklJLL6-vIR-GmyYF4ErZOfLrFLREEII6mOVuE15ImA8sq6VvneWK0KQvVOFh8nR_39hUdwN2YJMT7OX9Bivo7aPBBPj0zakQQ", "width": 1120}, "component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/c2b9b97f5b43d4d8edfb0efa2cae3a4ede8e4e442ea0c5231f5309e37613166abbfb485a7f96a16f06bdd58a0abeebaa7a24aed225d635193aaa2e07fb0de0f1", "height": 560, "url": "https://lh3.googleusercontent.com/2YiNco_ni2-lSwWlJuYpcp0SKqQQzz1FtoDMeqvd5rjvkTenfvcYm3ccSqJh2oowZ_bXvcUnrMvRzLXrR4HT-3iwlA25df97JZBiIAeOfZEoSHeldA", "width": 1680}, "component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/14d3cfe953f0b131da2966f35d9437ba2065e16f2d584c8da4192c45a2ba1937052ca085c386576e924d0cdb2c454593054b9742c644f4e57a541c1e5eed5a04", "height": 560, "url": "https://lh3.googleusercontent.com/vs0KnopDGwWY_DYPbdNdmkyYL_N4Cf3eOG7StgUi-LFVsgXqBJ0k4Jlgw25QLpCuxUFPk8Rwt3ijxuBgIohNjVQsEAIqvOB7EzObKxSQzbRyNgGVEYXG", "width": 840}, "component_image_position": "top center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/6442b37617d160c37751d4301b1265a781d2c786aed628fa890892d2e191038e5b987ff74363ccd261904eb0d686dbabd2e356107badfeaf57b6e13b629e0697", "height": 560, "url": "https://lh3.googleusercontent.com/aOb9-hvKVti3KeEn-NfoD-f1IonRWbrz-A26gJ4SSuakHtKHC2Vw_uh1w3E_1JzMAx4CQ0tjpi2Zvq4yzQ60whrjOAzyIq2CcjAzMgx5VcbGpNb1h4cA", "width": 1120}, "dark_component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/2e5a55f30d6a8841040c2e2d947f4039c5713cb5144318a02d5a1ef5a2d9b4fafb5f3f89af22ad89876c5f2fdbc5be393b23f2457e0829d2ed877d61301bec50", "height": 560, "url": "https://lh3.googleusercontent.com/2eharb9N0r0D_CQm81EpHY7FtjRm1hfksH7QVW09EsH2Wx6OwToQyFaWpUmqqGqtk3r30XIf42o1GeDOwjmkZtLPivrY0LyV0q2avatZVgKk8U0Gyw", "width": 1680}, "dark_component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/31f1e3efd779bd9bd956ab312e0107409d00de80ef55beb7a4fcc5e1588da9b88e3d4a5281002ff43de1ee61169a9538a9544015a620d9a2445c2f072c66e094", "height": 560, "url": "https://lh3.googleusercontent.com/3MqGJTtT0PiPqw6-AG2hxNyEw3EN7kfRuPQBbq4jAd5tU2lDf2eBPFzXyEmoe9iPQH1RfQaoql6df_4tuSKQli87ijf1aWl8JqoyarmV1FM36g33Gg", "width": 840}, "description": "Bottom sheets are surfaces containing supplementary content, anchored to the bottom of the screen.", "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/c9b614e2c6394e633361aedf8dfabee7018abc81fed5e9c2d2b830cfb91cdde77617375d80608ab19e9deaae6e65763ecf7ee7e7f3be1c5cb05eb08a89e09fe0", "height": 4096, "url": "https://lh3.googleusercontent.com/9gfaUBF_jWA_0uIpfK8gwcKthghUalMNBXP1_ILmkMAF8uf8q8xV3FPeiK2qJYfUyoUHf0zrQooP-olwdgm3nEfSIah6Do202yLoBMuFyl4nao29ao8", "width": 4096}, "foreground_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/533e014f36dc2451d394c03188633b3e805049119e1fdac9903be32e3e3163588ccfb610d365c2e1ada576174426cea0101031cbad8245a346d8fc1a88d4fff6", "height": 1816, "url": "https://lh3.googleusercontent.com/xG7HTNDPwS9Dj37Bw-sK9tqCB7RKZkDDYhw6oYHKxmEio1ZdY7ilg1TGGLteoAI14_qj3ZCMj4gbXa8NebMrGyYRKRcQ-5wqcMCdw6BeuTkI_P2gvOU", "width": 856}, "foreground_image_alignment": "center", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Components / Bottom Sheets", "isDisplayed": true, "jetpack": {}, "mdc_android": {"banners": [], "hide_generic_not_available_message": false, "hide_intro_block": true, "image": [{"a11y_description": "Example bottom sheet: modal bottom sheet", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/14fa0f73686498345e6b3d2c162cc038612f0ce475969b6223543977af215f0dd3a5d4473a594d5c4cb7cfb8f79f7fdb5f97f9159c372a2853111143861d1685", "height": 532, "url": "https://lh3.googleusercontent.com/Um-uopzOwBakYytrS-_tys-4Jhe_bwbY-rVuzx9swVBZMcizNX_w985A8GdRQ-FwbEW45mMfDgkiuMMsqi3JI9fqa6FHb0oSlvM4cwFEog1sSlicsYr-", "width": 1064}}, {"a11y_description": "Standard bottom sheet example. Collapsed on the left and expanded on the\nright.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/b08f62e5cc779362c32c8360c3015ea601124ece798a056ab276b565e117d0deaa774e0c476230b7dd796ce8443cbf34f9265ecc0027944f8cfe742a753139e2", "height": 2160, "url": "https://lh3.googleusercontent.com/B7t0IbDHwFQuL7iRuKhTuTpZo8mblYAHg0q-bCowsAn8fpizoxpWnQfK0E9Zb-g_6DownUBiSOA6NdaeCoVEd_DKdR1P8qbeP9dCQFXy0uz9ngGNeg", "width": 2160}}, {"a11y_description": "Modal bottom sheet example. Collapsed on the left and expanded on the right.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/f810ef2649599d0c1993697c41e609a37fb93773f5c7c09d52bb10e728e087c2f28c36b2cfe17bb8aa8c59725ba172f463b1723247f42cdac16d2379db1d52e4", "height": 2160, "url": "https://lh3.googleusercontent.com/ajuNBwFkxERvKgQ6Pk4e_ZOq8CPWj5f7aA_uYD6Qq5Tv1bYy1-jLKIhd_TK5EerJ550N0JnoyQ_fZ6_dEXC9g-hAWxe2GGamCxGEnsG1n_YxNVaqwQ", "width": 2160}}, {"a11y_description": "Bottom sheet anatomy", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/28bf359e28ada5a30a7b335b4ba3860c8a323c572cf1aa1b9d567e2caf99b6f39df87bbe15aa14ad6a4a8632ed0ec78b5e1c1051f34868f47e7ecddc1f3f550d", "height": 760, "url": "https://lh3.googleusercontent.com/UQIEJJ9UEOR3t5g9wtTOGoWy6s8QXbsxKYOdt7RJ6bSmINikBLnZ3XbSpIb9RBtQwY811TZCw9Zs57eg85AjERuRB4bE7LR08qZZsJLD21O4qRIjJQaX", "width": 1520}}, {"a11y_description": "Bottom sheet with pink background color. Collapsed on the left and expanded on\nthe right.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/8f7f2b0ea75fdb81c0988892e73059dd272b71c910b181096c5f963c88e47c780bc83ce2dbb100b550248173a0b64523d8cb29b3ef19c636d117877d24e1a434", "height": 830, "url": "https://lh3.googleusercontent.com/5KpmGZgdsLzmO52VnZGPD5JqniKVgQ1dynaKlS948Igjo0NmW5h1MVQibtW2ZD6-RoSUraRWU1PRlvgie1J1_1Q2A3opYG9gyGsBOzpzwsR4HKJTLZQE", "width": 800}}], "is_beta": false, "markdown_content": "<!--docs:\ntitle: \"Bottom Sheets\"\nlayout: detail\nsection: components\nexcerpt: \"Bottom sheets slide up from the bottom of the screen to reveal more content.\"\niconId: bottom_sheet\npath: /catalog/bottom-sheet-behavior/\n-->\n\n# Bottom Sheets\n\n[Bottom sheets](https://material.io/components/sheets-bottom) are surfaces\ncontaining supplementary content that are anchored to the bottom of the screen.\n\n<mio-image index=0></mio-image>\n\n**Contents**\n\n*   [Using bottom sheets](#using-bottom-sheets)\n*   [Standard bottom sheet](#standard-bottom-sheet)\n*   [Modal bottom sheet](#modal-bottom-sheet)\n*   [Anatomy and key properties](#anatomy-and-key-properties)\n*   [Theming](#theming-bottom-sheets)\n\n## Using bottom sheets\n\nBefore you can use Material bottom sheets, you need to add a dependency to the\nMaterial Components for Android library. For more information, go to the\n[Getting started](/libraries/mdc-android/getting-started)\npage.\n\nStandard bottom sheet basic usage:\n\n```xml\n<androidx.coordinatorlayout.widget.CoordinatorLayout\n  ...>\n\n  <FrameLayout\n    ...\n    android:id=\"@+id/standard_bottom_sheet\"\n    app:layout_behavior=\"com.google.android.material.bottomsheet.BottomSheetBehavior\">\n\n    <!-- Bottom sheet contents. -->\n\n  </FrameLayout>\n\n</androidx.coordinatorlayout.widget.CoordinatorLayout>\n```\n\nModal bottom sheet basic usage:\n\n```kt\nclass ModalBottomSheet : BottomSheetDialogFragment() {\n\n    override fun onCreateView(\n        inflater: LayoutInflater,\n        container: ViewGroup?,\n        savedInstanceState: Bundle?\n    ): View? = inflater.inflate(R.layout.modal_bottom_sheet_content, container, false)\n\n    companion object {\n        const val TAG = \"ModalBottomSheet\"\n    }\n}\n\nclass MainActivity : AppCompatActivity() {\n    ...\n    val modalBottomSheet = ModalBottomSheet()\n    modalBottomSheet.show(supportFragmentManager, ModalBottomSheet.TAG)\n    ...\n}\n```\n\nMore information on each individual section, below.\n\n### Setting behavior\n\nThere are several attributes that can be used to adjust the behavior of both\nstandard and modal bottom sheets.\n\nBehavior attributes can be applied to standard bottom sheets in xml by setting\nthem on a child `View` set to `app:layout_behavior`, or programmatically:\n\n```kt\nval standardBottomSheetBehavior = BottomSheetBehavior.from(standardBottomSheet)\n// Use this to programmatically apply behavior attributes\n```\n\nBehavior attributes can be applied to modal bottom sheets using app-level theme\nattributes and styles:\n\n```xml\n<style name=\"ModalBottomSheet\" parent=\"Widget.Material3.BottomSheet.Modal\">\n  <!-- Apply attributes here -->\n</style>\n\n<style name=\"ModalBottomSheetDialog\" parent=\"ThemeOverlay.Material3.BottomSheetDialog\">\n  <item name=\"bottomSheetStyle\">@style/ModalBottomSheet</item>\n</style>\n\n<style name=\"AppTheme\" parent=\"Theme.Material3.*\">\n  <item name=\"bottomSheetDialogTheme\">@style/ModalBottomSheetDialog</item>\n</style>\n```\n\nOr programmatically:\n\n```kt\nval modalBottomSheetBehavior = (modalBottomSheet.dialog as BottomSheetDialog).behavior\n// Use this to programmatically apply behavior attributes\n```\n\nMore information about these attributes and their default values is available in\nthe [behavior attributes](#behavior-attributes) section.\n\n### Retaining behavior on configuration change\n\nIn order to save and restore specific behaviors of the bottom sheet on\nconfiguration change, the following flags can be set (or combined with bitwise\nOR operations):\n\n*   `SAVE_PEEK_HEIGHT`: `app:behavior_peekHeight` is preserved.\n*   `SAVE_HIDEABLE`: `app:behavior_hideable` is preserved.\n*   `SAVE_SKIP_COLLAPSED`: `app:behavior_skipCollapsed` is preserved.\n*   `SAVE_FIT_TO_CONTENTS`: `app:behavior_fitToContents` is preserved.\n*   `SAVE_ALL`: All aforementioned attributes are preserved.\n*   `SAVE_NONE`: No attribute is preserved. This is the default value.\n\nBehaviors can also be set in code:\n\n```kt\nbottomSheetBehavior.saveFlags = BottomSheetBehavior.SAVE_ALL\n```\n\nOr in xml using the `app:behavior_saveFlags` attribute.\n\n### Setting state\n\nStandard and modal bottom sheets have the following states:\n\n*   `STATE_COLLAPSED`: The bottom sheet is visible but only showing its peek\n    height. This state is usually the 'resting position' of a bottom sheet, and\n    should have enough height to indicate there is extra content for the user to\n    interact with.\n*   `STATE_EXPANDED`: The bottom sheet is visible at its maximum height and it\n    is neither dragging nor settling (see below).\n*   `STATE_HALF_EXPANDED`: The bottom sheet is half-expanded (only applicable if\n    `behavior_fitToContents` has been set to false), and is neither dragging nor\n    settling (see below).\n*   `STATE_HIDDEN`: The bottom sheet is no longer visible and can only be\n    re-shown programmatically.\n*   `STATE_DRAGGING`: The user is actively dragging the bottom sheet up or down.\n*   `STATE_SETTLING`: The bottom sheet is settling to a specific height after a\n    drag/swipe gesture. This will be the peek height, expanded height, or 0, in\n    case the user action caused the bottom sheet to hide.\n\nYou can set a state on the bottom sheet:\n\n```kt\nbottomSheetBehavior.state = BottomSheetBehavior.STATE_COLLAPSED\n```\n\n**Note:** `STATE_SETTLING` and `STATE_DRAGGING` should not be set programmatically.\n\n### Listening to state and slide changes\n\nA `BottomSheetCallback` can be added to a `BottomSheetBehavior`:\n\n```kt\nval bottomSheetCallback = object : BottomSheetBehavior.BottomSheetCallback() {\n\n    override fun onStateChanged(bottomSheet: View, newState: Int) {\n        // Do something for new state.\n    }\n\n    override fun onSlide(bottomSheet: View, slideOffset: Float) {\n        // Do something for slide offset.\n    }\n}\n\n// To add the callback:\nbottomSheetBehavior.addBottomSheetCallback(bottomSheetCallback)\n\n// To remove the callback:\nbottomSheetBehavior.removeBottomSheetCallback(bottomSheetCallback)\n```\n\n### Handling insets and fullscreen\n\n`BottomSheetBehavior` can automatically handle insets (such as for\n[edge to edge](https://developer.android.com/training/gestures/edge-to-edge)) by\nspecifying any of these to true on the view:\n\n*   `app:paddingBottomSystemWindowInsets`\n*   `app:paddingLeftSystemWindowInsets`\n*   `app:paddingRightSystemWindowInsets`\n*   `app:paddingTopSystemWindowInsets`\n\nOn API 21 and above the modal bottom sheet will be rendered fullscreen (edge to\nedge) if the navigation bar is transparent and `app:enableEdgeToEdge` is true.\nTo enable edge-to-edge by default for modal bottom sheets, you can override\n`?attr/bottomSheetDialogTheme` like the below example:\n\n```\n<style name=\"AppTheme\" parent=\"Theme.Material3.*\">\n  ...\n  <item name=\"bottomSheetDialogTheme\">@style/ThemeOverlay.App.BottomSheetDialog</item>\n</style>\n\n<style name=\"ThemeOverlay.App.BottomSheetDialog\" parent=\"ThemeOverlay.Material3.BottomSheetDialog\">\n    <item name=\"android:navigationBarColor\" tools:ignore=\"NewApi\">@android:color/transparent</item>\n</style>\n```\n\nInsets can be added automatically if any of the padding attributes above are set\nto true in the style, either by updating the style passed to the constructor, or\nby updating the default style specified by the `?attr/bottomSheetDialogTheme`\nattribute in your theme.\n\n`BottomSheetDialog` will also add padding to the top when the bottom sheet\nslides under the status bar, to prevent content from being drawn underneath it.\n\n### Making bottom sheets accessible\n\nThe contents within a bottom sheet should follow their own accessibility\nguidelines, such as setting content descriptions for images.\n\nTo support dragging bottom sheets with accessibility services such as TalkBack,\nVoice Access, Switch Access, etc., we provide a convenient widget\n`BottomSheetDragHandleView` which will automatically receive and handle\naccessibility commands to expand and collapse the attached bottom sheet when\nthe accessibility mode is enabled. To use `BottomSheetDragHandleView`, you can\nadd it to the top of your bottom sheet content. It will show a customizable\nvisual indicator for all users. See the example in the below section for how to\nadd a drag handle to your bottom sheet.\n\n**Note:** `BottomSheetDragHandleView` has a default min width and height of 48dp\nto conform to the minimum touch target requirement. So you will need to preserve\nat least 48dp at the top to place a drag handle.\n\n## Standard bottom sheet\n\nStandard bottom sheets co-exist with the screen\u2019s main UI region and allow for\nsimultaneously viewing and interacting with both regions. They are commonly used\nto keep a feature or secondary content visible on screen when content in the\nmain UI region is frequently scrolled or panned.\n\n`BottomSheetBehavior` is applied to a child of\n[CoordinatorLayout](https://developer.android.com/reference/androidx/coordinatorlayout/widget/CoordinatorLayout)\nto make that child a **persistent bottom sheet**, which is a view that comes up\nfrom the bottom of the screen, elevated over the main content. It can be dragged\nvertically to expose more or less content.\n\nAPI and source code:\n\n*   `BottomSheetBehavior`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java)\n\n### Standard bottom sheet example\n\nThe following example shows a standard bottom sheet in its collapsed and\nexpanded states:\n\n<mio-image index=1></mio-image>\n\n`BottomSheetBehavior` works in tandem with `CoordinatorLayout` to let you\ndisplay content on a bottom sheet, perform enter/exit animations, respond to\ndragging/swiping gestures, etc.\n\nApply the `BottomSheetBehavior` to a direct child `View` of `CoordinatorLayout`:\n\n```xml\n<androidx.coordinatorlayout.widget.CoordinatorLayout\n  ...>\n\n  <FrameLayout\n    android:id=\"@+id/standard_bottom_sheet\"\n    style=\"@style/Widget.Material3.BottomSheet\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\"\n    app:layout_behavior=\"com.google.android.material.bottomsheet.BottomSheetBehavior\">\n\n    <!-- Drag handle for accessibility -->\n    <com.google.android.material.bottomsheet.BottomSheetDragHandleView\n    android:id=\"@+id/drag_handle\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"/>\n\n    <!-- Bottom sheet contents. -->\n    <TextView\n    android:layout_width=\"wrap_content\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/title\"\n    .../>\n\n    <TextView\n    android:layout_width=\"wrap_content\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/supporting_text\"\n    .../>\n\n    <Button\n    android:id=\"@+id/bottomsheet_button\"\n    android:layout_width=\"wrap_content\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/action\"\n    .../>\n\n    <com.google.android.material.switchmaterial.SwitchMaterial\n    android:layout_width=\"wrap_content\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/switch_label\"/>\n\n  </FrameLayout>\n\n</androidx.coordinatorlayout.widget.CoordinatorLayout>\n```\n\nIn this example, the bottom sheet is the `FrameLayout`.\n\n## Modal bottom sheet\n\nModal bottom sheets present a set of choices while blocking interaction with the\nrest of the screen. They are an alternative to inline menus and simple dialogs\non mobile devices, providing additional room for content, iconography, and\nactions.\n\n`BottomSheetDialogFragment` is a thin layer on top of the regular support\nlibrary Fragment that renders your fragment as a **modal bottom sheet**,\nfundamentally acting as a dialog.\n\nModal bottom sheets render a shadow on the content below them, to indicate that\nthey are modal. If the content outside of the dialog is tapped, the bottom sheet\nis dismissed. Modal bottom sheets can be dragged vertically and dismissed by\nsliding them down completely.\n\nAPI and source code:\n\n*   `BottomSheetDialogFragment`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetDialogFragment.java)\n\n### Modal bottom sheet example\n\nThe following example shows a modal bottom sheet in its collapsed and expanded\nstates:\n\n<mio-image index=2></mio-image>\n\nFirst, subclass `BottomSheetDialogFragment` and overwrite `onCreateView` to\nprovide a layout for the contents of the sheet (in this example, it's\n`modal_bottom_sheet_content.xml`):\n\n```kt\nclass ModalBottomSheet : BottomSheetDialogFragment() {\n\n    override fun onCreateView(\n        inflater: LayoutInflater,\n        container: ViewGroup?,\n        savedInstanceState: Bundle?\n    ): View? = inflater.inflate(R.layout.modal_bottom_sheet_content, container, false)\n\n    companion object {\n        const val TAG = \"ModalBottomSheet\"\n    }\n}\n```\n\nThen, inside an `AppCompatActivity`, to show the bottom sheet:\n\n```kt\nval modalBottomSheet = ModalBottomSheet()\nmodalBottomSheet.show(supportFragmentManager, ModalBottomSheet.TAG)\n```\n\n`BottomSheetDialogFragment` is a subclass of `AppCompatFragment`, which means\nyou need to use `Activity.getSupportFragmentManager()`.\n\n**Note:** Don't call `setOnCancelListener` or `setOnDismissListener` on a\n`BottomSheetDialogFragment`. You can override\n`onCancel(DialogInterface)` or `onDismiss(DialogInterface)` if necessary.\n\n## Anatomy and key properties\n\nBottom sheets have a sheet, content, and, if modal, a scrim.\n\n<mio-image index=3></mio-image>\n\n1.  Sheet\n2.  Content\n3.  Scrim (in modal bottom sheets)\n\n### Sheet attributes\n\nElement        | Attribute             | Related method(s)                 | Default value\n-------------- | --------------------- | --------------------------------- | -------------\n**Color**      | `app:backgroundTint`  | N/A                               | `?attr/colorSurface`\n**Shape**      | `app:shapeAppearance` | N/A                               | `?attr/shapeAppearanceLargeComponent`\n**Elevation**  | `android:elevation`   | N/A                               | `3dp`\n**Max width**  | `android:maxWidth`    | `setMaxWidth`<br/>`getMaxWidth`   | `640dp`\n**Max height** | `android:maxHeight`   | `setMaxHeight`<br/>`getMaxHeight` | N/A\n\n### Behavior attributes\n\nMore info about these attributes and how to use them in the\n[setting behavior](#setting-behavior) section.\n\nBehavior                                    | Related method(s)                                                         | Default value\n------------------------------------------- | ------------------------------------------------------------------------- | -------------\n`app:behavior_peekHeight`                   | `setPeekHeight`<br/>`getPeekHeight`                                       | `auto`\n`app:behavior_hideable`                     | `setHideable`<br/>`isHideable`                                            | `false` for standard<br/>`true` for modal\n`app:behavior_skipCollapsed`                | `setSkipCollapsed`<br/>`getSkipCollapsed`                                 | `false`\n`app:behavior_fitToContents`                | `setFitToContents`<br/>`isFitToContents`                                  | `true`\n`app:behavior_draggable`                    | `setDraggable`<br/>`isDraggable`                                          | `true`\n`app:behavior_halfExpandedRatio`            | `setHalfExpandedRatio`<br/>`getHalfExpandedRatio`                         | `0.5`\n`app:behavior_expandedOffset`               | `setExpandedOffset`<br/>`getExpandedOffset`                               | `0dp`\n`app:behavior_significantVelocityThreshold` | `setSignificantVelocityThreshold` <br/> `getSignificantVelocityThreshold` | `500 pixels/s`\n\nTo save behavior on configuration change:\n\nAttribute                | Related method(s)                 | Default value\n------------------------ | --------------------------------- | -------------\n`app:behavior_saveFlags` | `setSaveFlags`<br/>`getSaveFlags` | `SAVE_NONE`\n\n### Styles\n\n**Element**               | **Default value**\n------------------------- | -------------------------------------------\n**Default style (modal)** | `@style/Widget.Material3.BottomSheet.Modal`\n\nDefault style theme attribute:`?attr/bottomSheetStyle`\n\nNote: The `?attr/bottomSheetStyle` default style theme attribute is for modal\nbottom sheets only. There is no default style theme attribute for standard\nbottom sheets, because `BottomSheetBehavior`s don't have a designated associated\n`View`.\n\n### Theme overlays\n\n**Element**               | **Theme overlay**\n------------------------- | ------------------------------------------\n**Default theme overlay** | `ThemeOverlay.Material3.BottomSheetDialog`\n\nDefault theme overlay attribute: `?attr/bottomSheetDialogTheme`\n\nSee the full list of\n[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/res/values/styles.xml),\n[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/res/values/attrs.xml),\nand\n[themes and theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/res/values/themes.xml).\n\n## Theming bottom sheets\n\nBottom sheets support\n[Material Theming](https://material.io/components/sheets-bottom#theming), which\ncan customize color and shape.\n\n### Bottom sheet theming example\n\nAPI and source code:\n\n*   `BottomSheetBehavior`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java)\n*   `BottomSheetDialogFragment`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetDialogFragment)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetDialogFragment.java)\n\nThe following example shows a bottom sheet with Material Theming, in its\ncollapsed and expanded states.\n\n<mio-image index=4></mio-image>\n\n#### Implementing bottom sheet theming\n\nSetting the theme attribute `bottomSheetDialogTheme` to your custom\n`ThemeOverlay` will affect all bottom sheets.\n\nIn `res/values/themes.xml`:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n  ...\n  <item name=\"bottomSheetDialogTheme\">@style/ThemeOverlay.App.BottomSheetDialog</item>\n</style>\n\n<style name=\"ThemeOverlay.App.BottomSheetDialog\" parent=\"ThemeOverlay.Material3.BottomSheetDialog\">\n    <item name=\"bottomSheetStyle\">@style/ModalBottomSheetDialog</item>\n</style>\n```\n\nIn `res/values/styles.xml`:\n\n```xml\n<style name=\"ModalBottomSheetDialog\" parent=\"Widget.Material3.BottomSheet.Modal\">\n    <item name=\"backgroundTint\">@color/shrine_pink_light</item>\n    <item name=\"shapeAppearance\">@style/ShapeAppearance.App.LargeComponent</item>\n</style>\n\n<style name=\"ShapeAppearance.App.LargeComponent\" parent=\"ShapeAppearance.Material3.LargeComponent\">\n    <item name=\"cornerFamily\">cut</item>\n    <item name=\"cornerSize\">24dp</item>\n</style>\n```\n\n**Note:** The benefit of using a custom `ThemeOverlay` is that any changes to\nyour main theme, such as updated colors, will be reflected in the bottom sheet,\nas long as they're not overridden in your custom theme overlay. If you use a\ncustom `Theme` instead, by extending from one of the\n`Theme.Material3.*.BottomSheetDialog` variants, you will have more control over\nexactly what attributes are included in each, but it also means you'll have to\nduplicate any changes that you've made in your main theme into your custom\ntheme.\n", "markdown_path": "docs/components/BottomSheet.md", "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": null, "share_title": null}, "title": "Bottom sheets", "up_next_section": {"items": []}, "document_id": "4640185669255168"}, "mdc_flutter": {"banners": [], "hide_generic_not_available_message": false, "hide_intro_block": true, "image": [], "is_beta": false, "markdown_content": null, "markdown_path": null, "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": {}, "share_title": null}, "title": "Bottom Sheets", "up_next_section": {"items": []}, "document_id": "5472253978476544"}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google, Material Design 3, Material 3, Material You, Material Design Components, Material Components, components, cards", "meta_robots": null, "schema_structure": "{}", "share_description": "Bottom sheets show secondary content anchored to the bottom of the screen. There are two types of bottom sheets: standard and modal.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/c953bf9b2efdd14a850224135254c8b148a26adbce86d8a93dcf42439deb393f1ebbb519dc761df6c1569e1c08f757a88e4d533cc82dc8c7f4d25b16b781fb79", "height": 560, "url": "https://lh3.googleusercontent.com/anRizsTTKb3ZFDxvaOQnGhnaepLiJtk__kY2eOG1-X9tBEOZ_Efjd8vHU14mujMBUuRZXdKZjW6kZp32adjusmMOSOrgzXKXqvJHUUkEDF9C-tteNDyQ", "width": 1120}, "share_title": "Bottom sheets \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/423127aef1c64cb6a4d543d785647510ee752773c1e3730cd2aedeea5ce998522efed9ab837c46053e0b59e94b383b0626daf465340c81b7c98b05e944f9318d", "height": 1120, "url": "https://lh3.googleusercontent.com/LYDT9qYA1q7NLsDc9uG-q6ADc8znPvqUZ78u1oAg28gAsH6KDuUou2jk_OBbds4h3MDfZ0HwStPi5LPeXDGvpm7CkL1me_RlYTWXsHBmtW-FAYY-nXE", "width": 1120}, "foreground_image_1x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/2b1aa6610cb93219f521691df9d488f81e51d42cdf8515a454ad22f7f2820ed3c35ec81f42f80b2715a47e0d9cc6cff730ff516220572fa989ad9ccb7f1573e7", "height": 1120, "url": "https://lh3.googleusercontent.com/G9867ICt9b-lncJHHeVCxGxXlAKtIHq2Mzk4exKf7IkmAbj663wW-c4gIUsyeT0JfuNm8rrf1Hmo1wdCDS5AH0zScZNH8SLxn0iIi_58kS--vmVqPg", "width": 1120}, "foreground_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/f27e561a36c757333bc0e1671f30bf024bf5fc42d120495a9f443ce9cd207fa573c01d10b4ea977586470eeca1a134949841971504e59d1d12d34543974f2d72", "height": 1000, "url": "https://lh3.googleusercontent.com/6Xkb4jV_z0luNQskg19qC2PaETvm-JM49LlNOeqzfFiSXSmwae6J93dXBo7Jc442xJdZSENioqa28IsM406PXN_bPxo53-4kw5ZpXyj1lGKzOC2ORfSS", "width": 2000}, "foreground_image_2x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/22fc7f4780841efbb4c9acc5c9134eb76d84aec484c21dcc003c134fa90b77495aa6ed31efaaeec851096e2746ca4660aa396a49c45ed1726c6b1552b883d75c", "height": 1000, "url": "https://lh3.googleusercontent.com/XCWmA6moCnvUU5E2-0TNFM3MY2l4DlNkwRzwrjbD_ZHXcP-h2H02Y6UZ9juXVm4O0Eliok1wjM7kc4mZGRfRKEW_lS0DAk_qJdpPkG6gWtKozPpGOnfY", "width": 2000}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {}, "split_background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/6ab37909dc8478dd5e56137ee989c11507af974de96d6b52d7b04c096eaf500eb6cb297ecbc6d68d676634ef0c77bc196b4b50daf9101baf0a393f0d4e4d70c5", "height": 4096, "url": "https://lh3.googleusercontent.com/Zepnyf8JSnn6jKK6Zq6Ppm1oWSVdUMujaWc3pp-TMsk0U5THxsPYusqEIccnUary6eohY1UoVBgB7bQQ9FRgawuvXKDAPy2EPZwj6D9zgkRPV-breddj", "width": 4096}, "split_background_image_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/11266e9deb9db2deaab0114997d42033baa68f7cdc695f7f62dae5722a76b2e4787c5b96f0193b88c26968894dfbc41cc8fb0d07608fb463b21f5afd20ff238b", "height": 4096, "url": "https://lh3.googleusercontent.com/ewqelGlD5dUrp4LyDl4uyaS1aEAT0LqmTGwUblaNx6UlioWljMsus4141fu-waKli5dgu71O2g42Kl8owxFv6ijaFo_HTSnexyGaVHwF1DUqPEfW0Q", "width": 4096}, "vertical_foreground_alignment_override": null}, "title": "Bottom sheets", "document_id": "5317529291587584", "modified_date": "2025-04-25"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/dialogs.json b/evidence/surface/fetch/dialogs.json
new file mode 100644
index 0000000..6696384
--- /dev/null
+++ b/evidence/surface/fetch/dialogs.json
@@ -0,0 +1 @@
+{"category": "containment", "component_image_1x1": {}, "component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/1201b10f2aa29cc2b012aedf3d6767fa7b34b9a502457c68e1a6ef87c1b3d8c35e2f631bec3c785a03d0ee6e560e2004e6cf4527dc1faf03206476fde49d502f", "height": 560, "url": "https://lh3.googleusercontent.com/CFJfp5JSKy1CCK9X0jVO7pRomxEXLpvUPlj6biCd8V1zkvQAdNnnhWqE-pMeX8nol5yx9YwMikRapiuiahQLUEufqpxDJxs4w00HrUNUMcxLftTcddA", "width": 1120}, "component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/a8ee8e7fdedecf347ab7be12bdbe17ae43a145b06f8b6849806808fe705a329dae84930131c39debda19c5ebc03d60d93b102e96323f1a342e65c42354cb52e8", "height": 560, "url": "https://lh3.googleusercontent.com/vA2EVTxGzbpxA8uKcqA_kUbswA5Ip9NL9iuDq6XXU4DlNyAFNQaXu5H0JslNpWvfo0wqTABMQchMT2toI5YQFByNKhkty8pwj3cZXIXBsw0Hd5PwdBlx", "width": 1680}, "component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/667710b7bb2a7ea03afea363090125566b582bf944873a5fc55e158fc76d05a18f9784140bef9f4d631fe0392e2386d81aa854e59279c438d36a7e2cda9049c3", "height": 560, "url": "https://lh3.googleusercontent.com/asmiS26l6fx3OYk-LUie65WSh26b_c1zjpLUODiitaz_ICoFGQz-hyrnid0pw4GiCWNGy4incRNik8xuTNWjaMyPjKUQo5njyXuwdlm7A8yAFlCZIg", "width": 840}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/994d5fde6374e3edf539c37a962337f22e7ebcecb254b5b8f0b624245e2a34148282576570acac992f31fd10ad56d328f63e06536d38a5dfb0e0112711bcbe73", "height": 560, "url": "https://lh3.googleusercontent.com/8r_6V4X-Rw2Iywz74S0SHRsbe1Dghi2GmPHKHTqQ_AkOKhjWXsiJ9RUGx4l8n5WT17AHdj9E2ycJlIzqqPWJJ0Lii3C-WgXV1em_EEEtl4t0H1UGULg", "width": 1120}, "dark_component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/cf8967735ecfa675a864c392e728b94723b3d365ac8e0334c776fa4d2a3ed869e6a7514cd0f0671c753f33d891fd49a4d84450b8c05482c95e261603268075ba", "height": 560, "url": "https://lh3.googleusercontent.com/kVRpL11HJpgVz1WwKXoePGQs50bzRfd_vrk1gntt3VMrQDniwtkEinIYOj7CDeKh4j38EaxuR4OIXHao0ahKelQyT2fvNvB6-qMw7pplTaARrXLP9r-F", "width": 1680}, "dark_component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/720bedc77eae4ce24f71b551978a503ba999d9518f626b3478efe9166a76765ce767f84b59d5952c9bcca3cdc69fcac897ca20503ed5b0418fd57dee4cdca900", "height": 560, "url": "https://lh3.googleusercontent.com/UxQqwGi4wvijSnl77_1OLF9jpxNnS6zoadsG94JlTwHVusL-jOc5M2EMECCgSpuhp7euZlXdo2dj4s5o23F3puPqaLS6mS91DVS8ANeQGbNsGIrYBw", "width": 840}, "description": null, "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/374704d69859062037341f8f902b1efd04a623e626051d8249b8cd4ffe237f131bb0259de564e978f96a5ad0e3386721618b3cbb1f01890c63d94109c0f84fcc", "height": 4096, "url": "https://lh3.googleusercontent.com/p5D8lSFRzHHtJeJh9glEIalFFsCBHp0PBPImeTzekk3IE8mtEYxCMNXaj0TffIlcPkdFOjvjLf6Zp7SZDpNOA2e6M6jJNHoA5jRV5V0iSSE8AAljlZ4", "width": 4096}, "foreground_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/96b77eadf1dc3f9f97ed94edfdbe69a7716114344cb29f3a4ab0e9265945e617679c07754f984ed5d53fca0741176f1973d95bd76928ec9dd845487c81db3c1b", "height": 1816, "url": "https://lh3.googleusercontent.com/cD2FTVbrqtc_pZ7IwitArkWuRFGvQ_CHj-cuD76UiDUZZpjY2F0EmeUPmdLdf29NQKITPu540wiWTGIz4CbCZFzE_REolC9FEWXM6_pShckgW2Wg9Q", "width": 856}, "foreground_image_alignment": "center", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Components / Dialogs", "isDisplayed": true, "jetpack": {}, "mdc_android": {"banners": [{"description": "<p>Dialogs are available in the Material Design 3 library for Jetpack Compose. For implementation details, visit the&nbsp;<code>androidx.compose.material3</code> <a href=\"https://developer.android.com/jetpack/androidx/releases/compose-material3\" target=\"_blank\" rel=\"noopener\">library documentation on Android Developers</a>:</p>", "links": [{"aria_label": "Read about implementing Material Design 3 AlertDialogs using Jetpack Compose", "href": "https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#alertdialog", "label": "AlertDialog API reference", "open_new_window": true}], "title": "Jetpack Compose support available"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [{"a11y_description": "Examples of the two types of dialogs.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/4702378141911baecc1e6721afe2722cd953dbcece8c607f27ad431a1d2f3c59255d1b291781cfc8ea2251a4a42395ec674cec71ee85f8eb9712bffc963792d1", "height": 1036, "url": "https://lh3.googleusercontent.com/U3KG3u3LdCQsgAwfJMpOsk_RAZF1qYzBg-IVOQIqZEMmicfZu-1hHHHtfPTORjuMlP6zl5-gBV7ZMGoCxvQpGhL9_605HTMGUmVBBlSc8auT_9lV", "width": 1999}}, {"a11y_description": "\"Dialog with title, and text and purple buttons to cancel, decline or accept\"", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/641d369239c3c8122c7504ec20bb4734d7fa5e82211b760e7a2b353cafe5120bba9117af0a26e7d3726d8c9384f52e5c083ab8cd6df4b7eb8cea49f90703c8ed", "height": 687, "url": "https://lh3.googleusercontent.com/kEgwg9iNd9jboCKEfFrhvyJYod5D4ZALPrNd5Ru63Cqy4OG_FCX7zs8RU5AKBp1KrJxZzhGvu1QWG8dv1Z4Ngc0BYp8CChsqKcV8YFhnddJqRJU50ZQ", "width": 1080}}, {"a11y_description": "anatomy", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/34848ab749d6ff65f57f82b2c5ff5a54fe75ee3e7edafbe09cd860b75f16216d8409c6d0a3e044f13e4de1dd4c0db6b0f2c692c8265af4cc422f2939523b3b2e", "height": 970, "url": "https://lh3.googleusercontent.com/7GNdJqfCwAzo8wn9yzGsmGPeAFU3R3s6_A3VCdKX9u9cpGmQeCgnYni2t6CleU4bMEq01sBxsgQsNRJ2agc6lEdo5-j2angIeg87yqOTOTaaQS8Awbo", "width": 1410}}, {"a11y_description": "Dialog with title and text buttons in brown and selected radio button in pink", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/beb9fd6d806c96a1fc008977850761f1bc11c0e49fac272a021e11785fba46813bd8f6c66e31d1a6df3853f7cab78b7a242871798b0b94a20a09901925a8e0d5", "height": 737, "url": "https://lh3.googleusercontent.com/Ts8rbXjz2Oemc7LixUJrHcsXICUeM2tuHs89gPRfDL9pIfbLsHdu_5UUBCpx6cM8jkiFn3qAtNj3Ue0cpMTTzTprdhwjw-e45G4JrpaX51p4aHU9iOo", "width": 1080}}], "is_beta": false, "markdown_content": "<!--docs:\ntitle: \"Dialogs\"\nlayout: detail\nsection: components\nexcerpt: \"Dialogs are modal windows that require interaction.\"\niconId: dialog\npath: /catalog/dialogs/\n-->\n\n# Dialogs\n\n[Dialogs](https://material.io/components/dialogs/) inform users about a task and\ncan contain critical information, require decisions, or involve multiple tasks.\n\n![\"Dialog to confirm settings centered in a screen\"](assets/dialogs/dialogs_hero.png)\n\n**Contents**\n\n*   [Using dialogs](#using-dialogs)\n*   [Basic dialog](#basic-dialog)\n*   [Full-screen dialog](#full-screen-dialog)\n*   [Theming](#theming-dialogs)\n\n## Using dialogs\n\nBefore you can use Material dialogs, you need to add a dependency to the\nMaterial Components for Android library. For more information, go to the\n[Getting started](/libraries/mdc-android/getting-started)\npage.\n\n```kt\nMaterialAlertDialogBuilder(context)\n    // Add customization options here\n    .show()\n```\n\n### Making dialogs accessible\n\nThe contents within a dialog should follow their own accessibility guidelines,\nsuch as an icon on a title having a content description via the\n`android:contentDescription` attribute set in the\n`MaterialAlertDialog.Material3.Title.Icon` style or descendant.\n\n### Types\n\nThere are two types of dialogs: 1\\. [Basic dialog](#basic-dialog), 2\\.\n[Full-screen dialog](#full-screen-dialog)\n\n<mio-image index=0></mio-image>\n\n## Dialogs\n\nA dialog is a type of modal window that appears in front of app content to\nprovide critical information or ask for a decision. Dialogs disable all app\nfunctionality when they appear, and remain on screen until confirmed, dismissed,\nor a required action has been taken.\n\nDialogs are purposefully interruptive, so they should be used sparingly.\n\n### Dialog examples\n\nAPI and source code:\n\n*   `MaterialAlertDialogBuilder`\n    *   [Class description](https://developer.android.com/reference/com/google/android/material/dialog/MaterialAlertDialogBuilder)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/MaterialAlertDialogBuilder.java)\n\n## Basic dialog\n\nThe following example shows a basic dialog.\n\n<mio-image index=1></mio-image>\n\nIn code:\n\n```kt\nMaterialAlertDialogBuilder(context)\n        .setTitle(resources.getString(R.string.title))\n        .setMessage(resources.getString(R.string.supporting_text))\n        .setNeutralButton(resources.getString(R.string.cancel)) { dialog, which ->\n            // Respond to neutral button press\n        }\n        .setNegativeButton(resources.getString(R.string.decline)) { dialog, which ->\n            // Respond to negative button press\n        }\n        .setPositiveButton(resources.getString(R.string.accept)) { dialog, which ->\n            // Respond to positive button press\n        }\n        .show()\n```\n\n## Full-screen dialog\n\nFull-screen dialogs group a series of tasks, such as creating a calendar entry\nwith the event title, date, location, and time. Because they take up the entire\nscreen, full-screen dialogs are the only dialogs over which other dialogs can\nappear.\n\nThere is no specific Material implementation of a full-screen dialog. You can\nimplement it by using a\n[`DialogFragment`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment)\nas explained in the\n[Android Developer guides](https://developer.android.com/guide/topics/ui/dialogs#FullscreenDialog).\n\n### Anatomy and key properties\n\nA dialog has a container, content (either supporting text or a set of items of a\nparticular type), a background scrim, and, optionally, title and buttons.\n\n<mio-image index=2></mio-image>\n\n1.  Container\n2.  Icon (optional)\n3.  Title (optional)\n4.  Content\n5.  Buttons (optional)\n6.  Scrim\n\n#### Container attributes\n\nElement                             | **Attribute**                                            | **Related methods**                                    | **Default value**\n----------------------------------- | -------------------------------------------------------- | ------------------------------------------------------ | -----------------\n**Color**                           | N/A                                                      | N/A                                                    | `?attr/colorSurface`\n**Shape**                           | `app:shapeAppearance`<br/>`app:shapeAppearanceOverlay`   | N/A                                                    | `?attr/shapeAppearanceMediumComponent` with a corner size of `28dp`\n**Background inset start and end**  | `app:backgroundInsetStart`<br/>`app:backgroundInsetEnd`  | `setBackgroundInsetStart`<br/>`setBackgroundInsetEnd`  | `24dp`\n**Background inset top and bottom** | `app:backgroundInsetTop`<br/>`app:backgroundInsetBottom` | `setBackgroundInsetTop`<br/>`setBackgroundInsetBottom` | `80dp`\n\n#### Title attributes\n\nElement        | **Attribute**            | **Related methods**              | **Default value**\n-------------- | ------------------------ | -------------------------------- | -----------------\n**Text label** | N/A                      | `setTitle`<br/>`setCustomTitle`  | `null`\n**Text color** | `android:textColor`      | N/A                              | `?attr/colorOnSurface`\n**Typography** | `android:textAppearance` | N/A                              | `?attr/textAppearanceHeadlineSmall`\n**Icon**       | N/A                      | `setIcon`<br/>`setIconAttribute` | `null`\n**Icon tint**  | `app:tint`               | N/A                              | `?attr/colorSecondary`\n\n#### Content attributes\n\n**Supporting text**\n\nElement        | **Attribute**            | **Related methods** | **Default value**\n-------------- | ------------------------ | ------------------- | -----------------\n**Text**       | N/A                      | `setMessage`        | `null`\n**Color**      | `android:textColor`      | N/A                 | `?attr/colorOnSurfaceVariant`\n**Typography** | `android:textAppearance` | N/A                 | `?attr/textAppearanceBodyMedium`\n\n**List item**\n\nElement                                 | **Attribute**                  | **Related methods**    | **Default value**\n--------------------------------------- | ------------------------------ | ---------------------- | -----------------\n**List item layout**                    | `app:listItemLayout`           | `setItems`             | [`@layout/mtrl_alert_select_dialog_item`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_item.xml)\n**List item layout style**              | N/A                            | N/A                    | `?attr/materialAlertDialogBodyTextStyle`\n**List item text color**                | `android:textColor`            | N/A                    | `?attr/colorOnSurfaceVariant`\n**List item typography**                | `android:textAppearance`       | N/A                    | `?attr/textAppearanceBodyMedium`\n**Multi choice item layout**            | `app:multiChoiceItemLayout`    | `setMultiChoiceItems`  | [`@layout/mtrl_alert_select_dialog_multichoice`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_multichoice.xml)\n**Single choice item layout**           | `app:singleChoiceItemLayout`   | `setSingleChoiceItems` | [`@layout/mtrl_alert_select_dialog_singlechoice`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_singlechoice.xml)\n**Multi/single choice item style**      | `android:checkedTextViewStyle` | N/A                    | `@style/Widget.Material3.CheckedTextView`\n**Multi/single choice item text color** | `android:textColor`            | N/A                    | `?attr/colorOnSurfaceVariant`\n**Multi/single choice item typography** | `android:textAppearance`       | N/A                    | `?attr/textAppearanceBodyLarge`\n\n**Note:** You can set any custom view to be the content of your dialog via the\n`setView` method.\n\n#### Buttons attributes\n\nElement                                          | **Attribute**                     | **Related methods** | **Default value**\n------------------------------------------------ | --------------------------------- | ------------------- | -----------------\n**Buttons theme attributes (negative/positive)** | `app:buttonBar*ButtonStyle`       | N/A                 | `@style/Widget.Material3.Button.TextButton.Dialog`\n**Buttons theme attributes (neutral)**           | `app:buttonBarNeutralButtonStyle` | N/A                 | `@style/Widget.Material3.Button.TextButton.Dialog.Flush`\n**Buttons (neutral/negative/positive)**          | N/A                               | `set*Button`        | `null`\n**Icons**                                        | N/A                               | `set*ButtonIcon`    | `null`\n\nFor specific button attributes, see the\n[Buttons documentation](https://github.com/material-components/material-components-android/tree/master/docs/components/Button.md).\n\n#### Scrim attributes\n\nElement        | **Attribute**                 | **Related methods** | **Default value**\n-------------- | ----------------------------- | ------------------- | -----------------\n**Dim amount** | `android:backgroundDimAmount` | N/A                 | 32%\n\n#### Theme overlays\n\nElement                    | **Theme overlay**\n-------------------------- | -----------------\n**Default theme overlay**  | `ThemeOverlay.Material3.MaterialAlertDialog`\n**Centered theme overlay** | `ThemeOverlay.Material3.MaterialAlertDialog.Centered`\n\nDefault theme overlay attribute: `?attr/materialAlertDialogTheme`\n\n#### Theme attributes\n\nElement                   | **Theme attribute**                       | **Default value**\n------------------------- | ----------------------------------------- | -----------------\n**Default style**         | `?attr/alertDialogStyle`                  | `@style/MaterialAlertDialog.Material3`\n**Title text style**      | `?attr/materialAlertDialogTitleTextStyle` | `@style/MaterialAlertDialog.Material3.Title.Text`\n**Supporting text style** | `?attr/materialAlertDialogBodyTextStyle`  | `@style/MaterialAlertDialog.Material3.Body.Text`\n\nSee full list of\n[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/styles.xml),\n[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/attrs.xml),\nand\n[theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/themes.xml).\n\n## Theming dialogs\n\nA dialog supports\n[Material Theming](https://material.io/components/dialogs/#theming) which can\ncustomize color, typography and shape.\n\n### Dialog theming example\n\nAPI and source code:\n\n*   `MaterialAlertDialogBuilder`\n    *   [Class description](https://developer.android.com/reference/com/google/android/material/dialog/MaterialAlertDialogBuilder)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/MaterialAlertDialogBuilder.java)\n\nThe following example shows a dialog with Material Theming.\n\n<mio-image index=3></mio-image>\n\n#### Implementing dialog theming\n\nSetting the theme attribute `materialAlertDialogTheme` to your custom\n`ThemeOverlay` will affect all dialogs.\n\nIn `res/values/themes.xml`:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n  ...\n  <item name=\"materialAlertDialogTheme\">@style/ThemeOverlay.App.MaterialAlertDialog</item>\n</style>\n\n<style name=\"ThemeOverlay.App.MaterialAlertDialog\" parent=\"ThemeOverlay.Material3.MaterialAlertDialog\">\n    <item name=\"colorPrimary\">@color/shrine_pink_100</item>\n    <item name=\"colorSecondary\">@color/shrine_pink_100</item>\n    <item name=\"colorSurface\">@color/shrine_pink_light</item>\n    <item name=\"colorOnSurface\">@color/shrine_pink_900</item>\n    <item name=\"alertDialogStyle\">@style/MaterialAlertDialog.App</item>\n    <item name=\"materialAlertDialogTitleTextStyle\">@style/MaterialAlertDialog.App.Title.Text</item>\n    <item name=\"buttonBarPositiveButtonStyle\">@style/Widget.App.Button</item>\n    <item name=\"buttonBarNegativeButtonStyle\">@style/Widget.App.Button</item>\n</style>\n```\n\nIn `res/values/styles.xml`:\n\n```xml\n<style name=\"MaterialAlertDialog.App\" parent=\"MaterialAlertDialog.Material3\">\n    <item name=\"shapeAppearance\">@style/ShapeAppearance.App.MediumComponent</item>\n    <item name=\"shapeAppearanceOverlay\">@null</item>\n</style>\n\n<style name=\"MaterialAlertDialog.App.Title.Text\" parent=\"MaterialAlertDialog.Material3.Title.Text\">\n     <item name=\"android:textColor\">@color/shrine_pink_900</item>\n</style>\n\n  <style name=\"Widget.App.Button\" parent=\"Widget.Material3.Button.TextButton.Dialog\">\n    <item name=\"android:textColor\">@color/shrine_pink_900</item>\n  </style>\n\n<style name=\"ShapeAppearance.App.MediumComponent\" parent=\"ShapeAppearance.Material3.MediumComponent\">\n    <item name=\"cornerFamily\">cut</item>\n    <item name=\"cornerSize\">8dp</item>\n</style>\n```\n\nOr if you want to change only one specific dialog, pass the `themeResId` to the\nconstructor:\n\n```kt\nMaterialAlertDialogBuilder(context,  R.style.ThemeOverlay_App_MaterialAlertDialog)\n        ...\n        .show()\n```\n", "markdown_path": "docs/components/Dialog.md", "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": null, "share_title": null}, "title": "Dialogs", "up_next_section": {"items": []}, "document_id": "4969122496249856"}, "mdc_flutter": {"banners": [{"description": "<p>Dialogs are available in the Flutter Material library using the&nbsp;<a href=\"https://api.flutter.dev/flutter/material/ThemeData/useMaterial3.html\" target=\"_blank\" rel=\"noopener\"><code>useMaterial3</code></a>&nbsp;flag. For details on how to implement,&nbsp;<a href=\"https://api.flutter.dev/flutter/material/ThemeData/useMaterial3.html\" target=\"_blank\" rel=\"noopener\">visit the API documentation</a>.</p>", "links": [{"aria_label": "Read about implementing Material Design 3 Dialog using Flutter", "href": "https://api.flutter.dev/flutter/material/Dialog-class.html", "label": "Dialog API reference", "open_new_window": true}, {"aria_label": "Read about implementing Material Design 3 AlertDialog using Flutter", "href": "https://api.flutter.dev/flutter/material/AlertDialog-class.html", "label": "AlertDialog API reference", "open_new_window": true}], "title": "Flutter support available"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [], "is_beta": false, "markdown_content": null, "markdown_path": null, "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": {}, "share_title": null}, "title": "Dialogs", "up_next_section": {"items": []}, "document_id": "5240559261974528"}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, Material Design Components, Material Components, components, dialogs", "meta_robots": null, "schema_structure": "{}", "share_description": "Dialogs provide important prompts in a user flow. Use dialogs to make sure users act on information", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/645047f1a7e12769b092d3f1746d0a86fc87b52d90a065f64ae8582a5547fa67706ae0c2b4ca6193b7df3172692ae586d3368247bcdb349749ac862e2e7c6bfb", "height": 560, "url": "https://lh3.googleusercontent.com/mfskU6xDOqSsTCcgnGcsTfdCcT35ftTpCJmb4kuchYadG_41OF410XdGQP08L3iqFsq_pwIJ7_Zyf-8e-8J7nEwdNWMB-PqZGdICdnLsmHYfXy08Wrw", "width": 1120}, "share_title": "Dialogs \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/c26a0789742bad25a27d711dea8e655b1048515c311e47467b70ce19aada489175aeebb7b779c1dadfe85d429aec3c13715cea872735e5b59951114d5a593bc2", "height": 1120, "url": "https://lh3.googleusercontent.com/q-dfTEhPWF_-_eM4VpJrZA694bAqAO8BJMQMvVrDsqZ1kHyCOOhhnaXWYJw-wP3bGv6CXAKaEOrAxk2OEY47frCMhjGgp4ZZUtFsUCeMn0dthK0T8w", "width": 1120}, "foreground_image_1x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/9ed9fa99e47af01d81ae06cb058b307f64fe5ad80f518c46655fab1b66a8eb019aca19b27aaf200320caaaced0560bc0e68888d728194894bdd9710eb1080594", "height": 1120, "url": "https://lh3.googleusercontent.com/NFxYirrIZx8x5PbwPfor383cpP0mjHhJtIeXy-fAbo878fU2IJ5NEiRubwH3xHFVuN8J12QtUD6erRN6YCyx7e1OluYRzs8hYtRFer3K5oNn562hrOo", "width": 1120}, "foreground_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/16ec9ceebf3552311c38177ae3e547df730ad4398714a450983194b622471a59168f0d13e76f271096b27d3e5cf3d309a08de27408b08466dfad4e022ecd995c", "height": 1000, "url": "https://lh3.googleusercontent.com/euzNp7-lR2RlNLgwaPFT0mjcpki6eFepE5yrYjxsGmVn3Mi-3e7nmGiVWBdPKUYHKn9cWZncX_09QVYT_0QWdl8vbo88ajt3Usbeqv-_ypmB0pu43-9x", "width": 2000}, "foreground_image_2x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/22d90bf7a02bea312349422e7bc3a1a2b915f0a07b4d25e51fc5bef75cd7a3d2cbfe49fe6851f048ad712861e2ac09844daab502007b649de1103fde29ed466c", "height": 1000, "url": "https://lh3.googleusercontent.com/QfWucnJId1YNG8tBqQdCxL5aDcK5kcDxCo57DWf_e9_Q8y-W1Om1ulxFtF0WZI6V4W-bBxj7spcHt2vJx1LfnWFE_PMmQ-aRYS-kH2COxgwyAgmWJg8", "width": 2000}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {}, "split_background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/06a3ad2112a7a75e2a38793327f4e8e486d6c9419a6767c779d54d7dbbacfbc5490ff86f55d08ab821aa6e89881362465f8332e9bf5eb67b9c7c9bba8b59c6d6", "height": 4096, "url": "https://lh3.googleusercontent.com/ClaZSxMwSB7FD1hlooJt1hkkA2NiWXWIVrCHb1qizShsE2nNht2euUQm6BmS-C6B6nwzB8DUuuUjYy25E9weS5oMxQFkrWgcucbDtXtBobfs_riZootR", "width": 4096}, "split_background_image_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/04794fbf602312f722329bc76020840bdd22adb6c751aba94802088e571ebaff854cfb859c1cf2efc541f99ed8d274386b67b60c8ad4586e3d9a6079a1af0404", "height": 4096, "url": "https://lh3.googleusercontent.com/hORpCLy8XRY7280TZFng7WkrjURav7C3AApKqntCFUZnFZ4_NybzinpEA-HSGL46pPn_m96V4GL9t08BxTkkKmT3FX3SrRsUi2yWdQyzwQmUqzNSSMj7", "width": 4096}, "vertical_foreground_alignment_override": null}, "title": "Dialogs", "document_id": "5732087063379968", "modified_date": "2025-05-01"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/layout-applying.json b/evidence/surface/fetch/layout-applying.json
new file mode 100644
index 0000000..61b87c6
--- /dev/null
+++ b/evidence/surface/fetch/layout-applying.json
@@ -0,0 +1 @@
+{"category": null, "component_image_1x1": {}, "component_image_2x1": {}, "component_image_3x1": {}, "component_image_3x2": {}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {}, "dark_component_image_3x1": {}, "dark_component_image_3x2": {}, "description": "Use window size classes to create layouts that scale across most devices and form factors.", "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/2a62e31378857d6697036e05f7be96efbf388211a4d46eeefaecbe993b06d74be5826e0e9dcc08fc8b450c5b0faef9f061aebc8cce918d965b2aa7338b8833a6", "height": 1200, "url": "https://lh3.googleusercontent.com/CIyB5lCif4nv2PAOf5rXTP3F5QR1FrtGwOfF0nTi1YUu38kd9Q-16uQ4huiiaPFftqAgZqNM8JaymDXcxUb_P_4vASsP8hlP6jMDXXfezufgTRkMC9s", "width": 2400}, "foreground_image": {}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Foundations / Layout / Applying layout", "isDisplayed": true, "jetpack": {}, "mdc_android": {}, "mdc_flutter": {}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, adaptive, responsive, layouts", "meta_robots": " ", "schema_structure": "{}", "share_description": "Use window size classes to create layouts that scale across most devices and form factors.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/a5205fc1d66462945233e8abb82dd1a98633141a775cf9809bdfc8a8dbcd6bc2215cfc3309a640dceb773eca70977b133e878cd2e6b98ade4a377686ef149260", "height": 540, "url": "https://lh3.googleusercontent.com/9IC8KyAT2SkaRgd0oRs6Q9_EThFKVJQomkWlNMfvupqnnafcaoMNDpju-OSuXaKR5pvAwLF1NGQibVeKPdmwuisCTerH_NdiJdpxYi2AmD9QT_Nleg", "width": 960}, "share_title": "Applying layout \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {}, "foreground_image_1x1_dark_mode": {}, "foreground_image_2x1": {}, "foreground_image_2x1_dark_mode": {}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {"file_name": "Google_Mio_UnderstandingLayout_1080x1080.mp4", "file_path": "f3eb2abc4e890d68862f4d078fb6c1b39232bc11ccf12df23c1b7dd35eb6b7554fd0c937fd186d6340d5147c096764df5a2075bff03d3b64333cd60d0efd067a", "url": "https://kstatic.googleusercontent.com/files/f3eb2abc4e890d68862f4d078fb6c1b39232bc11ccf12df23c1b7dd35eb6b7554fd0c937fd186d6340d5147c096764df5a2075bff03d3b64333cd60d0efd067a"}, "split_background_image": {}, "split_background_image_dark_mode": {}, "vertical_foreground_alignment_override": null}, "title": "Applying layout", "document_id": "6396979944620032", "modified_date": "2024-05-10"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/manifest.yaml b/evidence/surface/fetch/manifest.yaml
new file mode 100644
index 0000000..a44b7e4
--- /dev/null
+++ b/evidence/surface/fetch/manifest.yaml
@@ -0,0 +1,17 @@
+schema_version: 1
+package: "surface_fetch_baseline"
+updated_at: "2026-02-23"
+source_run: "EXP-2026-02-22-longrun-001"
+source_path: "drafts/experiment/runs/EXP-2026-02-22-longrun-001/fetch"
+notes:
+  - "This fetch set was selected as the canonical preserved baseline."
+  - "Equivalent fetch sets existed in other drafts runs and were byte-identical."
+files:
+  - "bottom-sheets.json"
+  - "dialogs.json"
+  - "layout-applying.json"
+  - "menus.json"
+  - "motion-easing-duration.json"
+  - "motion-transitions.json"
+  - "navigation-drawer.json"
+  - "side-sheets.json"
diff --git a/evidence/surface/fetch/menus.json b/evidence/surface/fetch/menus.json
new file mode 100644
index 0000000..ad78789
--- /dev/null
+++ b/evidence/surface/fetch/menus.json
@@ -0,0 +1 @@
+{"category": "selection", "component_image_1x1": {}, "component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/f3d1d05fa3f98b7ed34577f6bf887203bd162e7b9345e649ff4cbf5fed67d6f6ab856ea9ccd72f468d1470880f1d9dc00bbeb72b9846dbb421bcda0fbc41139c", "height": 560, "url": "https://lh3.googleusercontent.com/k9FOfw5GEcyNWd-Iqc8zhd2qfWULlhXjaEnV_N_twzxIYtR77YiLgLEwGgcK-xdWA4uumfdX-aYKo_V8-Ufqarw-n2YmJqeNiyDcNEqza48A7eipbOg", "width": 1120}, "component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/205babd7b20c05185e7b46ac4fae5fb4d132f7ff66544af9160f3f36e424b640f0b0791be257bd8b2e8554e4af9cfc2312ca19b10da7f238ba6c331e917af67a", "height": 560, "url": "https://lh3.googleusercontent.com/xtpBXljEGhJN5JEnvNw2UVR_l_yng6IfOoCQGC6Ls4WxVvoROmN5O8qyvdCoIelP90wzZR3_QN41CDXlHgqZnw5_WjWIs9uPP8iI0K90lFQ_HsCLyh0", "width": 1680}, "component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/3e17b5ed53619638fe6ece233a0a31848381cf699b3685def701b7d49f8f9e5eb0561a077a3ca478c95d76ef770e8c5f80478a0a49b94522078eb5cf3c481fa5", "height": 560, "url": "https://lh3.googleusercontent.com/VxcZwSoYqM_KdhpHLPeAaM-KScIOFBt4uzxbifNaVrQwQYEw6ZbDh-ehhaBrd_lxWn5mTxUXUKb_foMmV-zYN-rd4vJOEl6cxWdZToarE8edli0mhp4", "width": 840}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/f46cfd9b67bc7fcda8898b95c5f15a6642f8d0227aceb890cb46d730bd4b57f3549972d614c76bfdc1a7ab9b5af623eb8ba675c431f01f1a6c28851962f30c48", "height": 560, "url": "https://lh3.googleusercontent.com/g-nOrn0GXf-nZJ22TwAM8ChICae6oDtnAVPPWnoe0JQ9Mh2OpWkl_qfQ45Q59YUZDv2ZCLnpierG13fE8UinLDi1xFNv1XyyYmiw0vf0wfqEjvadTJI", "width": 1120}, "dark_component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/89bb3e1f2cd4b1ca5e62e21f9042322a871a424e12dcb6c5b46d1fe57606f5283f9f5b73b9ecd354963a903739e7212af3fb8b950d30c5fbec2975419f26085e", "height": 560, "url": "https://lh3.googleusercontent.com/8qsTRu46sT7aR_EHcDRrbgTHAp_emItoya46tNkjc8u0i5UHbeo3u5kViYcYSXq8v0UeGyFXJeCDyJ8Nm4dqxpMc-gkASRqZDIa94rTnpXe5lCFBFNzQ", "width": 1680}, "dark_component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/aa0f1e028214700f1e8d3cccf8824090f78360e951eabac3341cd71dbb64778c761d6a2b42f075a87360a70de9a2aaa95682a11bdac4c679a0d2004cd2547daf", "height": 560, "url": "https://lh3.googleusercontent.com/4un3gOBZ2kAujd4tLWLaKBpPgfMyz0TEQzAcdQqRTj0KFe-snSi9L7Sqpe0rdFwruDkRvn4wlQmtqJPNY54F1fQeKkXuGlFHyKjLWB2JsdpAuPIyNN4", "width": 840}, "description": null, "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/7a8fa848b6b77f42495f75eafac551a09a53d560ca7a9430c7a5056f89ba232f0bb1fd6ef8b4888e8f33871e050a153c2d8eb677e4a8c45a68775a42c305784d", "height": 4096, "url": "https://lh3.googleusercontent.com/2fY0UpxDH_6NCU8n8L7xSnxSokFQqdA8qOWo_NNCU8ikQW5BhiP4Ha5aP_L0oYnFC8wtHdkEtxxC8CcGue6Tj_wrY7-QtEVsYjZziIasgck97JD4pIo", "width": 4096}, "foreground_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/ec9075bd851c86a3ae9930b62d7fefbc2cc4300973d11813ae6c8f7cbc2da2b00341136ab501bac4e3a8e8e85c144ced8f574fc89a1f0c25afa66c66b9f54cb1", "height": 1120, "url": "https://lh3.googleusercontent.com/1nhfDYUuWn2Y837J6niWOD9td-3BcYN1e83LtvwoWVyMrs16SQcxxWnr1dlxrQPyyTPe08aKzSlxetsVLWX1uBTyvdYRthlhgNrv5Q8UnxJGGbj1Ow", "width": 1120}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": true}, "ia_title": "Components / Menus", "isDisplayed": true, "jetpack": {}, "mdc_android": {"banners": [{"description": "<p>Menus are available in the Material Design 3 library for Jetpack Compose. For implementation details, visit the <code>androidx.compose.material3</code>&nbsp;<a href=\"https://developer.android.com/jetpack/androidx/releases/compose-material3\" target=\"_blank\" rel=\"noopener\">library documentation on Android Developers</a>:</p>", "links": [{"aria_label": "Read about implementing Material Design 3 AlertDialogs using Jetpack Compose", "href": "https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#DropdownMenu(kotlin.Boolean,kotlin.Function0,androidx.compose.ui.Modifier,androidx.compose.ui.unit.DpOffset,androidx.compose.ui.window.PopupProperties,kotlin.Function1)", "label": "DropdownMenu API Reference", "open_new_window": true}, {"aria_label": "Read about implementing Material Design 3 ExposedDropdownMenu using Jetpack Compose", "href": "https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#ExposedDropdownMenuBox(kotlin.Boolean,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1)", "label": "ExposedDropdownMenu API Reference", "open_new_window": true}], "title": "Jetpack Compose support available"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [{"a11y_description": "Menu hero example", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/da9bc72e7ce22d5466d4932275b9af1a2c798a87b47943fc3c8be1e70e12255833c07378041e1cd278e80620c1076ce4929d72b2b37ccb282d449b6ab54f7020", "height": 754, "url": "https://lh3.googleusercontent.com/Kb7vuTWlHrnwuv-8taEKtQZuTzKta54HxDNsUzN864yfInGGIx333w1VErFA8zlmFEW8hRa9JDXi-K6wUy-ReZQHERNZH4CA273evW3urLrys-KsYQ", "width": 1999}}, {"a11y_description": "Composite image of example dropdown and exposed dropdown menu types", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/13e3ee536262916e9edd4ea67762d836c54d571e515ce1234308e96abcede4082375a2aec11cc9c6b82050663ed69a456182b3ff18cc83ad7da8eb17fd944ab5", "height": 940, "url": "https://lh3.googleusercontent.com/X_D_If_smcA-GPD4A-USkWJgj0UgT9YSx2JmTcxI7dfvJiKU7M08lpFsc8-MNb-ZHuh5jVwpx5b6eeMuzlpNVmt0F6MbSVjvL63oGlzeJLFEjBarQeQ", "width": 2048}}, {"a11y_description": "Composite image: purple \"Menus\" bar, and purple \"Menus\" bar with white menu\nand 3 options", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/d5dadc3e2f0d1b341fb784613fcb87fde6231cc9803588b5b56f06415e5106f66cae8dba24edb84ee928dd94aea9f6f1a78e67b9fefa89bf09a46e1fa969c64c", "height": 650, "url": "https://lh3.googleusercontent.com/gh99kXdWMairaR0nsNpVkgE90_dMb74HMzoPfxFIZwIJo2vkJ3wKL8Nd87QdKXqaA1zFImD3ACa0sUbuqpQ1WYU5QapTEB8JOuO18JZLERWbE_d_n9c", "width": 1080}}, {"a11y_description": "White menu window with two options floating over a white background with grey\ntext", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/c308438bedef64d236cf034176a68e6bd5c4758eeb0a6e9e91c4762dfd5da830ac7f340ada2280d0210d57412bf6b0b1886a4e2f05b65e05598079b083683520", "height": 463, "url": "https://lh3.googleusercontent.com/j4Crs8v0RxV8F4W40NQ78y8IANvZfG4ra-hAXxP3qe5WVYycY91eVpyfEQbNZ9vX11qryv-lEK0GO1DoI6laBsoOkxjBHpDGH_Gy0lWx2gzZBVfrjA", "width": 1080}}, {"a11y_description": "White menu container with 3 options open below a purple \"Show menu\" button", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/3a9ece693f83eb50c0810d14bc629f88293aa830fe94487f17bbe440a9a7a3b59cd558f6819e2fb6e38842aca960d9eb7e53b0da8698c6166cee415efb52b071", "height": 655, "url": "https://lh3.googleusercontent.com/n--GNHXqdi6IAWHN4AqGWHN8hWZ1D2Zp2Vzz4H5Hyn13DCUjQtJYxTg8QEA3KVNSJ_32X4SPuwRJrMHveZwvqwxBaKXptGRO3OwUamedoPtLMiVW3nw", "width": 1080}}, {"a11y_description": "White menu window with 3 options open below a purple \"Show menu\" button. Each\noption has an icon.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/243744613f0f55c96c0f809d11beb9598662c3525f4942dfe6c5bf5981be692b55bc48d382d1f6814dff115788a6e93392e5870eb6f6df474faa23f49126c677", "height": 746, "url": "https://lh3.googleusercontent.com/DQC8wOdRISEh_rVPd8uCJryHd1SvjzYkKBSiSkCd6-9Zm1Cpwafo5cRWWqh6xfhby-6xgKNazfOnjDRy0zNkBNYtUkUJ8xMNs_05Cr-bV8QsJ96Zhrkb", "width": 1080}}, {"a11y_description": "White menu container with 3 options below a purple \"Show menu\" button", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/7f7449899e6653b6854d950c1ec540034cb2dbfdccbd5f150950d2cd1bfc2d6065595a02bd2d1a855dd2b24f3c12bcfbddcff952dd54e98cc9419e59b4d9ef69", "height": 851, "url": "https://lh3.googleusercontent.com/dUS2p3rCcRYLLAqbINsDJNG6BS35MCimP6RCHjoEPybt7rCmylcw6umvXSxSbZLPM1_Nw-baGHJxQTRGYoHlevsSK2jvvI2Qmf4BMHyRjyiEcfA2krE", "width": 1080}}, {"a11y_description": "Menus anatomy diagrams", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/3fdf3f958e1e19bdd6e730ab63e3bdea088c222eb1f7ccb8eb5dfc50e30aa17285220a071ded0ee7a7b3cc1404cce78a3ce71194f354b02952bac496eecea132", "height": 1045, "url": "https://lh3.googleusercontent.com/laHuXPSZTM4O_vqnZXda7hziGjy9ASSB-iISC1EyQ3d_7SXZNLp0JXMi795PoYeXC0YO1dfEtUcPh2uNAmXFvLUkW9hwxQqERmpKwN7OqF8GM8OfIx3O", "width": 1999}}, {"a11y_description": "2 menu states with text field element: 1) has \"item 1\", 2) has \"item 1\" and a\n4-item menu container.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/fc19c6475eac357ad6f5095c449c90472faceca82417de3dc23a06ace9264596e4ccacff8d9f6b004cba367cdc43daedf1b1cf6b367962433cb9a2ddd49a96d9", "height": 1088, "url": "https://lh3.googleusercontent.com/wAY6SANH7FSIDjD3unZacLO13lhDGveMKaa0SPRYxXSb2DYIRMlGsZ5_439T_YMs9oCv47QCPxqlSz5avTVR9XfI9Ln_o1OcHxWMuYwyVMl_CgKmiZQ", "width": 1080}}, {"a11y_description": "Menu with purple outlined text field element and 4 items. Item 1 selected.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/24ebf0ae74d894bdbd3a3866451ee6b4ca89aae5d40a6dff81bc98ca61036daffd5ccc7ae5927fe5170b1bf157955bada93c8a723da4f4c4f1c070f3ae2ed8b5", "height": 806, "url": "https://lh3.googleusercontent.com/50YgYjtYrYt-pt2z0cbeScd46k87_auB_rG8WzXaI-XH6dsdrn1CrI2C6uy9Peff1MxlyO5EEpOU3x2Jvjzb0DJq844Tg34zCimJruqLXIe-jsCQww", "width": 1080}}, {"a11y_description": "Exposed dropdown menu anatomy diagram", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/899b0462ee201be46c303101b746518dcabc60bd3bcf192fc713d74b7f9ac6c47612039c93bbfce86c3c3891ec71d26316d1428db98df0998f3ebc1c1c6442d9", "height": 1070, "url": "https://lh3.googleusercontent.com/-UN5DIcokiLQt7ga1W60Cgn7jOvXipS0dEOoHTIyj_AAs9PvkqbXZZpeHaXHib0jbBoK3nlFNVBRBjQsRCYnqWxkmICedLpAA3EbjvXBYc-34INabOc", "width": 2048}}, {"a11y_description": "White menu container with brown text showing 3 options", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/1764ef3c118e224429b07bf02f93685a5cc7519afda3744d917a3133226e0aeeadef6ca81491b417075e05c2dd39fb499b322f52b6c2edeaa92d1d97e711f32e", "height": 294, "url": "https://lh3.googleusercontent.com/D12ZcYdcTC8C6Opc_SwZbJ5hA5rCeVZo8hkTEtuawp0WZZ8P3bSSpbGWuar3_ehXTGwLI5AE2GVbixeehq3g2CanaIy7SWB5ZWx7awEkmSaD9c38XK4", "width": 400}}, {"a11y_description": "Composite image of \"Show menu\" button and options: gray button with pink\nunderline, and white button with pink\noutline", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/2f6fe3ba4e94014212938f293059220eb01ad09b5e8d0493f5f62f19eee576ad0f4b91f1418c3e25ec9e8eae775a23fc9b3ed75bb96463bd1099b05602e46156", "height": 363, "url": "https://lh3.googleusercontent.com/MRNcysCTiR5Z9bsP_I3LkcLnvFTCl5ZIWdQrkjfeMUe4-YuhoI8duuHM7syR5q3m3pWUCi-6HI4Zm2ZSBbznP4A3_9Ylvbx8i4BK4uafeet1ClZat29o", "width": 1000}}], "is_beta": false, "markdown_content": "<!--docs:\ntitle: \"Menus\"\nlayout: detail\nsection: components\nexcerpt: \"Menus display a list of choices on temporary surfaces.\"\niconId: menu\npath: /catalog/menus/\n-->\n\n# Menus\n\n[Menus](https://material.io/components/menus) display a list of choices on\ntemporary surfaces.\n\n<mio-image index=0></mio-image>\n\n**Contents**\n\n*   [Using menus](#using-menus)\n*   [Dropdown menus](#dropdown-menus)\n*   [Exposed dropdown menus](#exposed-dropdown-menus)\n*   [Theming](#theming-menus)\n\n## Using menus\n\nA menu displays a list of choices on a temporary surface. They appear when users\ninteract with a button, action, or other control.\n\nBefore you can use Material menus, you need to add a dependency to the Material\nComponents for Android library. For more information, go to the\n[Getting started](/libraries/mdc-android/getting-started)\npage.\n\nA typical menu resource looks like this:\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<menu xmlns:android=\"http://schemas.android.com/apk/res/android\">\n    <item android:id=\"@+id/option_1\"\n          android:title=\"@string/option_1\" />\n    <item android:id=\"@+id/option_2\"\n          android:title=\"@string/option_2\" />\n    <item android:id=\"@+id/option_3\"\n          android:title=\"@string/option_3\" />\n</menu>\n```\n\nA typical exposed dropdown menu looks like this:\n\n```xml\n<com.google.android.material.textfield.TextInputLayout\n    android:id=\"@+id/menu\"\n    style=\"@style/Widget.Material3.TextInputLayout.FilledBox.ExposedDropdownMenu\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:hint=\"@string/label\">\n\n    <AutoCompleteTextView\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"wrap_content\"\n        android:inputType=\"none\"\n    />\n\n</com.google.android.material.textfield.TextInputLayout>\n```\n\nSee the [dropdown menus](#dropdown-menus) and\n[exposed dropdown menus](#exposed-dropdown-menus) sections for detailed usage\ninformation.\n\n### Making menus accessible\n\nMenus are readable by most screen readers, such as TalkBack. Text rendered in\nmenus is automatically provided to accessibility services. Additional content\nlabels are usually unnecessary.\n\nAndroid's exposed dropdown menu component APIs support both label text and\nhelper text, which tell the user what information is requested for a menu. While\noptional, their use is strongly encouraged. For more information about this\ncomponent's accessibility, check out\n[the text field's a11y section](https://www.github.com/material-components/material-components-android/tree/master/docs/components/TextField.md#making-text-fields-accessible).\n\n### Types\n\nMenus allow users to make a selection from multiple options. They are less\nprominent and take up less space than selection controls, such as a set of radio\nbuttons.\n\nThere are two types of menus: 1\\. [Dropdown menus](#dropdown-menus) (overflow,\ncontext, popup, and list popup window menus), 2\\.\n[Exposed dropdown menus](#exposed-dropdown-menus).\n\n<mio-image index=1></mio-image>\n\n## Dropdown menus\n\nDropdown menus display a list of options, triggered by an icon, button, or\naction. Their placement varies based on the element that opens them.\n\n### Dropdown menu examples\n\nAPI and source code:\n\n*   `Menu`\n    *   [Class definition](https://developer.android.com/reference/android/view/Menu)\n*   `MenuInflater`\n    *   [Class definition](https://developer.android.com/reference/android/view/MenuInflater)\n*   `ContextMenu`\n    *   [Class definition](https://developer.android.com/reference/android/view/ContextMenu)\n*   `PopupMenu`\n    *   [Class definition](https://developer.android.com/reference/android/widget/PopupMenu)\n*   `ListPopupWindow`\n    *   [Class definition](https://developer.android.com/reference/android/widget/ListPopupWindow)\n\n#### Overflow menus\n\nThe following example shows an overflow menu.\n\n<mio-image index=2></mio-image>\n\nIn code:\n\n```kt\noverride fun onCreateOptionsMenu(menu: Menu): Boolean {\n    val inflater: MenuInflater = menuInflater\n    inflater.inflate(R.menu.overflow_menu, menu)\n    return true\n}\n```\n\nIn `res/menu/overflow_menu.xml`:\n\n```xml\n<menu xmlns:android=\"http://schemas.android.com/apk/res/android\">\n    <item android:id=\"@+id/option_1\"\n          android:title=\"@string/option_1\" />\n    <item android:id=\"@+id/option_2\"\n          android:title=\"@string/option_2\" />\n    <item android:id=\"@+id/option_3\"\n          android:title=\"@string/option_3\" />\n</menu>\n```\n\n#### Context menus\n\nThe following example shows a context menu that appears when a `TextView` is\npressed for a designated amount of time.\n\n<mio-image index=3></mio-image>\n\nIn code:\n\n```kt\noverride fun onCreate(savedInstanceState: Bundle?) {\n    ...\n    val contextMenuTextView = view.findViewById<TextView>(R.id.context_menu_tv)\n    // Register context menu for TextView\n    registerForContextMenu(contextMenuTextView)\n}\n\noverride fun onCreateContextMenu(menu: ContextMenu, v: View, menuInfo: ContextMenu.ContextMenuInfo?) {\n    val contextMenuTextView = v as TextView\n    val context = context\n    // Add menu items via menu.add\n    menu.add(R.string.option_1)\n        .setOnMenuItemClickListener { item: MenuItem? ->\n            // Respond to item click.\n      }\n    menu.add(R.string.option_2)\n        .setOnMenuItemClickListener { item: MenuItem? ->\n            // Respond to item click.\n      }\n}\n\noverride fun onContextMenuClosed(menu: Menu) {\n    // Respond to context menu being closed.\n}\n```\n\nIn the layout:\n\n```xml\n<TextView\n    android:id=\"@+id/context_menu_tv\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:padding=\"16dp\"\n    android:text=\"@string/menu_context_menu_description\"/>\n```\n\nAlternatively, you can inflate a context menu in `onCreateContextMenu` (as with\nthe overflow menu):\n\n```kt\noverride fun onCreateContextMenu(menu: ContextMenu, v: View, menuInfo: ContextMenu.ContextMenuInfo?) {\n  super.onCreateContextMenu(menu, v, menuInfo)\n  val inflater: MenuInflater = menuInflater\n  inflater.inflate(R.menu.context_menu, menu)\n}\n\n// Then, to handle clicks:\noverride fun onContextItemSelected(item: MenuItem): Boolean {\n  val info = item.menuInfo as AdapterView.AdapterContextMenuInfo\n  return when (item.itemId) {\n    R.id.option_1 -> {\n      // Respond to context menu item 1 click.\n      true\n    }\n    R.id.option_2 -> {\n      // Respond to context menu item 2 click.\n      true\n    }\n    else -> super.onContextItemSelected(item)\n  }\n}\n```\n\nwith a `res/menu/context_menu.xml`:\n\n```xml\n<menu xmlns:android=\"http://schemas.android.com/apk/res/android\">\n    <item android:id=\"@+id/option_1\"\n          android:title=\"@string/option_1\" />\n    <item android:id=\"@+id/option_2\"\n          android:title=\"@string/option_2\" />\n</menu>\n```\n\n#### Popup menus\n\nThe following example shows a popup menu that displays when a button is clicked.\n\n<mio-image index=4></mio-image>\n\nIn code:\n\n```kt\noverride fun onCreate(savedInstanceState: Bundle?) {\n    ...\n    val button = view.findViewById<Button>(R.id.menu_button)\n    button.setOnClickListener { v: View ->\n        showMenu(v, R.menu.popup_menu)\n    }\n}\n\nprivate fun showMenu(v: View, @MenuRes menuRes: Int) {\n    val popup = PopupMenu(context!!, v)\n    popup.menuInflater.inflate(menuRes, popup.menu)\n\n    popup.setOnMenuItemClickListener { menuItem: MenuItem ->\n        // Respond to menu item click.\n    }\n    popup.setOnDismissListener {\n        // Respond to popup being dismissed.\n    }\n    // Show the popup menu.\n    popup.show()\n}\n```\n\nIn the layout:\n\n```xml\n<Button\n    android:id=\"@+id/menu_button\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/show_menu\"/>\n```\n\nIn `res/menu/popup_menu.xml`:\n\n```xml\n<menu xmlns:android=\"http://schemas.android.com/apk/res/android\">\n    <item android:id=\"@+id/option_1\"\n          android:title=\"@string/option_1\" />\n    <item android:id=\"@+id/option_2\"\n          android:title=\"@string/option_2\" />\n    <item android:id=\"@+id/option_3\"\n          android:title=\"@string/option_3\" />\n</menu>\n```\n\n##### Adding icons to popup menus\n\nCurrently, there is no public API to add icons to popup menus. The following\nworkaround is for API 21+, and uses library-only APIs, and is not guaranteed to\nwork in future versions.\n\nThe following example shows a popup menu with icons.\n\n<mio-image index=5></mio-image>\n\nIn code:\n\n```kt\n//In the showMenu function from the previous example:\nprivate fun showMenu(v: View, @MenuRes menuRes: Int) {\n    val popup = PopupMenu(context!!, v)\n    popup.menuInflater.inflate(menuRes, popup.menu)\n    ...\n    if (popup.menu is MenuBuilder) {\n        val menuBuilder = popup.menu as MenuBuilder\n        menuBuilder.setOptionalIconsVisible(true)\n        for (item in menuBuilder.visibleItems) {\n            val iconMarginPx =\n                TypedValue.applyDimension(\n                    TypedValue.COMPLEX_UNIT_DIP, ICON_MARGIN.toFloat(), resources.displayMetrics)\n                .toInt()\n            if (item.icon != null) {\n              if (Build.VERSION.SDK_INT > Build.VERSION_CODES.LOLLIPOP) {\n                  item.icon = InsetDrawable(item.icon, iconMarginPx, 0, iconMarginPx,0)\n              } else {\n                  item.icon =\n                      object : InsetDrawable(item.icon, iconMarginPx, 0, iconMarginPx, 0) {\n                          override fun getIntrinsicWidth(): Int {\n                              return intrinsicHeight + iconMarginPx + iconMarginPx\n                      }\n                }\n              }\n          }\n      }\n    }\n    ...\n    popup.show()\n}\n```\n\nIn `res/menu/popup_menu.xml`:\n\n```xml\n<menu xmlns:android=\"http://schemas.android.com/apk/res/android\">\n    <item android:id=\"@+id/option_1\"\n          android:icon=\"@drawable/ic_3d_rotation_24dp\"\n          android:title=\"@string/option_1\" />\n    <item android:id=\"@+id/option_2\"\n          android:icon=\"@drawable/ic_accelerator_24dp\"\n          android:title=\"@string/option_2\" />\n    <item android:id=\"@+id/option_3\"\n          android:icon=\"@drawable/ic_favorite_24dp\"\n          android:title=\"@string/option_3\" />\n</menu>\n```\n\n#### List popup window menus\n\nThe following example shows a list popup window menu that appears when a button\nis clicked.\n\n<mio-image index=6></mio-image>\n\nIn code:\n\n```kt\nval listPopupWindowButton = view.findViewById<Button>(R.id.list_popup_button)\nval listPopupWindow = ListPopupWindow(context!!, null, R.attr.listPopupWindowStyle)\n\n// Set button as the list popup's anchor\nlistPopupWindow.anchorView = listPopupWindowButton\n\n// Set list popup's content\nval items = listOf(\"Item 1\", \"Item 2\", \"Item 3\", \"Item 4\")\nval adapter = ArrayAdapter(requireContext(), R.layout.list_popup_window_item, items)\nlistPopupWindow.setAdapter(adapter)\n\n// Set list popup's item click listener\nlistPopupWindow.setOnItemClickListener { parent: AdapterView<*>?, view: View?, position: Int, id: Long ->\n  // Respond to list popup window item click.\n\n  // Dismiss popup.\n  listPopupWindow.dismiss()\n}\n\n// Show list popup window on button click.\nlistPopupWindowButton.setOnClickListener { v: View? -> listPopupWindow.show() }\n```\n\nIn the layout:\n\n```xml\n<Button\n    android:id=\"@+id/list_popup_button\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:text=\"@string/show_menu\"/>\n```\n\nIn the item layout `res/layout/list_popup_window_item.xml`:\n\n```xml\n<TextView\n    xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:padding=\"16dp\"\n    android:ellipsize=\"end\"\n    android:maxLines=\"1\"\n    android:textAppearance=\"?attr/textAppearanceBodyLarge\"\n/>\n```\n\n### Anatomy and key properties\n\nThe following are menu anatomy diagrams showing all possible elements:\n\n<mio-image index=7></mio-image>\n\n1.  List item\n2.  Leading icon\n3.  Trailing icon\n4.  Trailing text\n5.  Container\n6.  Divider\n\n#### Container attributes\n\nElement        | Attribute                     | Related method(s) | Default value\n-------------- | ----------------------------- | ----------------- | -------------\n**Background** | `android:popupMenuBackground` | N/A               | `?attr/popupMenuBackground`\n**Color**      | N/A                           | N/A               | `?attr/colorSurface`\n**Elevation**  | `android:popupElevation`      | N/A               | `3dp`\n\n#### Text attributes\n\nElement        | Attribute                                                                     | Related method(s)                                                  | Default value\n-------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------\n**Text label** | `android:title`                                                               | `getMenu().add`<br/>`getMenu().addSubMenu`<br/>`getMenu().getItem` | N/A\n**Typography** | `?attr/textAppearanceLargePopupMenu`<br/>`?attr/textAppearanceSmallPopupMenu` | N/A                                                                | `?attr/textAppearanceBodyLarge`\n\n#### Styles\n\nElement                     | **Theme attribute**              | **Default value**\n--------------------------- | -------------------------------- | -----------------\n**Popup menus**             | `?attr/popupMenuStyle`           | `@style/Widget.Material3.PopupMenu`\n**List popup window style** | `?attr/listPopupWindowStyle`     | `@style/Widget.Material3.PopupMenu.ListPopupWindow`\n**Context menus**           | `?android:contextPopupMenuStyle` | `@style/Widget.Material3.PopupMenu.ContextMenu`\n**Overflow menus**          | `?attr/actionOverflowMenuStyle`  | `@style/Widget.Material3.PopupMenu.Overflow`\n\nSee the full list of\n[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/menu/res/values/styles.xml)\nand\n[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/menu/res/values/attrs.xml).\n\n## Exposed dropdown menus\n\nExposed dropdown menus display the currently selected menu item above a list of\noptions. Some variations can accept user-entered input.\n\n**Note:** The exposed dropdown menu is implemented through the\n`TextInputLayout`. For detailed information on\n[Material text fields](https://material.io/design/components/text-fields.html)\nand their usage, see the [TextInputLayout documentation](components/text-fields).\n\n### Exposed dropdown menu example\n\nAPI and source code:\n\n*   `TextInputLayout`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/textfield/TextInputLayout)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/TextInputLayout.java)\n*   `AutoCompleteTextView`\n    *   [Class definition](https://developer.android.com/reference/android/widget/AutoCompleteTextView)\n*   `MaterialAutoCompleteTextView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/textfield/MaterialAutoCompleteTextView)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/MaterialAutoCompleteTextView.java)\n\n**Note:** `MaterialComponentsViewInflater` auto-inflates\n`<AutoCompleteTextView>` to\n`<com.google.android.material.textfield.MaterialAutoCompleteTextView>` when\nusing `Theme.Material3.*` themes.\n\nThe following is an example of a filled exposed dropdown menu:\n\n<mio-image index=8></mio-image>\n\nIn the layout:\n\n```xml\n<com.google.android.material.textfield.TextInputLayout\n    android:id=\"@+id/menu\"\n    style=\"@style/Widget.Material3.TextInputLayout.FilledBox.ExposedDropdownMenu\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:hint=\"@string/label\">\n\n    <AutoCompleteTextView\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"wrap_content\"\n        android:inputType=\"none\"\n        app:simpleItems=\"@array/simple_items\"\n    />\n\n</com.google.android.material.textfield.TextInputLayout>\n```\n\nThe string array specified by `app:simpleItems` will be used as the default\nitem strings for auto-completion. Or you can also set it programmatically:\n\n```kt\nval items = arrayOf(\"Item 1\", \"Item 2\", \"Item 3\", \"Item 4\")\n(textField.editText as? MaterialAutoCompleteTextView)?.setSimpleItems(items)\n```\n\nAlternatively, to have more control over the auto-completion items rendering,\nyou can also provide a custom item adapter by:\n\n```kt\nval items = listOf(\"Item 1\", \"Item 2\", \"Item 3\", \"Item 4\")\nval adapter = ArrayAdapter(requireContext(), R.layout.list_item, items)\n(textField.editText as? AutoCompleteTextView)?.setAdapter(adapter)\n```\n\nAnd a custom item layout (`list_item.xml`):\n\n```xml\n<TextView\n    xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:padding=\"16dp\"\n    android:ellipsize=\"end\"\n    android:maxLines=\"1\"\n    android:textAppearance=\"?attr/textAppearanceBodyLarge\"\n/>\n```\n\nTo use the exposed dropdown menu with an outlined text field, set the `style` to\n`@style/Widget.Material3.TextInputLayout.OutlinedBox.ExposedDropdownMenu`:\n\n<mio-image index=9></mio-image>\n\n#### Non editable variation\n\nFor a non-editable menu, disable the user input in the `AutoCompleteTextView` by\nsetting `android:inputType=\"none\"` on the `AutoCompleteTextView`.\n\n#### Setting a default value\n\nIn order to have a pre-selected value displayed, you can call\n`setText(CharSequence text, boolean filter)` on the `AutoCompleteTextView` with\nthe filter set to `false`.\n\n### Anatomy and key properties\n\nThe exposed dropdown menu is an `AutoCompleteTextView` within a\n`TextInputLayout`. It displays a dropdown menu below a text field.\n\n<mio-image index=10></mio-image>\n\n1.  Text\n2.  Container\n3.  Label\n4.  Selection/Input text\n5.  Trailing icon\n\n#### `TextInputLayout` attributes (container, label, trailing icon)\n\nFor all attributes that apply to the `TextInputLayout`, see the\n[TextInputLayout documentation](components/text-fields).\n\n#### `MaterialAutoCompleteTextView` attributes (input text, dropdown menu)\n\nElement                                   | Attribute                                                           | Related method(s)                                                             | Default value\n----------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------\n**Input text**                            | `android:text`                                                      | `setText`<br/>`getText`                                                       | `@null`\n**Typography**                            | `android:textAppearance`                                            | `setTextAppearance`                                                           | `?attr/textAppearanceBodyLarge`\n**Input accepted**                        | `android:inputType`                                                 | `N/A`                                                                         | framework's default\n**Input text color**                      | `android:textColor`                                                 | `setTextColor`<br/>`getTextColors`<br/>`getCurrentTextColor`                  | `?android:textColorPrimary`\n**Cursor color**                          | N/A (color comes from the theme attr `?attr/colorControlActivated`) | N/A                                                                           | `?attr/colorPrimary`\n**Dropdown menu<br/>container color**     | N/A                                                                 | N/A                                                                           | `?attr/colorSurface`\n**Dropdown menu elevation**               | `android:popupElevation`                                            | `getPopupElevation`                                                           | `3dp`\n**Simple items**                          | `app:simpleItems`                                                   | `setSimpleItems`                                                              | `null`\n**Simple item layout**                    | `app:simpleItemLayout`                                              | N/A                                                                           | `@layout/m3_auto_complete_simple_item`\n**Selected simple item color**            | `app:simpleItemSelectedColor`                                       | `setSimpleItemSelectedColor`<br/>`getSimpleItemSelectedColor`                 | `?attr/colorSurfaceVariant`\n**Selected simple item<br/>ripple color** | `app:simpleItemSelectedRippleColor`                                 | `setSimpleItemSelectedRippleColor`<br/>`getSimpleItemSelectedRippleColor`     | `@color/m3_simple_item_ripple_color`\n\n#### Styles\n\nElement            | Style\n------------------ | -----\n**Filled style**   | `Widget.Material3.TextInputLayout.FilledBox.ExposedDropdownMenu`\n**Outlined style** | `Widget.Material3.TextInputLayout.OutlinedBox.ExposedDropdownMenu`\n**Filled dense**   | `Widget.Material3.TextInputLayout.FilledBox.Dense.ExposedDropdownMenu`\n**Outlined dense** | `Widget.Material3.TextInputLayout.OutlinedBox.Dense.ExposedDropdownMenu`\n\nDefault style theme attribute: `?attr/textInputStyle`\n\nSee the full list of\n[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/res/values/styles.xml)\nand\n[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/res/values/attrs.xml).\n\n## Theming menus\n\nMenus drawers support\n[Material Theming](https://material.io/components/text-fields/#theming) which\ncan customize color, typography and shape.\n\n### Menu theming examples\n\nPopup, overflow, and list popup window menus support\n[Material Theming](https://material.io/components/chips/#theming) which can\ncustomize typography.\n\nAPI and source code:\n\n*   `Menu`\n    *   [Class definition](https://developer.android.com/reference/android/view/Menu)\n*   `MenuInflater`\n    *   [Class definition](https://developer.android.com/reference/android/view/MenuInflater)\n*   `ContextMenu`\n    *   [Class definition](https://developer.android.com/reference/android/view/ContextMenu)\n*   `PopupMenu`\n    *   [Class definition](https://developer.android.com/reference/android/widget/PopupMenu)\n*   `ListPopupWindow`\n    *   [Class definition](https://developer.android.com/reference/android/widget/ListPopupWindow)\n\nThe following example shows a menu with Material Theming.\n\n<mio-image index=11></mio-image>\n\n### Implementing menu theming\n\nUse default style theme attributes, which affect all menus but do not affect\nother components:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n    ...\n    <item name=\"textAppearanceLargePopupMenu\">@style/TextAppearance.App.BodyLarge</item>\n    <item name=\"textAppearanceSmallPopupMenu\">@style/TextAppearance.App.BodyLarge</item>\n    <item name=\"popupMenuBackground\">@drawable/custom_popup_background</item>\n</style>\n\n<style name=\"TextAppearance.App.BodyLarge\" parent=\"TextAppearance.Material3.BodyLarge\">\n    <item name=\"fontFamily\">@font/rubik</item>\n    <item name=\"android:fontFamily\">@font/rubik</item>\n    <item name=\"android:textColor\">@color/shrine_pink_900</item>\n</style>\n```\n\nIn `res/drawable/custom_popup_background`:\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<shape xmlns:android=\"http://schemas.android.com/apk/res/android\">\n  <solid android:color=\"?attr/colorSurface\"/>\n  <corners\n    android:radius=\"16dp\"/>\n  <padding\n      android:bottom=\"8dp\"\n      android:top=\"8dp\"/>\n</shape>\n```\n\nUse a custom style instead of overriding `?attr/popupMenuBackground` if you want\nto set a custom background for one type of menu:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n    ...\n    <item name=\"popupMenuStyle\">@style/Widget.App.PopupMenu</item>\n</style>\n\n<style name=\"Widget.App.PopupMenu\" parent=\"Widget.Material3.PopupMenu\">\n    <item name=\"android:popupBackground\">@drawable/custom_popupmenu_background</item>\n</style>\n```\n\n### Exposed dropdown menu theming example\n\nExposed dropdown menus support\n[Material Theming](https://material.io/components/chips/#theming) which can\ncustomize color, typography, and shape.\n\n**Note:** The exposed dropdown menu is implemented through the\n`TextInputLayout`. For detailed information on how\n[Material text fields](https://material.io/design/components/text-fields.html)\nwork, see the [TextInputLayout documentation](components/text-fields).\n\nAPI and source code:\n\n*   `TextInputLayout`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/textfield/TextInputLayout)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/TextInputLayout.java)\n*   `AutoCompleteTextView`\n    *   [Class definition](https://developer.android.com/reference/android/widget/AutoCompleteTextView)\n*   `MaterialAutoCompleteTextView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/textfield/MaterialAutoCompleteTextView)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/textfield/MaterialAutoCompleteTextView.java)\n\nThe following example shows filled and outlined exposed dropdown menu types with\nMaterial Theming.\n\n<mio-image index=12></mio-image>\n\n### Implementing exposed dropdown menu theming\n\nUse default style theme attributes, styles and theme overlays which adds themes\nto all menus but does not affect other components:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n    ...\n    <item name=\"textInputStyle\">@style/Widget.App.ExposedDropdownMenu</item>\n</style>\n\n<style name=\"Widget.App.ExposedDropdownMenu\" parent=\"Widget.Material3.TextInputLayout.*.ExposedDropdownMenu\">\n    <item name=\"materialThemeOverlay\">@style/ThemeOverlay.App.ExposedDropdownMenu</item>\n    <item name=\"shapeAppearance\">@style/ShapeAppearance.App.SmallComponent</item>\n    <item name=\"hintTextColor\">?attr/colorOnSurface</item>\n    <item name=\"endIconTint\">?attr/colorOnSurface</item>\n</style>\n\n<style name=\"ThemeOverlay.App.ExposedDropdownMenu\" parent=\"\">\n    <item name=\"colorPrimary\">@color/shrine_pink_100</item>\n    <item name=\"colorOnSurface\">@color/shrine_pink_900</item>\n    <item name=\"colorError\">@color/shrine_red</item>\n    <item name=\"textAppearanceBodyLarge\">@style/TextAppearance.App.BodyLarge</item>\n    <item name=\"textAppearanceBodySmall\">@style/TextAppearance.App.BodySmall</item>\n    <item name=\"autoCompleteTextViewStyle\">@style/Widget.Material3.AutoCompleteTextView.*</item>\n</style>\n\n<style name=\"TextAppearance.App.BodyLarge\" parent=\"TextAppearance.Material3.BodyLarge\">\n    <item name=\"fontFamily\">@font/rubik</item>\n    <item name=\"android:fontFamily\">@font/rubik</item>\n</style>\n\n<style name=\"TextAppearance.App.BodySmall\" parent=\"TextAppearance.Material3.BodySmall\">\n    <item name=\"fontFamily\">@font/rubik</item>\n    <item name=\"android:fontFamily\">@font/rubik</item>\n</style>\n\n<style name=\"ShapeAppearance.App.SmallComponent\" parent=\"ShapeAppearance.Material3.SmallComponent\">\n    <item name=\"cornerFamily\">cut</item>\n    <item name=\"cornerSize\">4dp</item>\n</style>\n```\n\nor use the style in the layout, which affects only this menu:\n\n```xml\n<com.google.android.material.textfield.TextInputLayout\n    ...\n    style=\"@style/Widget.App.ExposedDropdownMenu\">\n\n    ...\n\n</com.google.android.material.textfield.TextInputLayout>\n```\n\n**Note:** When setting a `materialThemeOverlay` on a custom `TextInputLayout`\nstyle, set `autoCompleteTextViewStyle` to either a\n`@style/Widget.Material3.AutoCompleteTextView.*` style or to a custom one that\ninherits from that. <br/> The `TextInputLayout.*.ExposedDropdownMenu` styles set\n`materialThemeOverlay` to override `autoCompleteTextViewStyle` with the\nspecific `AutoCompleteTextView` style needed. Therefore, you don't need to\nspecify a style tag on the `AutoCompleteTextView`.\n", "markdown_path": "docs/components/Menu.md", "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": null, "share_title": null}, "title": "Menus", "up_next_section": {"items": []}, "document_id": "6426597019877376"}, "mdc_flutter": {"banners": [{"description": "<p>The Flutter team is currently working on Material Design 3 support for <code>Menus</code>. Follow the&nbsp;<a href=\"https://github.com/flutter/flutter/issues/91605\" target=\"_blank\" rel=\"noopener\">GitHub issue</a>&nbsp;and&nbsp;<a href=\"https://twitter.com/FlutterDev\" target=\"_blank\" rel=\"noopener\">@FlutterDev</a>&nbsp;for additional updates.</p>", "links": [], "title": "Flutter support in progress"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [], "is_beta": false, "markdown_content": null, "markdown_path": null, "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": {}, "share_title": null}, "title": "Menus", "up_next_section": {"items": []}, "document_id": "5917820973744128"}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, Material Design Components, Material Components, components, menus", "meta_robots": null, "schema_structure": "{}", "share_description": "Menus display a list of choices on a temporary surface. Menus can open from a variety of components, including icon buttons and text fields.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/60ce195c3b8f455a9358de1f2bcd5d20b0d6a25c4b7dd9bdf9f6e14f25371b17df476d16f69b06ad49eb811ddd60bcdc2e2e6a6bfe38ac0d3e71b1fbcda2827c", "height": 560, "url": "https://lh3.googleusercontent.com/eL0VqKowoWoyad9XeiEkCH_Z07uvihWBuQdxkFAW_Nqgs56RqYsknQb3955D1ivkyjqQpqC_UrfjcSGYlEicvokGdB3KnRWVrEUwcAsl0BY2lDp5WSw", "width": 1120}, "share_title": "Menus \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/9e837f2b18990c31a67ae6601fdafa96d9c698c99bd839b018e391b97f1aac8b5e94adbe0fbaff0336220adfd78b9bc3a7d05facf04dda39bbe924747fb35186", "height": 1120, "url": "https://lh3.googleusercontent.com/CYP6RLqXcSIuJS111dPc0EJPsy3iY-MSYZ8Kk9eG8y3vzJZWCDs0xfu7O6Leszbw5tPrbvCRWHe7OE5632ppd8uQnMF12edSpUCzROZVDAzw0S0RqyW8", "width": 1120}, "foreground_image_1x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/f7ef50a35a7cde64d9c7ccfc028e5aacd9fb9cf63a474664fb6d4b0cffb1ea0774d56cad0534dd5d0dbb3896810a24baf8904fdb24aed208a6a6aeafa01cecde", "height": 1120, "url": "https://lh3.googleusercontent.com/9JnzLpy2w6WoDCuHM4uPpzffx3dxq6Tz6HKyjkLEsLRaEJj8ZSWma60kvU1ZcKHN_Zh6mT4m8-FQUDk3fldn0eaMMTN8YaBKGo-1zZe8gYw5GlbvhA", "width": 1120}, "foreground_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/7f73be7db72d7d61cb91e96efe61e10b9254c1b6ca6e09ea301cec3969df9e377f2e37737a7cf7a0c93f29467bdf38e238ae40ab8347a50ba13b8fdd40409385", "height": 1000, "url": "https://lh3.googleusercontent.com/yjVCw3R4saCCeYJpHW2cVTezuWpWYxoRHOANeU-lLZ7QLRwcmEKOOT-VfxUkZIZwbUTNoZgWGniHeYMq82kVHozIYtoZZ3JezA9ndTpn8F2n1tWgITnw", "width": 2000}, "foreground_image_2x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/7b9ea6ce583a2efb413380ab2c863d6680dbd15f9dffed3774685400aef11d33232cb6b20a96994067af6b09299235956dae2a29a8e44964d1a02c7d97f6a54d", "height": 1000, "url": "https://lh3.googleusercontent.com/ZVIJA7rtogj73vQTRwOTPD7KLNmn3vC5meGV-Efo1L3rN5fiILoMBDm597hVZ-zWQe3x7eEg2Mnvs_CLFceN2wPBAiyGAqj2Lx_x-EzKMf-VLHlXfg", "width": 2000}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {}, "split_background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/6e64a89bff674daaf8a04faa76e26a797cf0b6b96a4f878a5085a87fe54eced568cfcfa27e63ecf65506b676cf19d7d33a68cf69152740e188e79206ad327a60", "height": 4096, "url": "https://lh3.googleusercontent.com/ripoWfm4wgmhZmNUtG8bvJVRC0lchQexv8QX1EpvDurNDu7j2ZOCk4Tx6ZKRuMVA5wzuBlu6MYw3Mgdv_4gXlUUgHeFyWvfjkQzxBeFPSmgYDEgUddUd", "width": 4096}, "split_background_image_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/71c95a036b2abfe4360d67fae514fb29f32806f4299589cec0fb29a4efb7edc1b9e04a5e149dc4e7ee2e03101f9238ff20a264d2a2547c869adfdf5b9c3e589a", "height": 4096, "url": "https://lh3.googleusercontent.com/JWsutJ9nyTn8uCFqN2o8CNBi58WDqGUljTFpb1mWap6hIbiF6bCKF_zvnACwiCmVjwDvVyWsJiUv2qFzDxYX5LBlvbgIVajDDvDZMklC0CP0whgilQ", "width": 4096}, "vertical_foreground_alignment_override": "position_bottom"}, "title": "Menus", "document_id": "4984542628413440", "modified_date": "2025-11-14"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/motion-easing-duration.json b/evidence/surface/fetch/motion-easing-duration.json
new file mode 100644
index 0000000..c3274e4
--- /dev/null
+++ b/evidence/surface/fetch/motion-easing-duration.json
@@ -0,0 +1 @@
+{"category": null, "component_image_1x1": {}, "component_image_2x1": {}, "component_image_3x1": {}, "component_image_3x2": {}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {}, "dark_component_image_3x1": {}, "dark_component_image_3x2": {}, "description": null, "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/9164cda0aeba593dc6a9df6900028e0093d41c3222e8fe4af6226f74d0f899e42ad7aac67613bc77e859d8df12554c46bbc662893b34bba18256479896d1086c", "height": 800, "url": "https://lh3.googleusercontent.com/VXAl4bA55djZtzg5DwZsWUKgkK0xox-uZFh-0vv02Pb17idnl4ihgPC1B1jBtdaz7nnZooDayVLba3aEmcMpCrvsso49pnoIP1m7wWWSFecVZk6_dO4h", "width": 2400}, "foreground_image": {}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Styles / Motion / Easing and duration", "isDisplayed": true, "jetpack": {}, "mdc_android": {}, "mdc_flutter": {}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, color, theme, theming, brand, branding, customization", "meta_robots": " ", "schema_structure": "{}", "share_description": "Material easing and durations create responsive and expressive motion.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/0dc12de919d480d12a14280a8db24ed16af0395e2bd6850b9d46df80d1dc30c761e2bc30971220acc054bbc8802319ed8ccb5c931984118987131a2db75eeb9e", "height": 563, "url": "https://lh3.googleusercontent.com/Q1E_p456YpzWCM4GEUcaJvRJkFgOsTG8DUMOT3SMRF33OreG0XjEcipcaptxNVvvYmS5p3m3dS-fz4fMiSJL8TvkLo8976iqnEwRuP1rfKxXhylB8GE", "width": 960}, "share_title": "Easing and duration \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {}, "foreground_image_1x1_dark_mode": {}, "foreground_image_2x1": {}, "foreground_image_2x1_dark_mode": {}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {"file_name": "Google_Mio_Motion_1080x1080.mp4", "file_path": "c799da99b55e6901b022e163c02bd319963c79613cee10a8113f434a941a46591750503770b0f7f072306bb4c678a34b5111c393fca16a07ea3e0eb17aae4f19", "url": "https://kstatic.googleusercontent.com/files/c799da99b55e6901b022e163c02bd319963c79613cee10a8113f434a941a46591750503770b0f7f072306bb4c678a34b5111c393fca16a07ea3e0eb17aae4f19"}, "split_background_image": {}, "split_background_image_dark_mode": {}, "vertical_foreground_alignment_override": null}, "title": "Easing and duration", "document_id": "5485575272529920", "modified_date": "2024-05-10"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/motion-transitions.json b/evidence/surface/fetch/motion-transitions.json
new file mode 100644
index 0000000..aa49f6f
--- /dev/null
+++ b/evidence/surface/fetch/motion-transitions.json
@@ -0,0 +1 @@
+{"category": null, "component_image_1x1": {}, "component_image_2x1": {}, "component_image_3x1": {}, "component_image_3x2": {}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {}, "dark_component_image_3x1": {}, "dark_component_image_3x2": {}, "description": null, "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/aa41a08ab039aef827ba8828d28fc7fdff590cea964ff34ab9ad4f19dc0eddbac430f1fce5c43e6bd46fa97461233a0600494f00c92dc51ecf94445cb40e7ebb", "height": 800, "url": "https://lh3.googleusercontent.com/8KWbIfyHlt2x5R1dypLOpOgRE-Y7fJSIZDqbupZlOvC2B9E1PCwlBfhGxRQUx5XPIJGdQ9_bKrnFc2KllyNLS-ylzw13tTpCFnHmhjBlvcy37xw22BhP", "width": 2400}, "foreground_image": {}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Styles / Motion / Transitions", "isDisplayed": true, "jetpack": {}, "mdc_android": {}, "mdc_flutter": {}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, color, theme, theming, brand, branding, customization", "meta_robots": " ", "schema_structure": "{}", "share_description": "Transitions help guide users as they navigate an app.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_be877ab23edb4a39be610a57a771c69d_/4e21623424258768dab8bd3ca896bd4558c3f390213df903c70ed58d8406f4ca95bb988e7a7aa7c24427c8eeb6657e4075a3f01e7635f7c73f530a0259fc6658", "height": 563, "url": "https://lh3.googleusercontent.com/XWHrJTm9zhER8cf-lTyi0lxi2lr7-KwkSbJF3HbplKmcsh-VKPtY3zD_byQfdnmHy60RHq2N9NYhbii3onVGIGlZr6K29epf_1TenaLcwNJT058pOoU", "width": 960}, "share_title": "Transitions \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {}, "foreground_image_1x1_dark_mode": {}, "foreground_image_2x1": {}, "foreground_image_2x1_dark_mode": {}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {"file_name": "Google_Mio_Motion_1080x1080.mp4", "file_path": "54c7a96b382f9f326ec4443721938ca407373355d6f563365b8738ec1d768fa8e19c6df5d19b55c5a97e4bd47f3d1a897dadf1976353c8c35afb4eabe9e30524", "url": "https://kstatic.googleusercontent.com/files/54c7a96b382f9f326ec4443721938ca407373355d6f563365b8738ec1d768fa8e19c6df5d19b55c5a97e4bd47f3d1a897dadf1976353c8c35afb4eabe9e30524"}, "split_background_image": {}, "split_background_image_dark_mode": {}, "vertical_foreground_alignment_override": null}, "title": "Transitions", "document_id": "4701069397590016", "modified_date": "2024-05-10"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/navigation-drawer.json b/evidence/surface/fetch/navigation-drawer.json
new file mode 100644
index 0000000..2141aec
--- /dev/null
+++ b/evidence/surface/fetch/navigation-drawer.json
@@ -0,0 +1 @@
+{"category": "navigation", "component_image_1x1": {}, "component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/a35f36af3d228a07f91a488498f704590f74c5fd7e3959c040383054c9b9112e69cf9b4e0f03858c4ff95de1baa5778517041d5794255155c346b5b8f401cdc3", "height": 560, "url": "https://lh3.googleusercontent.com/f3eG3VTNrN0sqo500bZc81dUJ7abW11Fu8g0EroVIjqzMIITn2cmcm0vDZMsJ6UTGHLQqpSiJ8pr8ADFJzsk2ZX0NUsKJBn9lZLKNBM6vrJTcivcGXU", "width": 1120}, "component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/11ceacbb816971a3e1832bcdd6755cb4c11f952ad74f9fbb7e8efa93ab23bc27f47841e429495e3771417145b199ae44bbfe798a07f6e2dee0eb4ea6b0dd43c6", "height": 560, "url": "https://lh3.googleusercontent.com/8UBdHa5T1nwvb2d2CcEgfSVsPiew8wIgxEtm2W-tlKWMFWOh092FAH4R1x-VPPdw296SovxpctnxjT-zU7aad2Jbx3y0WD-t8tBQaAoe0JnjaP4gKC8", "width": 1680}, "component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/2f6f7a39d7557b0e261746671b26bc8304d86d5692de3891486b1f017f52f04b7f3acc59405362ece3ac0d07d4eacce818f1a51b3775d878fcbc7bb759461788", "height": 560, "url": "https://lh3.googleusercontent.com/f7IGmv0UcH4pHUi7rTpyhDXM0R0ZDVXBnjVJRV-Z_HVxBAwTXIza_r15fn1g4gMWw--UXrtP59_494J9abvklR_Y9__PWQGG6Bn8i6kkeM6_aaKACQ", "width": 840}, "component_image_position": "bottom center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/155eb9cef10ae8b7ff188a389fa73fa1f89ee4835f53fb292f2fa405b84f3a64bfd055fab8c864a834ba72c4bbe97a2a6b89e32b8533f66f0ec20e02a1c5b81d", "height": 560, "url": "https://lh3.googleusercontent.com/FtGSv_EaEhFJR8iTVfkCXSNBOCZ_QWayzMB2aFLGVgAldbA7iUCxL0wAFB_rR3pIc_VqYl5a3g8Iv4QzRPIIh8fEYf-BvVcQR3OgPRbVI_L70WSZLSc", "width": 1120}, "dark_component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/670c23bd23876162ec1926d761d81f29776cc87442daa5562ce411caf3ea28c12596aa6810727d99dcd935ff255164e756b043e8239abc1dbc2ff6e73915b5d3", "height": 560, "url": "https://lh3.googleusercontent.com/vEfmExpvZdGU4B_mAFPR7hm3OvGT8kZZc5S-DIsW7CdnNbTZCC_KzcGq127MlScirmjLnjMNUJAJ3yQnQ1JtJgk__MiNRVPcvD7slc9pB4UNUV2TPE-9", "width": 1680}, "dark_component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/a01ccbd15d01cd8352908e6ae919083638e35fa0de4aa9d3e9236d8d042e835a9331b3de6b1b4535b5431b8e81db8ec650366b60f55f9159f9d9e1ab8085a9cd", "height": 560, "url": "https://lh3.googleusercontent.com/oFGdutiZU_UQpIkgLFsVNth42pZTqi-4tc8OpREEJcInQ9XJV3Ogm3_T10VEH9JC2z3IEuuneZ7NwTYs_0dY-a5pi_0aJtOiQKuRMdxPzVWIgu8xUjo", "width": 840}, "description": null, "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/07961623449d535bc37272543d77bb7693e9873bd46c774ef6e7f1032258dab13ebe07602f170a79383170dd69544796009efdc021b779a20b5b076d3369f09c", "height": 4096, "url": "https://lh3.googleusercontent.com/kOjv2BXRvgEGd6h_DLoWSxTgeVFXCk5xXXUsfv_EKY54Hsqn9O_nZy15e6cfg4ezSNciOyAjuA0emr40fD0Lf1h4o8iOS42XicJ3VVVdEbfQJYg3oVJv", "width": 4096}, "foreground_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/6248141da4560041c9bf6b06b3a41fc06002f772a5454c2ff95ccfbc1b83d56b8345e47f94706c8c8f5b0743dc9cb91fe9e4fdc5f94ddf08e69893dba338b8c4", "height": 738, "url": "https://lh3.googleusercontent.com/i06UvMzkpcJIaWeg-KuH59G4zvwOfAWgPpGKSWNKwg5j0GNNcj9xKDjq1LNzMZWntQs5VrBF0MlbhOPMdEser0EWJ72Est1RsViD_m9TD5BmyPiiTA", "width": 904}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Components / Navigation drawer", "isDisplayed": true, "jetpack": {}, "mdc_android": {"banners": [{"description": "<p>Navigation drawers are available in the Material Design 3 library for Jetpack Compose. For implementation details, visit the <code>androidx.compose.material3</code> <a href=\"https://developer.android.com/jetpack/androidx/releases/compose-material3\" target=\"_blank\" rel=\"noopener\">library documentation on Android Developers</a>:</p>", "links": [{"aria_label": "Read about implementing Material Design 3 NavigationDrawers using Jetpack Compose", "href": "https://developer.android.com/reference/kotlin/androidx/compose/material3/package-summary#navigationdrawer", "label": "NavigationDrawer API reference", "open_new_window": true}], "title": "Jetpack Compose support available"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [{"a11y_description": "A standard (left) and modal (right) Navigation drawer", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/70d3fc24714f87111445c0f7e07069128608176c284cc7c8f848dd8ef9396840b0a6835287a48367111eb75656daf48eb2eeb870b5109c510ec92e5f2bea9ee5", "height": 1144, "url": "https://lh3.googleusercontent.com/e5dT3lxSiIZvTZ4ETiUMbqSeF3LqX2aGk8rHdC8ve-4FaGhyu2hKw96oUD1wqhA1IfdQItwIOkGQjlnaU-oVJQ_c15i2S2ODJBvcodNYi0MSHICMaAo", "width": 2048}}, {"a11y_description": "Nav drawer with 3 menu items", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/b5dbb3154b4a07130ba08989ae671d73011fd95caad59efe955802414548f5d9a2c26088c546ca93096b34c7456b107a32a2e39ce8197c672f78b63228747f51", "height": 636, "url": "https://lh3.googleusercontent.com/u4-1-VP8j6cHmtGj5bk0bb1SvBTeqo4gz5cnaYbg3PYQHKP9pkh-AcsVtOLdqAypFJNx-_RjFN4INjoM0htEzTulgQPsWDcipmPzfGQyMs8SO6yPf4QU", "width": 1352}}, {"a11y_description": "Nav drawer with \"Header title\", \"Header text\", a \"Mail\" subheader, and 3\nitems. Item 1 is\nselected.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/cd08314fcde21c5f1a925bfa353cd538942800bdfe4ac9658237b76d8e19d9acc2c4296d5ce695f9ed4169454cf6549529e97f5ac9c348afb4ed8c8e31e610e5", "height": 957, "url": "https://lh3.googleusercontent.com/YrA-6RMyaP7u2nbgQ8C4slNMPrmJqKtnZyPkMrJ6QRSBH1afCRtqtcuJj7LtXwSP0W13FhpPLe8JZxVOeZXMmVzZXZPeter_n-UOkrQAFnUP7TgBP4c", "width": 1079}}, {"a11y_description": "Nav drawer with \"Header title\", \"Header text\", \"Mail\" subheader, and 6 items\nwith a divider between items 3 and\n4", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/b3c2304624f58d918d14b7da31b1400e91c6d8185f8d417b71caaf9e7488536f59241daf811ed145e7693295e0688838b9a041182be3d9f204042d5dce6d4821", "height": 2280, "url": "https://lh3.googleusercontent.com/RE77cJKyDGVabZnOTUarBRwGDDQX4pdlUpATettNU5aV6IxzKE9w4eieoRAzwb3l-zusYuCxP1gzi3vx4UdRZrw8jAyGosCU20gnAApXofqCtEQ7vS_O", "width": 1080}}, {"a11y_description": "Navigation drawer anatomy", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/5a956a74b4d8587a10a1aed648f9b644ec67a3322a03f916d3d4ee40b26cc38a940d502e293661111d1592a0d29cbb31c525a84c1babfc488a6b19d6fc7ff619", "height": 1144, "url": "https://lh3.googleusercontent.com/lJYjWTyz7sQLRjCGskEv_MQa-dx2UOjTjmjmyg_sfst4kv7NB20lUwPwaAzGaMGsSzXAixdzAE-j2txRKQBztYzOAC7eDNEnR9UDNrn6YjP0JKuDK46T", "width": 1352}}, {"a11y_description": "Nav drawer with \"Header title\", \"Header text\", \u00e2\u0080\u009cSubtitle\u00e2\u0080\u009d, and 3 items with\nicons on left of\nscreen.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/1d00f2a5f01333102187d04feac6b559f2e24f2dede2409703a9098f028492c6a42c7f356174f070ef590bd5c3163c959d1d6c4812019e8a1e7a060ed98d65fc", "height": 1080, "url": "https://lh3.googleusercontent.com/2DL_ng6-Sz4eyV452O1gveZODQTCtU-_li38zswgNiaPJ52kQ-pS8FMYOPBrKr92RmOZeTGOh9OjAWgn_MTkoKnjmu41MRJKk_z2fz8HL2RSakK6B11X", "width": 2108}}, {"a11y_description": "A screen with a modal navigation drawer open. The drawer container \"Header\ntitle\", \"Header text\", and 6\nitems.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/ab7c9822ddbdfaba687d64af634e4c276e493eb3b4f262c43f0351e9645f56a9c5780a2ec7f619bc1f126dbf136e3fe6c0c756c3a4a74bdbd3895593be93a429", "height": 2280, "url": "https://lh3.googleusercontent.com/faR-DfcPIwkvfDZgdbNnZg8-yEsxYhxSZreXWgPTczVEggfwz1fRG8pbhCVHu0SQERRXZuTcj_bShuOMNQ1KXcxWhe_4h_h09ojlSiKI_Wj_ta4dpg", "width": 1080}}, {"a11y_description": "2 views: screen with bottom app bar; nav drawer covering bottom with scrim\nover remaining screen.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/f7c56895bbe65a15996975eb552b0fd6933a19ba724f2693c547402057de3d0e21aec54df82cef9c91b8d7b377572271fc46ff0368aca5e7b774f055adc04a36", "height": 712, "url": "https://lh3.googleusercontent.com/SDxrYPq5bmeTfeZ0IQ1YT3fZpOUXe4jDsTUAtIQFSYsrP2Bc0ccXelNVnomv8jNpliafJ0DAh5cL61OARrG6JWwRqoNCoB_bl5kcN0MiEPR4UHfV1yaE", "width": 1056}}, {"a11y_description": "Nav drawer with \u00e2\u0080\u009cHeader\u00e2\u0080\u009d, \u00e2\u0080\u009cHeader text\u00e2\u0080\u009d, \u00e2\u0080\u009cMail\u00e2\u0080\u009d subtitle and 6 items: brown\ntext and icons, pink\ncontainers.", "bordered": true, "caption": null, "case": null, "file": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_293ae6e29e4b420a9648cf846508437a_/ec614729ac1c80a71ee7cf1b6ecb738d56a7690d0657901592159381d4ae2af6e900c322f93d52bf9d7484510e8775dfc03abecbd490ff3dbfa67aa1078ee2f0", "height": 2280, "url": "https://lh3.googleusercontent.com/WYFathT7_IYA6ssRQjhd7E7cwOCvnxZRiA_yN6-xJusEWMnavSZk7dj7CLIWb0z4sOhBurnhX8yybQFtW-mjgNiYH6FGpN_K3lqQ3eafC50_t4cDxDg", "width": 1080}}], "is_beta": false, "markdown_content": "<!--docs:\ntitle: \"Navigation drawers\"\nlayout: detail\nsection: components\nexcerpt: \"Navigation drawers provide access to destinations in your app.\"\niconId: navigation-drawer\npath: /catalog/navigation-drawer/\n-->\n\n# Navigation drawer\n\n[Navigation drawers](https://material.io/components/navigation-drawer) provide\naccess to destinations in your app.\n\n<mio-image index=0></mio-image>\n\n**Contents**\n\n*   [Using navigation drawers](#using-navigation-drawers)\n*   [Anatomy](#anatomy)\n*   [Standard navigation drawer](#standard-navigation-drawer)\n*   [Modal navigation drawer](#modal-navigation-drawer)\n*   [Bottom navigation drawer](#bottom-navigation-drawer)\n*   [Theming](#theming)\n\n## Using navigation drawers\n\nBefore you can use navigation drawers, you need to add a dependency to the\nMaterial Components for Android library. For more information, go to the\n[getting started](/libraries/mdc-android/getting-started)\npage. For modal navigation drawers you also need to add a dependency to the\nAndroidX `DrawerLayout` library. For more information go to the\n[releases](https://developer.android.com/jetpack/androidx/releases/drawerlayout)\npage.\n\nThe content of all navigation drawer types can be implemented using a\n`NavigationView`.\n\n```xml\n<com.google.android.material.navigation.NavigationView\n  android:id=\"@+id/navigationView\"\n  ... />\n```\n\n**Note:** The `layout_width` and `layout_height` attributes should be set to\n`wrap_content`, `match_parent`, or a custom dimension depending on the\nnavigation drawer type and parent `ViewGroup`.\n\n### Adding a menu\n\n<mio-image index=1></mio-image>\n\nIn the layout:\n\n```xml\n<com.google.android.material.navigation.NavigationView\n    ...\n    app:menu=\"@menu/navigation_drawer\" />\n```\n\nIn `res/menu/navigation_drawer.xml`:\n\n```xml\n<menu ...>\n\n  <item\n    android:id=\"@+id/main_item\"\n    android:title=\"@string/mail_subheader_title\">\n      <menu>\n        <item\n          android:id=\"@+id/inbox_item\"\n          android:icon=\"@drawable/ic_inbox_24px\"\n          android:title=\"@string/inbox_title\"\n          android:checkable=\"true\"/>\n        <item\n          android:id=\"@+id/outbox_item\"\n          android:icon=\"@drawable/ic_outbox_24px\"\n          android:title=\"@string/outbox_title\"\n          android:checkable=\"true\"/>\n        <item\n          android:id=\"@+id/favourites_item\"\n          android:icon=\"@drawable/ic_favourites_24px\"\n          android:title=\"@string/favourites_title\"\n          android:checkable=\"true\">\n      </menu>\n  </item>\n\n</menu>\n```\n\n### Adding a header\n\n<mio-image index=2></mio-image>\n\nIn the layout:\n\n```xml\n<com.google.android.material.navigation.NavigationView\n    ...\n    app:headerLayout=\"@layout/header_navigation_drawer\" />\n```\n\nIn `res/layout/header_navigation_drawer.xml`:\n\n```xml\n<LinearLayout\n    ...\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"wrap_content\"\n    android:orientation=\"vertical\">\n\n    <TextView\n        android:layout_width=\"wrap_content\"\n        android:layout_height=\"wrap_content\"\n        android:layout_marginTop=\"24dp\"\n        android:layout_marginStart=\"24dp\"\n        android:layout_marginEnd=\"24dp\"\n        android:textAppearance=\"?attr/textAppearanceHeadlineSmall\"\n        android:textColor=\"?attr/colorOnSurface\"\n        android:text=\"@string/header_title\" />\n\n    <TextView\n        android:layout_width=\"wrap_content\"\n        android:layout_height=\"wrap_content\"\n        android:layout_marginBottom=\"24dp\"\n        android:layout_marginStart=\"24dp\"\n        android:layout_marginEnd=\"24dp\"\n        android:textAppearance=\"?attr/textAppearanceTitleSmall\"\n        android:textColor=\"?attr/colorOnSurfaceVariant\"\n        android:text=\"@string/header_text\" />\n\n</LinearLayout>\n```\n\n### Adding dividers and subtitles\n\n<mio-image index=3></mio-image>\n\nDividers are automatically added between `<item>` groups with unique IDs or\n`<group>`s with unique IDs. When a sub-`<menu>` is added to an item it is\ntreated as a subtitle.\n\nIn `res/menu/navigation_drawer.xml`:\n\n```xml\n<menu ...>\n  <item\n    android:id=\"@+id/main_item\"\n    android:title=\"@string/mail_subheader_title\">\n      <menu>\n        <item\n          android:id=\"@+id/search_item\"\n          android:icon=\"@drawable/ic_search_24px\"\n          android:title=\"@string/search_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n        <item\n          android:id=\"@+id/rotation_item\"\n          android:icon=\"@drawable/ic_3d_rotation_24px\"\n          android:title=\"@string/3d_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n        <item\n          android:id=\"@+id/accelerator_item\"\n          android:icon=\"@drawable/ic_accelerator_24px\"\n          android:title=\"@string/accelerator_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n        <item\n          android:id=\"@+id/dashboard_item\"\n          android:icon=\"@drawable/ic_dashboard_24px\"\n          android:title=\"@string/dashboard_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n      </menu>\n  </item>\n  <item\n    android:id=\"@+id/labels_item\"\n    android:title=\"@string/labels_subheader_title\">\n      <menu>\n        <item\n          android:id=\"@+id/label_one\"\n          android:icon=\"@drawable/ic_label_24px\"\n          android:title=\"@string/label_one_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n        <item\n          android:id=\"@+id/label_two\"\n          android:icon=\"@drawable/ic_label_24px\"\n          android:title=\"@string/label_two_title\"\n          android:checkable=\"true\"\n          app:showAsAction=\"ifRoom\"/>\n      </menu>\n  </item>\n\n</menu>\n```\n\n### Making navigation drawers accessible\n\nNavigation drawers support content labeling for accessibility and are readable\nby most screen readers, such as TalkBack. Text rendered in menu items is\nautomatically provided to accessibility services. Additional content labels are\noptional but recommended.\n\nFor more information on content labels, go to the\n[Android accessibility help guide](https://support.google.com/accessibility/android/answer/7158690).\n\n#### Content descriptions\n\nA content description can be set on `<item>`s in the `NavigationView` menu so\nthat screen readers like TalkBack are able to announce their purpose or action.\nThis can be done in XML using the `android:contentDescription` attribute or\nprogrammatically with\n`navigationView.menu.findItem(R.id.itemId)#setContentDescription` (on API 26 and\nabove).\n\nAny `ImageView`s within the header layout should also have a content description\nset.\n\n#### Opening and closing navigation drawers\n\nTo open navigation drawers, use clickable widgets that meet the minimum touch\ntarget size of `48dp` and are properly labeled for accessibility. To close\nnavigation drawers, consider doing the same but bear in mind that clicking on\nmenu items or an optional scrim should also serve this purpose.\n\n### Using navigation drawers with the Navigation component\n\nNavigation drawers can be used with the AndroidX Navigation library. For more\ninformation, go to the\n[documentation](https://developer.android.com/guide/navigation/navigation-ui#add_a_navigation_drawer).\n\n## Anatomy\n\nNavigation drawers have a container, an optional header, optional dividers,\nitems with inactive text, active text, and an active text overlay, optional\nsubtitles, and an optional scrim.\n\n<mio-image index=4></mio-image>\n\n1.  Container\n2.  Subheader (optional)\n3.  Label text\n4.  Icon (optional)\n5.  Active indicator/Item shape\n6.  Badge text (coming soon)\n7.  Divider\n8.  Scrim (modal drawer only)\n\n### Container attributes\n\nElement                 | Attribute(s)                                                        | Related method(s)                                | Default value\n----------------------- | ------------------------------------------------------------------- | ------------------------------------------------ | -------------\n**Color**               | `android:background`                                                | `setBackground`<br>`getBackground`               | `?attr/colorSurface`\n**Shape**               | `app:shapeAppearance`<br>`app:shapeAppearanceOverlay`               | N/A                                              | `null`\n**Elevation**           | `app:elevation` (can be used on `NavigationView` or `DrawerLayout`) | `setElevation`<br>`getElevation`                 | `0dp` (`NavigationView`) or `1dp` (`DrawerLayout`)\n**Max width**           | `android:maxWidth`                                                  | N/A                                              | `280dp`\n**Fits system windows** | `android:fitsSystemWindows`                                         | `setFitsSystemWindows`<br>`getFitsSystemWindows` | `true`\n\n### Header attributes\n\nElement    | Attribute          | Related method(s)                                                                                   | Default value\n---------- | ------------------ | --------------------------------------------------------------------------------------------------- | -------------\n**Layout** | `app:headerLayout` | `addHeaderView`<br>`inflateHeaderView`<br>`getHeaderView`<br>`getHeaderCount`<br>`removeHeaderView` | `null`\n\n### Divider attributes\n\nElement     | Attribute                                                                                                                                                                                                                    | Related method(s)                                                                                   | Default value\n----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------\n**Divider** | `android:listDivider` in app theme                                                                                                                                                                                           | N/A                                                                                                 | Varies per platform version\n**Height**  | N/A (see [layout](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/internal/res/layout/design_navigation_item_separator.xml)) | N/A                                                                                                 | `1dp`\n**Inset**   | `app:dividerInsetStart`<br/>`app:dividerInsetEnd`                                                                                                                                                                            | `setDividerInsetStart`<br/>`getDividerInsetStart`<br/>`setDividerInsetEnd`<br/>`getDividerInsetEnd` | `28dp`<br/>`28dp`\n\n### Item attributes\n\nElement                | Attribute(s)                                                                                                  | Related method(s)                                                                              | Default value\n---------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------\n**Color**              | `app:itemShapeFillColor`                                                                                      | N/A                                                                                            | `?attr/colorSecondaryContainer`\n**Shape**              | `app:itemShapeAppearance`<br>`app:itemShapeAppearanceOverlay`                                                 | N/A                                                                                            | `@style/ShapeAppearance.Material3.Corner.Full` <br>(`?attr/shapeCornerFamily` and corner size `50%`)\n**Insets**             | `app:itemShapeInsetStart`<br>`app:itemShapeInsetTop`<br>`app:itemShapeInsetEnd`<br>`app:itemShapeInsetBottom` | N/A                                                                                            | `12dp`<br>`0dp`<br>`12dp`<br>`0dp`\n**Horizontal padding** | `app:itemHorizontalPadding`                                                                                   | `setItemHorizontalPadding`<br>`setItemHorizontalPaddingResource`<br>`getItemHorizontalPadding` | `28dp`\n**Vertical padding**   | `app:itemVerticalPadding`                                                                                     | `setItemVerticalPadding`<br>`setItemVerticalPaddingResource`<br>`getItemVerticalPadding`       | `4dp`\n\n### Text attributes\n\nElement        | Attribute                | Related method(s)                        | Default value\n-------------- | ------------------------ | ---------------------------------------- | -------------\n**Color**      | `app:itemTextColor`      | `setItemTextColor`<br>`getItemTextColor` | `?attr/colorOnSecondaryContainer` when active else `?attr/colorOnSurfaceVariant`\n**Typography** | `app:itemTextAppearance` | `setItemTextAppearance`                  | `?attr/textAppearanceLabelLarge`\n**Max lines**  | `app:itemMaxLines`       | `setItemMaxLines`<br>`getItemMaxLines`   | `1`\n\n### Icon attributes\n\nElement     | Attribute             | Related method(s)                                                            | Default value\n----------- | --------------------- | ---------------------------------------------------------------------------- | -------------\n**Color**   | `app:itemIconTint`    | `setIconItemTintList`<br>`getIconItemTintList`                               | `?attr/colorOnSecondaryContainer` when active else `?attr/colorOnSurfaceVariant`\n**Size**    | `app:itemIconSize`    | `setItemIconSize`                                                            | `24dp`\n**Padding** | `app:itemIconPadding` | `setItemIconPadding`<br>`setItemIconPaddingResource`<br>`getItemIconPadding` | `12dp`\n\n### Subtitle attributes\n\nElement        | Attribute                                             | Related method(s)                                                                                           | Default value\n-------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------\n**Color**      | `app:subheaderColor`                                  | N/A                                                                                                         | `?attr/colorOnSurfaceVariant`\n**Typography** | `app:subheaderTextAppearance`                         | N/A                                                                                                         | `?attr/textAppearanceTitleSmall`\n**Max lines**  | N/A                                                   | N/A                                                                                                         | `1`\n**Height**     | N/A                                                   | N/A                                                                                                         | `?attr/listPreferredItemHeightSmall`\n**Padding**    | `app:subheaderInsetStart`<br/>`app:subheaderInsetEnd` | `setSubheaderInsetStart`<br/>`getSubheaderInsetStart`<br/>`setSubheaderInsetEnd`<br/>`getSubheaderInsetEnd` | `28dp` and `28dp`\n\n### Scrim attributes\n\nElement   | Attribute | Related method(s)                 | Default value\n--------- | --------- | --------------------------------- | --------------------\n**Color** | N/A       | `setScrimColor` on `DrawerLayout` | Black at 60% opacity\n\n### `NavigationView` styles\n\nElement           | Style\n----------------- | ---------------------------------\n**Default style** | `Widget.Material3.NavigationView`\n\nDefault style theme attribute: `?attr/navigationViewStyle`\n\n### `DrawerLayout` styles\nElement           | Style\n----------------- | ---------------------------------\n**Default style** | `Widget.Material3.DrawerLayout`\n\nDefault style theme attribute: `?attr/drawerLayoutStyle`\n\n### Types\n\nThere are three types of navigation drawers: 1\\.\n[Standard navigation drawer](#standard-navigation-drawer), 2\\.\n[Modal navigation drawer](#modal-navigation-drawer), 3\\.\n[Bottom navigation drawer](#bottom-navigation-drawer)\n\n## Standard navigation drawer\n\n[Standard navigation drawers](https://material.io/components/navigation-drawer#standard-drawer)\nallow interaction with both screen content and the drawer at the same time. They\ncan be used on tablet and desktop, but they aren\u2019t suitable for mobile devices\ndue to limited screen size.\n\n### Standard navigation drawer example\n\nAPI and source code:\n\n*   `NavigationView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/navigation/NavigationView)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/navigation/NavigationView.java)\n\nThe following example shows a permanently visible standard navigation drawer.\n\n<mio-image index=5></mio-image>\n\nIn the layout:\n\n```xml\n<androidx.constraintlayout.widget.ConstraintLayout\n    ...\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\">\n\n    <com.google.android.material.navigation.NavigationView\n        ...\n        android:layout_width=\"wrap_content\"\n        android:layout_height=\"match_parent\"\n        app:layout_constraintStart_toStartOf=\"parent\" />\n\n    <!-- Screen content (constrained to end of navigationView) -->\n\n</androidx.constraintlayout.widget.ConstraintLayout>\n```\n\nIn `res/values/themes.xml`:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.DayNight.*\">\n    <item name=\"android:windowTranslucentStatus\">true</item>\n</style>\n```\n\nIn `res/layout/header_navigation_drawer.xml`:\n\n```xml\n<LinearLayout\n    ...\n    android:fitsSystemWindows=\"true\">\n\n    ...\n\n</LinearLayout>\n```\n\n## Modal navigation drawer\n\n[Modal navigation drawers](https://material.io/components/navigation-drawer#modal-drawer)\nblock interaction with the rest of an app\u2019s content with a scrim. They are\nelevated above most of the app\u2019s UI and don\u2019t affect the screen\u2019s layout grid.\n\nThey are primarily used for mobile devices where screen space is limited, and\ncan be replaced by standard drawers on tablet and desktop.\n\n### Modal navigation drawer example\n\nAPI and source code:\n\n*   `NavigationView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/navigation/NavigationView)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/navigation/NavigationView.java)\n*   `DrawerLayout`\n    *   [Class definition](https://developer.android.com/reference/kotlin/androidx/drawerlayout/widget/DrawerLayout)\n\nThe following example shows a modal navigation drawer.\n\n<mio-image index=6></mio-image>\n\nIn the layout:\n\n```xml\n<androidx.drawerlayout.widget.DrawerLayout\n    ...\n    android:id=\"@+id/drawerLayout\"\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\"\n    tools:openDrawer=\"start\">\n\n    <androidx.coordinatorlayout.widget.CoordinatorLayout\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"match_parent\"\n        android:fitsSystemWindows=\"true\">\n\n        <!-- Screen content -->\n        <!-- Use app:layout_behavior=\"@string/appbar_scrolling_view_behavior\" to fit below top app bar -->\n\n    </androidx.coordinatorlayout.widget.CoordinatorLayout>\n\n    <com.google.android.material.navigation.NavigationView\n        ...\n        android:layout_width=\"wrap_content\"\n        android:layout_height=\"match_parent\"\n        android:layout_gravity=\"start\" />\n\n</androidx.drawerlayout.widget.DrawerLayout>\n```\n\nIn `res/values/themes.xml`:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.DayNight.*\">\n    <item name=\"android:windowTranslucentStatus\">true</item>\n</style>\n```\n\nIn `res/layout/header_navigation_drawer.xml`:\n\n```xml\n<LinearLayout\n    ...\n    android:fitsSystemWindows=\"true\">\n\n    ...\n\n</LinearLayout>\n```\n\nIn code:\n\n```kt\ntopAppBar.setNavigationOnClickListener {\n    drawerLayout.open()\n}\n\nnavigationView.setNavigationItemSelectedListener { menuItem ->\n    // Handle menu item selected\n    menuItem.isChecked = true\n    drawerLayout.close()\n    true\n}\n```\n\nFor more information on top app bars see the\n[documentation](https://github.com/material-components/material-components-android/tree/master/docs/components/TopAppBar.md).\n\n## Bottom navigation drawer\n\n[Bottom navigation drawers](https://material.io/components/navigation-drawer#bottom-drawer)\nare modal drawers that are anchored to the bottom of the screen instead of the\nleft or right edge. They are only used with bottom app bars.\n\nThese drawers open upon tapping the navigation menu icon in the bottom app bar.\nThey are only for use on mobile devices.\n\n### Bottom navigation drawer example\n\nAPI and source code:\n\n*   `NavigationView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/navigation/NavigationView)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/navigation/NavigationView.java)\n*   `BottomSheetBehavior`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/bottomsheet/BottomSheetBehavior)\n    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/bottomsheet/BottomSheetBehavior.java)\n\nThe following example shows a bottom navigation drawer with a bottom app bar.\n\n<mio-image index=7></mio-image>\n\nIn the layout:\n\n```xml\n<androidx.coordinatorlayout.widget.CoordinatorLayout\n    ...\n    android:layout_width=\"match_parent\"\n    android:layout_height=\"match_parent\">\n\n    <androidx.coordinatorlayout.widget.CoordinatorLayout\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"match_parent\"\n        android:layout_marginBottom=\"?attr/actionBarSize\">\n\n        <!-- Screen content -->\n\n        <FrameLayout\n            android:id=\"@+id/scrim\"\n            android:layout_width=\"match_parent\"\n            android:layout_height=\"match_parent\" />\n\n        <com.google.android.material.navigation.NavigationView\n            ...\n            android:layout_width=\"match_parent\"\n            android:layout_height=\"wrap_content\"\n            app:layout_behavior=\"@string/bottom_sheet_behavior\"\n            app:behavior_hideable=\"true\" />\n\n    </androidx.coordinatorlayout.widget.CoordinatorLayout>\n\n    <com.google.android.material.bottomappbar.BottomAppBar\n        android:id=\"@+id/bottomAppBar\"\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"wrap_content\"\n        android:layout_gravity=\"bottom\"\n        app:navigationIcon=\"@drawable/ic_menu_24dp\" />\n\n</androidx.coordinatorlayout.widget.CoordinatorLayout>\n```\n\nIn code:\n\n```kt\nval bottomSheetBehavior = BottomSheetBehavior.from(navigationView)\nbottomSheetBehavior.state = BottomSheetBehavior.STATE_HIDDEN\n\nbottomAppBar.setNavigationOnClickListener {\n    bottomSheetBehavior.state = BottomSheetBehavior.STATE_EXPANDED\n}\n\nnavigationView.setNavigationItemSelectedListener { menuItem ->\n    // Handle menu item selected\n    menuItem.isChecked = true\n    bottomSheetBehavior.state = BottomSheetBehavior.STATE_HIDDEN\n    true\n}\n\nscrim.setOnClickListener {\n    bottomSheetBehavior.state = BottomSheetBehavior.STATE_HIDDEN\n}\n\nbottomSheetBehavior.addBottomSheetCallback(object : BottomSheetBehavior.BottomSheetCallback() {\n    override fun onSlide(bottomSheet: View, slideOffset: Float) {\n        val baseColor = Color.BLACK\n        // 60% opacity\n        val baseAlpha = ResourcesCompat.getFloat(resources, R.dimen.material_emphasis_medium)\n        // Map slideOffset from [-1.0, 1.0] to [0.0, 1.0]\n        val offset = (slideOffset - (-1f)) / (1f - (-1f)) * (1f - 0f) + 0f\n        val alpha = MathUtils.lerp(0f, 255f, offset * baseAlpha).toInt()\n        val color = Color.argb(alpha, baseColor.red, baseColor.green, baseColor.blue)\n        scrim.setBackgroundColor(color)\n    }\n    override fun onStateChanged(bottomSheet: View, newState: Int) {\n    }\n})\n```\n\nFor more information on bottom app bars see the\n[documentation](https://github.com/material-components/material-components-android/tree/master/docs/components/BottomAppBar.md).\n\n## Theming\n\nNavigation drawers support\n[Material Theming](https://material.io/components/text-fields/#theming) which\ncan customize color, typography and shape.\n\n### Navigation drawer theming example\n\nAPI and source code:\n\n*   `NavigationView`\n    *   [Class definition](https://developer.android.com/reference/com/google/android/material/navigation/NavigationView)\n    *   [GitHub source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/navigation/NavigationView.java)\n\nThe following example shows a navigation drawer with Material Theming.\n\n<mio-image index=8></mio-image>\n\n#### Implementing navigation drawer theming\n\nUse theme attributes, default style theme attributes, and styles in\n`res/values/styles.xml`, which applies to all navigation drawers and affects\nother components:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n    ...\n    <item name=\"colorSecondaryContainer\">@color/shrine_theme_light_secondaryContainer</item>\n    <item name=\"colorOnSecondaryContainer\">@color/shrine_theme_light_onSecondaryContainer</item>\n    <item name=\"colorTertiaryContainer\">@color/shrine_theme_light_tertiaryContainer</item>\n    <item name=\"colorOnTertiaryContainer\">@color/shrine_theme_light_onTertiaryContainer</item>\n    <item name=\"colorSurface\">@color/shrine_theme_light_surface</item>\n    <item name=\"colorOnSurface\">@color/shrine_theme_light_onSurface</item>\n    <item name=\"colorOnSurfaceVariant\">@color/shrine_theme_light_onSurfaceVariant</item>\n    <item name=\"colorOutline\">@color/shrine_theme_light_outline</item>\n    <item name=\"textAppearanceTitleSmall\">@style/TextAppearance.App.TitleSmall</item>\n    <item name=\"textAppearanceLabelLarge\">@style/TextAppearance.App.LabelLarge</item>\n</style>\n\n<style name=\"TextAppearance.App.TitleSmall\" parent=\"TextAppearance.Material3.TitleSmall\">\n    <item name=\"fontFamily\">@font/rubik</item>\n    <item name=\"android:fontFamily\">@font/rubik</item>\n</style>\n\n<style name=\"TextAppearance.App.LabelLarge\" parent=\"TextAppearance.Material3.LabelLarge\">\n    <item name=\"fontFamily\">@font/rubik</item>\n    <item name=\"android:fontFamily\">@font/rubik</item>\n</style>\n\n<style name=\"Widget.App.NavigationView\" parent=\"Widget.Material3.NavigationView\">\n    <item name=\"itemIconTint\">@color/navigation_item_color</item>\n    <item name=\"itemTextColor\">@color/navigation_item_color</item>\n    <item name=\"itemShapeFillColor\">@color/navigation_item_background_color</item>\n</style>\n```\n\nIn `res/color/navigation_item_color.xml`:\n\n```xml\n<selector ...>\n    <item android:color=\"?attr/colorOnTertiaryContainer\" android:state_checked=\"true\"/>\n    <item android:alpha=\"@dimen/material_emphasis_disabled\" android:color=\"?attr/colorOnSurface\" android:state_enabled=\"false\"/>\n    <item android:color=\"?attr/colorOnSurfaceVariant\"/>\n</selector>\n\n```\n\nIn `res/color/navigation_item_background_color.xml`:\n\n```xml\n<selector ...>\n    <item android:alpha=\"@dimen/material_emphasis_disabled\" android:color=\"?attr/colorTertiaryContainer\" android:state_activated=\"true\"/>\n    <item android:alpha=\"@dimen/material_emphasis_disabled\" android:color=\"?attr/colorTertiaryContainer\" android:state_checked=\"true\"/>\n    <item android:color=\"@android:color/transparent\"/>\n</selector>\n```\n\nUse default style theme attributes, styles and theme overlays which apply to all\nnavigation drawers but do not affect other components:\n\n```xml\n<style name=\"Theme.App\" parent=\"Theme.Material3.*\">\n    ...\n    <item name=\"navigationViewStyle\">@style/Widget.App.NavigationView</item>\n</style>\n\n<style name=\"Widget.App.NavigationView\" parent=\"Widget.Material3.NavigationView\">\n    <item name=\"materialThemeOverlay\">@style/ThemeOverlay.App.NavigationView</item>\n    <item name=\"itemIconTint\">@color/navigation_item_color</item>\n    <item name=\"itemTextColor\">@color/navigation_item_color</item>\n    <item name=\"itemShapeFillColor\">@color/navigation_item_background_color</item>\n</style>\n\n<style name=\"ThemeOverlay.App.NavigationView\" parent=\"\">\n    <item name=\"colorSecondaryContainer\">@color/shrine_theme_light_secondaryContainer</item>\n    <item name=\"colorOnSecondaryContainer\">@color/shrine_theme_light_onSecondaryContainer</item>\n    <item name=\"colorTertiaryContainer\">@color/shrine_theme_light_tertiaryContainer</item>\n    <item name=\"colorOnTertiaryContainer\">@color/shrine_theme_light_onTertiaryContainer</item>\n    <item name=\"colorSurface\">@color/shrine_theme_light_surface</item>\n    <item name=\"colorOnSurface\">@color/shrine_theme_light_onSurface</item>\n    <item name=\"colorOnSurfaceVariant\">@color/shrine_theme_light_onSurfaceVariant</item>\n    <item name=\"colorOutline\">@color/shrine_theme_light_outline</item>\n    <item name=\"textAppearanceTitleSmall\">@style/TextAppearance.App.TitleSmall</item>\n    <item name=\"textAppearanceLabelLarge\">@style/TextAppearance.App.LabelLarge</item>\n</style>\n```\n\nUse the style in the layout, which affects only this navigation drawer:\n\n```xml\n<com.google.android.material.navigation.NavigationView\n    ...\n    style=\"@style/Widget.App.NavigationView\" />\n```\n", "markdown_path": "docs/components/NavigationDrawer.md", "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": null, "share_title": null}, "title": "Navigation drawers", "up_next_section": {"items": []}, "document_id": "5513367430889472"}, "mdc_flutter": {"banners": [{"description": "<p>The Flutter team is currently working on Material Design 3 support for <code><a href=\"https://api.flutter.dev/flutter/material/Drawer-class.html\" target=\"_blank\" rel=\"noopener\">Drawer</a></code>. Follow the&nbsp;<a href=\"https://github.com/flutter/flutter/issues/91605\" target=\"_blank\" rel=\"noopener\">GitHub issue</a>&nbsp;and&nbsp;<span style=\"font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans, Helvetica Neue, sans-serif;\">&nbsp;</span><a style=\"font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;\" href=\"https://twitter.com/FlutterDev\" target=\"_blank\" rel=\"noopener\">@FlutterDev</a><span style=\"font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;\">&nbsp;for additional updates.</span></p>", "links": [], "title": "Flutter support in progress"}], "hide_generic_not_available_message": true, "hide_intro_block": true, "image": [], "is_beta": false, "markdown_content": null, "markdown_path": null, "meta": {"keywords": null, "meta_robots": " ", "schema_structure": "{}", "share_description": null, "share_image": {}, "share_title": null}, "title": "Navigation drawers", "up_next_section": {"items": []}, "document_id": "5610111401459712"}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google Material, Google, Material Design 3, Material 3, Material You, Material Design Components, Material Components, components, navigation drawer, navigation", "meta_robots": null, "schema_structure": "{}", "share_description": "Navigation drawers let people switch between UI views on larger devices. Navigation drawers provide access to destinations in your app.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/5b4ff0af7cc467a79a72c21219810bbc1d4b68f7c8226255552ff68780bd4992bf714cb14296a6ce5f2324ec83f207d4b8fc19af189c633304aad8ef266c1df1", "height": 560, "url": "https://lh3.googleusercontent.com/KW-2sMX9xpyX8ebSlKw431RiEykFgS90SJms8kfWusCoMrEaQMYNyytsHlCAZVoWS8jUjUOA-IRnXIIGBT6fB7yNFh16KYqc45tm9C8fqLqwYCPvIvc", "width": 1120}, "share_title": "Navigation drawer \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/09a37221db185d8d8277c7115155278778df9328d7de94b2254920205e03724c3066c92da20f3ea8808541feac5e3875b54edb087c9739007b560baee0dd9cff", "height": 1120, "url": "https://lh3.googleusercontent.com/KBRSNCe0yE2C8ftH8FXB7frKQsiibs8m58pu1gS6MyhsJBSdX6HCEywQivI9RaBAKwAz3j4SZxFYXDfzFHL9n61rg1PRyutIelPVBgWzNRFcW6SK0xtV", "width": 1120}, "foreground_image_1x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/623308e14acb06d5a78e4f564fc35695fcfaba1f7fef2c39468cc6966cdaebc32819b02e8fd364c44a7879867dcdbcb7b163665e52ec4b6a3fb63265b481df91", "height": 1120, "url": "https://lh3.googleusercontent.com/LTgStl5HUZHpSeHrJahYlh573WtRwc3Ffp79VGIkcfWPBFfrW2iYnWvvApSuurlB0qRDhNQAEGN5Z8uEp5ZacxgKUvaZrWO2HEocaZqqlBQAWYCG-kU", "width": 1120}, "foreground_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/0db5d2eafa40abf1577ad7027389a66c4a1680835e16458cb7aa3bac7384d3607bc65e863efef9a3356b8232b6a712936d71e468dd5d513a1e6952f602ab175e", "height": 1000, "url": "https://lh3.googleusercontent.com/87BvuquNLu5vjSHcZfBAHdDwKILQxH-1BXcES49kGBzGTv_sxooLWa9sk0o2iAanIgbfG114yefzGiCZR8IornqIolxUYiWG1I8y4NGUEGNjngRkIA", "width": 2000}, "foreground_image_2x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/dfcb2bfeb10ec32532cebfb3b6ebb5230537aa471bcd9c77888f7564f1d4d9ab3d073129ba4ade6db55b6dfa1a545690d360b3b42c922664973b9d062672ad37", "height": 1000, "url": "https://lh3.googleusercontent.com/M61M4Oxnpkz_YS9kKzJ9rymp7yqrXpMY8gYWalWmQdsMo2Jvmw4IUpYmjFzbx7UTtAGgubuz-G6b6TmQ-fjC_Ic3lyoLpWhvttEvZBbVsYnaT6Ngls8", "width": 2000}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": null, "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {}, "split_background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/438df1d3de37963508b00858948609ccd2eec9c328273f5418b5da03d548f8f28d23dff12d3a8cc244c493785a9257e0c83d9bd4b1c0f3708be7a1eb32b740b2", "height": 4096, "url": "https://lh3.googleusercontent.com/_ipYeG22zN1nYoaUJT6qod1eLv_ptUl8ffTWfNAVI2fjcAszAQM9P9OTOR7RvyeUTVUe1t7YKKGmnUZnoWS8zDM_rrOS75Ct-Se1q02mydKF8kRaIw", "width": 4096}, "split_background_image_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/9a12f32426fe9719c7604298887a6318443b3a59db92eda664e4844336e9a926dad8488c5597ddd333c0d7b3db811dd6f78c418dbc5d3106cfab1d3ec285b597", "height": 4096, "url": "https://lh3.googleusercontent.com/DjFSOTy8DIdsfjRvVql0t2WP6PcCy33PVdwBuha6_2ZM_5BdYFMIs9e9Ssb1RCOsgDbXVK50k3PlwlTlgvQjeUxMCcRp7lTNmHPxSsK5dBqRs_Zp52Y", "width": 4096}, "vertical_foreground_alignment_override": "position_bottom"}, "title": "Navigation drawer", "document_id": "5584597953544192", "modified_date": "2025-04-27"}
\ No newline at end of file
diff --git a/evidence/surface/fetch/side-sheets.json b/evidence/surface/fetch/side-sheets.json
new file mode 100644
index 0000000..f0bb63b
--- /dev/null
+++ b/evidence/surface/fetch/side-sheets.json
@@ -0,0 +1 @@
+{"category": "containment", "component_image_1x1": {}, "component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/63e1ec48cc47f7e519bdeb17fd0e4d2785d66b170214417ed567cdcf7f1c49509ef701f4a9a193c0eb696210a92145824faa260941f8eee2dab028a826e0a4ba", "height": 560, "url": "https://lh3.googleusercontent.com/2ghfWKt28c84ZkVEvzBs9Gqlc5p5Kp0jWnNfqzhaX9eriUbCgMtIcwKrR_krdL9S1TWjDM5jITISkbGo9UGN02jBJuKWm1qX_NuDcS4dTUG-9DqJ3iNy", "width": 1120}, "component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/7ca6e06240289597a3fd6009a290e35195ef355b59772362c73629b60c21bf1a0bebd5e3694fce145fa0be5932043c4e888bee1dde6b3c542d5d860ba9c1a2bb", "height": 560, "url": "https://lh3.googleusercontent.com/BgAqeav7zMp7E9tzvrM0ebQUkXi_95H40BG9N3EDl4S0_-WVknfbDVe0TzdjTj7_qNU_p41tjJVhxgMeJMxYEj44E8dzqdD2Q3mDwbNPMkQH9WgV", "width": 1680}, "component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/97b79c99adea06693883c95fbf0e89373221d1525a5debe81c2ea16c51928d2dba6d8b33b8523800cf0efe61b15348ddc3f84ec06a394a092a456a76271a02da", "height": 560, "url": "https://lh3.googleusercontent.com/09EsQqVuYNxMqe40iqMgORv-3N5GHdYZ6wf61w-afiQFBRtq8Gp4zOyKSTzXsrerXYxeJEgK7VwMVF44hrSTUU1f9OhwgzHDA6mM2kQVtwjFz2s0WMg", "width": 840}, "component_image_position": "center", "dark_component_image_1x1": {}, "dark_component_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/ecae3f337d6bb4bd2c45c90c92890699ab0a1035f17e89493c87341bfe797f5ece708f87fe3ffe83e600e47692faca9056c5636d5d4a7c748abb1b20cdbc4924", "height": 560, "url": "https://lh3.googleusercontent.com/7btR4Ps2BWIN4sr4et_nFwM2Vc5EuHyAUjg5YXZ9RGfIQdi7axXiiufCzHhDexu9NgocrTl0SYXg8LYSCQN3yIGenJVZysPHar9xSHXjiH2X79DBbps", "width": 1120}, "dark_component_image_3x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/22974e2408536d58f7d422026ac87d4e214a18f09cb5b61553f25bebf5cff81f8a19fb68c9f9b12984ad6496470180bb047e294b238ee0d4313e76fe32a6edb8", "height": 560, "url": "https://lh3.googleusercontent.com/KHiIdixbl0gvaXEREggvIFpELZqVB0Tta9zSxKHDOhJ9NAMLymeYXvIZI_KbLwzab-_mgzs2c4nDlaPYKar7ZosRbVUlH_N2KnxE2O6Lqc7wqf1H9Q", "width": 1680}, "dark_component_image_3x2": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/f00291d4565f967bc2cfd102a0cdc3bd5ffc5cb09f2c071d2cf405ded51f129c9c774c31ac8f427ef80633f7047753629bbb079e41c2727692d8385f649b07c3", "height": 560, "url": "https://lh3.googleusercontent.com/b00xPZhqJH7Dxo-zNM0oWw2U4WoGGdlaZ1d7bwORsR9DiyQufLu1pHWXqguGbkEImST42hvvXupNafxwoGhtvjZW1thpxp2IWdqJvl43qe6-d1E3aw", "width": 840}, "description": "Side sheets are surfaces containing supplementary content or actions to support tasks as part of a flow.", "hero": {"background_asset": {}, "background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/06dd7c804834eee1b67788e857eebe3ba70445b75aa85c9ab578b6a864e137d117ae023e27a4626a7797ffaff77af2f2ab60c7140c8399eb646634f7c70f6404", "height": 4096, "url": "https://lh3.googleusercontent.com/VdzSvJMsTSb38fwKy6wpR5ivMxisl7iC2CGIbBI2567doUJh51RoVMR4HxFKE6uEAHcU3gEPPilPNR_fYCLDndeJhe5CsyOHK1HQQzc7-49LgeKxkA", "width": 4096}, "foreground_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/33f6db6481943ca1cd29bc4da1e7d52cc37376ea0fbef9b757ce52e17bc9bc44a6e367778ceeb33fd12cbb81480c25fd03a50301530b2f4a4448b072ce80f056", "height": 1402, "url": "https://lh3.googleusercontent.com/vWz6TjgiWFPGHKOlgrYnd5_nF-UejbXsCjXxlc_uupNhnt9iYYyVPlfN44laJ1ev5KJ-RGxPs_bj46QjJ3zcA6jLQAn8Nv7LiUnXfs58lhzBv3inw0Pv", "width": 1682}, "foreground_image_alignment": "top", "foreground_image_svg": null, "foreground_text_light": false}, "ia_title": "Components / Side sheets", "isDisplayed": true, "jetpack": {}, "mdc_android": {}, "mdc_flutter": {}, "mdc_web": {}, "metadata": {"keywords": "Material, Material Design, Google, Material Design 3, Material 3, Material You, Material Design Components, Material Components, components, cards", "meta_robots": null, "schema_structure": "{}", "share_description": "Side sheets show secondary content anchored to the side of the screen. There are two types: standard and modal.", "share_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/a3b5be2386ef86fe18af1a3dbfc8416c4d283d3cc9f98237d6295b87de2193535b89288075ddd3be214c089de0949cd38301633b982d7d7863d6817e8b2eb0c7", "height": 560, "url": "https://lh3.googleusercontent.com/n8fIOtVTaebce3t16v7jMRN1-sL2Xj13DBTxPiQA3tLczCD_Za-MdXw5wAoGOpoczWBOCeCndDrJCaUKYA4rhL019LE453WkY4c9wR8udXgv__WX-Q", "width": 1120}, "share_title": "Side sheets \u2013 Material Design 3"}, "page_hero": {"foreground_image_1x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/39b881d24fd57cd60dc0c226dc753c696164099eaf729e6df726ba4f3d941486c4ce2a709e597b468376ae97dad2e440d7e13f3d45093d05fff7d28a3bcd927a", "height": 1120, "url": "https://lh3.googleusercontent.com/Ih8_-jx0aXXnzLrg0NPIly8mD7HP5sto3H__SCb71f9d5hDWC3FNsRJsQs5aEYz6-0d-umN_D8NKV9qNlnkuyqN45FtSC_FdyAYdhYHngBnu0kZA7bk", "width": 1120}, "foreground_image_1x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/670982f411375f6c13f9d135a9164764fc6ef0f533b8c436c0f745eae7de9ee6cf321757317a1a2e5d3c5f224b52f19ee9f5511223510428a859afecc00338f8", "height": 1120, "url": "https://lh3.googleusercontent.com/pipxCaBphDcDWoucxdpJ-68nUbkFxTxNuKMtiYQG177TmGyE8rsFdHLmG-swVQZmikv26Yc0GN7aqTPiwfbv4oVDGZprU5yqN2qrRSmHUqBS-VXTPi8", "width": 1120}, "foreground_image_2x1": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/ad863cfd5bb496355e611773562546d9601ca0ce8e461b5d596b4802cd6464d9572a56bf07e966b864e00e93373b8c23c1309c45cade1312fb2c0e1cf6b2a8a8", "height": 1000, "url": "https://lh3.googleusercontent.com/4fWhU-tbJFMBtJr4zcxfcNW401sNzQDGPozetySDtCHxoOHDdy59jGNwOM1QBI8Z0fjP4VGYBf9u8PKZ5mKdoNsdzYdLM7aLWQGalLgBMcfJiZC-fFs", "width": 2000}, "foreground_image_2x1_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/e09d2ad378f76272503db57db9f4af4039dec0432be0f5aa1eea8818d80d483f17806a1f174bd2070b975e3daecd4f08f1d1fb8b6f893d7e71657d284cbbaf58", "height": 1000, "url": "https://lh3.googleusercontent.com/5iCZjwZa3O8SyBL0IwXXTbVR6OsdENXneLXTkBgoug00rifmDkpS62CzqcdgrHazR0feq97s6tMGNKkv9rvwqrm_BWeikXC2UqIJRd34FGDDXE7VJgdA", "width": 2000}, "full_width": false, "full_width_content_centered": false, "horizontal_foreground_alignment_override": "position_left", "main_background_image": {}, "main_background_image_dark_mode": {}, "split_background_asset": {}, "split_background_image": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/dc4cccf5e6481e835b60ab735927ecfc8cddbe77c44c1c4cf001147de878d32c55fae2ee31d5bd189a64a50c8e34b7bbf3a61f2075d83eb9a4dbd7073efd04cf", "height": 4096, "url": "https://lh3.googleusercontent.com/mcJzbWJB-vemWX4xZzDNiWgcIdchbjrhrEixRnpBvpFWQHVNRfHgnd9IKE5l69BYtEa_1Nr03eW6h4k4bKudaVHNwd7JG9JGiGSO4kFbXlEicjf-tg", "width": 4096}, "split_background_image_dark_mode": {"file_path": "_f68a99ffe9144467a917320028f1ce3b_/_95f9980dd12d4f8886c881994eaa6a79_/1a282beb41b91863c4013acdd9a4d5751cc38a4c6c35e43e0f1fe18d8fb87040111418fba574f890ca157e74547c47df77598ed4caf04d94697571deb497249d", "height": 4096, "url": "https://lh3.googleusercontent.com/bs-f9MjdinTVKLD68JtgGSOKHeBeGZiENS3Pixg7rzrY1FPaMoCjWPBm2bg3CR0TE8dLI2ZqzdABAVsfYeshnjtVDpftKw8oqFJGycMvEeq1LplUsbU", "width": 4096}, "vertical_foreground_alignment_override": "position_bottom"}, "title": "Side sheets", "document_id": "5634981699387392", "modified_date": "2025-07-15"}
\ No newline at end of file
diff --git a/evidence/surface/model/layers.yaml b/evidence/surface/model/layers.yaml
new file mode 100644
index 0000000..6fa03e0
--- /dev/null
+++ b/evidence/surface/model/layers.yaml
@@ -0,0 +1,76 @@
+schema_version: 1
+updated_at: "2026-02-22"
+scope: "surface"
+status: "draft"
+
+layer_model:
+  - id: "base_content"
+    z_index_order: 0
+    purpose: "Main page content layer."
+  - id: "docked_surfaces"
+    z_index_order: 100
+    purpose: "Coplanar/standard surfaces sharing layout space."
+    examples:
+      - "standard_side_sheet"
+      - "standard_navigation_drawer"
+      - "persistent_bottom_sheet"
+  - id: "floating_non_modal"
+    z_index_order: 200
+    purpose: "Temporary non-modal floating surfaces."
+    examples:
+      - "menu"
+      - "popover_like_surface"
+  - id: "modal_scrim"
+    z_index_order: 300
+    purpose: "Input-blocking scrim behind modal surfaces."
+  - id: "modal_surfaces"
+    z_index_order: 400
+    purpose: "Modal surface stack."
+    examples:
+      - "dialog"
+      - "modal_bottom_sheet"
+      - "modal_navigation_drawer"
+      - "modal_side_sheet"
+  - id: "top_overlays"
+    z_index_order: 500
+    purpose: "Critical/system overlays that may appear above modal stack."
+
+orchestration_rules:
+  - id: "LR-001"
+    statement: "Every surface instance must belong to exactly one active layer at a time."
+  - id: "LR-002"
+    statement: "Entering modal mode must bind the surface to modal_surfaces and enforce modal_scrim policy."
+  - id: "LR-003"
+    statement: "Transition docked->modal requires explicit layer rebinding, not only geometry change."
+  - id: "LR-004"
+    statement: "Transient non-modal overlays tied to background content are dismissed when blocking modal state starts."
+  - id: "LR-005"
+    statement: "Focus ownership belongs to top item in modal_surfaces stack when stack is non-empty."
+
+stack_policy:
+  modal_stack:
+    mode: "lifo"
+    allow_multiple: true
+    default_on_new_modal: "push"
+    optional_same_task_policy: "replace_top"
+  transient_overlay_policy:
+    on_modal_entry:
+      background_attached: "dismiss"
+      modal_attached: "rebind_to_modal_context_if_supported"
+
+conflict_scenarios:
+  - id: "LC-001"
+    scenario: "docked_side_sheet_to_modal_dialog_while_modal_exists"
+    default_resolution:
+      - "push new modal dialog on modal stack"
+      - "set focus to new top modal"
+      - "keep scrim active"
+  - id: "LC-002"
+    scenario: "menu_open_request_while_modal_dialog_active"
+    default_resolution:
+      - "allow only if anchor belongs to top modal subtree"
+      - "otherwise reject_or_dismiss_request"
+  - id: "LC-003"
+    scenario: "viewport_shrinks_standard_to_modal"
+    default_resolution:
+      - "atomic switch: geometry update + layer rebind + focus/scrim update"
diff --git a/evidence/surface/model/requirements.yaml b/evidence/surface/model/requirements.yaml
new file mode 100644
index 0000000..550942d
--- /dev/null
+++ b/evidence/surface/model/requirements.yaml
@@ -0,0 +1,129 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface"
+status: "draft"
+
+definition:
+  id: "surface"
+  summary: "Generalized M3 surface container capable of geometry and modality transformations."
+
+defaults:
+  shape:
+    value: "rectangle"
+    corner_radius: "0"
+  size:
+    mode: "fill_available_space"
+  spacing:
+    margin: "none"
+    padding: "none"
+  placement_rules:
+    value: "not_imposed"
+  visual_hierarchy:
+    based_on:
+      - "m3_surface_roles"
+      - "m3_elevation"
+
+capabilities:
+  geometry:
+    width:
+      value: "resizable_range"
+      required: true
+    height:
+      value: "resizable_range"
+      required: true
+    corners:
+      all_sides_change: true
+      selected_sides_change: true
+  anchoring:
+    values: ["center", "anchor", "bottom", "start", "end"]
+  modality:
+    values: ["standard", "modal"]
+  transition_support:
+    reversible_morphs_preferred: true
+
+transform_scenarios:
+  - id: "TS-001"
+    from: "card"
+    to: "page_like_container"
+    required: true
+    notes:
+      - "Must respect reserved areas (top app bar, navigation regions)."
+  - id: "TS-002"
+    from: "side_sheet"
+    to: "modal_dialog"
+    required: true
+  - id: "TS-003"
+    from: "menu"
+    to: "modal_surface"
+    required: true
+    trigger_hint: "compact_viewport"
+  - id: "TS-004"
+    from: "standard_sheet_or_drawer"
+    to: "modal_sheet_or_drawer"
+    required: true
+  - id: "TS-005"
+    from: "standard_side_sheet"
+    to: "modal_side_sheet"
+    required: true
+    notes:
+      - "Prefer preserving side anchor continuity during docked->modal switch."
+
+boundaries:
+  includes:
+    - "container_geometry"
+    - "shape_elevation_surface_profile"
+    - "modality_scrim_focus"
+    - "container_motion_profile"
+  excludes:
+    - "business_logic_of_content"
+    - "domain_semantics_of_inner_widgets"
+    - "route_level_page_composition_as_a_whole"
+
+requirements:
+  - id: "SC-REQ-001"
+    kind: "functional"
+    priority: "must"
+    statement: "Surface container must be content-agnostic."
+  - id: "SC-REQ-002"
+    kind: "functional"
+    priority: "must"
+    statement: "Surface container must support morphing between key surface archetypes."
+  - id: "SC-REQ-003"
+    kind: "functional"
+    priority: "must"
+    statement: "Surface container must support modality switching with corresponding scrim/focus behavior."
+  - id: "SC-REQ-004"
+    kind: "functional"
+    priority: "must"
+    statement: "Surface container must support layout-aware constraints by viewport/window class."
+  - id: "SC-REQ-005"
+    kind: "non_functional"
+    priority: "must"
+    statement: "Geometry decisions must be deterministic."
+  - id: "SC-REQ-006"
+    kind: "non_functional"
+    priority: "must"
+    statement: "Key geometry and visual parameters must be tokenizable."
+  - id: "SC-REQ-007"
+    kind: "non_functional"
+    priority: "should"
+    statement: "Morph transitions should be reversible unless explicitly one-way by UX intent."
+  - id: "SC-REQ-008"
+    kind: "functional"
+    priority: "must"
+    statement: "Side-sheet profile must define preferred edge policy (end/right), fixed-width mode, and optional inset contract."
+  - id: "SC-REQ-009"
+    kind: "non_functional"
+    priority: "must"
+    statement: "Docked-to-modal side-sheet transition must preserve visual continuity (no teleport between states)."
+
+risks:
+  - id: "SC-RISK-001"
+    level: "high"
+    statement: "Overgeneralization may erase useful component-specific constraints."
+  - id: "SC-RISK-002"
+    level: "high"
+    statement: "Platform divergence (Compose/MDC/Web) may require explicit branching strategy."
+  - id: "SC-RISK-003"
+    level: "medium"
+    statement: "Missing direct side-sheet numeric redlines weakens confidence in unified geometry."
diff --git a/evidence/surface/model/spec-findings.yaml b/evidence/surface/model/spec-findings.yaml
new file mode 100644
index 0000000..4c97b32
--- /dev/null
+++ b/evidence/surface/model/spec-findings.yaml
@@ -0,0 +1,178 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface"
+status: "draft"
+
+method_limits:
+  - "M3 live pages are JS-driven in CLI context; direct body parsing is limited."
+  - "Primary extraction channels used: runtime page-data payloads and official indexed snippets."
+
+findings:
+  - id: "WF-001"
+    topic: "menu_is_temporary_surface"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Menus are described as a temporary surface for a list of choices."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/4984542628413440.json"
+    extracted_from:
+      file: "/tmp/m3_page_menus_latest.md"
+
+  - id: "WF-002"
+    topic: "standard_bottom_sheet_coplanar"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Standard bottom sheet co-exists with main UI and allows simultaneous interaction."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+    extracted_from:
+      file: "/tmp/m3_page_bottom_sheets_latest.md"
+
+  - id: "WF-003"
+    topic: "modal_bottom_sheet_blocks_background"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Modal bottom sheet blocks interaction with rest of screen and is modal."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+    extracted_from:
+      file: "/tmp/m3_page_bottom_sheets_latest.md"
+
+  - id: "WF-004"
+    topic: "modal_bottom_sheet_as_alt_to_menu_dialog"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Modal bottom sheet is presented as an alternative to inline menus and simple dialogs on mobile."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+    extracted_from:
+      file: "/tmp/m3_page_bottom_sheets_latest.md"
+
+  - id: "WF-005"
+    topic: "modal_bottom_sheet_dismiss_behavior"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Tapping outside modal bottom sheet dismisses it; drag-down dismissal is supported."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+    extracted_from:
+      file: "/tmp/m3_page_bottom_sheets_latest.md"
+
+  - id: "WF-006"
+    topic: "standard_navigation_drawer_coplanar"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Standard navigation drawer allows interaction with both content and drawer simultaneously."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5584597953544192.json"
+    extracted_from:
+      file: "/tmp/m3_navigation_drawer_mdc_android.md"
+
+  - id: "WF-007"
+    topic: "modal_navigation_drawer_scrim"
+    confidence: "high"
+    evidence_type: "page_data_markdown"
+    statement: "Modal navigation drawer blocks background interaction with scrim and is elevated over app UI."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5584597953544192.json"
+    extracted_from:
+      file: "/tmp/m3_navigation_drawer_mdc_android.md"
+
+  - id: "WF-008"
+    topic: "side_sheet_semantics"
+    confidence: "high"
+    evidence_type: "page_data_metadata"
+    statement: "Side sheets are supplementary/secondary content anchored to side; standard and modal variants are present."
+    sources:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+
+  - id: "WF-009"
+    topic: "layout_uses_window_size_classes"
+    confidence: "high"
+    evidence_type: "page_data_metadata"
+    statement: "Applying layout guidance is tied to window size classes."
+    sources:
+      - "https://m3.material.io/page-data/GuidelinesM3/6396979944620032.json"
+
+  - id: "WF-010"
+    topic: "menu_to_bottom_sheet_compact"
+    confidence: "medium"
+    evidence_type: "official_search_snippet"
+    statement: "Menus guidance snippet indicates adapting menus into bottom sheets on compact windows."
+    sources:
+      - "https://m3.material.io/components/menus/guidelines"
+    snippet_files:
+      - "/tmp/m3_search_side_sheet_specs.json"
+      - "/tmp/m3_search_sheet_width.json"
+
+  - id: "WF-011"
+    topic: "side_sheet_fixed_width_full_height"
+    confidence: "medium"
+    evidence_type: "official_search_snippet"
+    statement: "Side sheets guidance snippet indicates fixed width and typical full-height behavior."
+    sources:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    snippet_files:
+      - "/tmp/m3_search_side_sheet_specs.json"
+
+  - id: "WF-012"
+    topic: "bottom_vs_side_sheet_content_adaptation"
+    confidence: "medium"
+    evidence_type: "official_search_snippet"
+    statement: "Bottom sheets guidance snippet indicates similar content may move to side sheet on desktop."
+    sources:
+      - "https://m3.material.io/components/bottom-sheets/guidelines"
+    snippet_files:
+      - "/tmp/m3_search_side_sheet.json"
+
+  - id: "WF-013"
+    topic: "coplanar_side_sheet_transition_pattern"
+    confidence: "medium"
+    evidence_type: "official_search_snippet"
+    statement: "Transitions snippet mentions dedicated enter/exit transition for coplanar side sheet."
+    sources:
+      - "https://m3.material.io/styles/motion/transitions"
+    snippet_files:
+      - "/tmp/m3_search_side_sheet.json"
+
+  - id: "WF-014"
+    topic: "large_window_third_pane_side_sheet"
+    confidence: "medium"
+    evidence_type: "official_search_snippet"
+    statement: "Applying layout snippets mention standard side sheet as a third pane on extra-large windows."
+    sources:
+      - "https://m3.material.io/foundations/layout/applying-layout/large-extra-large"
+      - "https://m3.material.io/foundations/layout/applying-layout"
+    snippet_files:
+      - "/tmp/m3_search_side_sheet.json"
+      - "/tmp/m3_search_sheet_width.json"
+
+  - id: "WF-015"
+    topic: "side_sheet_dimensions_depend_on_layout_regions"
+    confidence: "medium"
+    evidence_type: "guidance_excerpt_local_capture"
+    statement: "Side sheet dimensions are tied to how the app layout is subdivided into UI regions."
+    sources:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    extracted_from:
+      file: "evidence/surface/panel/side-sheet-guidance.md"
+
+  - id: "WF-016"
+    topic: "side_sheet_preferred_right_edge"
+    confidence: "medium"
+    evidence_type: "guidance_excerpt_local_capture"
+    statement: "Side sheets are placed on screen edge, usually on the right side to avoid interference with left-edge navigation."
+    sources:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    extracted_from:
+      file: "evidence/surface/panel/side-sheet-guidance.md"
+
+  - id: "WF-017"
+    topic: "side_sheet_optional_inset_16dp"
+    confidence: "medium"
+    evidence_type: "guidance_excerpt_local_capture"
+    statement: "Side sheets may be slightly inset by 16dp as an optional geometry mode."
+    sources:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    extracted_from:
+      file: "evidence/surface/panel/side-sheet-guidance.md"
diff --git a/evidence/surface/model/transitions.yaml b/evidence/surface/model/transitions.yaml
new file mode 100644
index 0000000..a8891a5
--- /dev/null
+++ b/evidence/surface/model/transitions.yaml
@@ -0,0 +1,143 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface"
+status: "draft"
+
+transitions:
+  - id: "TR-001"
+    from: "card"
+    to: "page_like_container"
+    triggers:
+      - "user_primary_action"
+      - "expand_details_flow"
+    preconditions:
+      - "container_can_expand_within_layout_constraints"
+    layer_actions:
+      from_layer: "base_content"
+      to_layer: "base_content"
+      notes:
+        - "No mandatory modalization."
+    focus_scrim:
+      focus_policy: "preserve_or_shift_to_expanded_container"
+      scrim: "none_by_default"
+    motion_profile: "container_expand"
+
+  - id: "TR-002"
+    from: "menu"
+    to: "modal_bottom_sheet"
+    triggers:
+      - "compact_viewport"
+      - "longer_labels_or_richer_actions"
+    preconditions:
+      - "menu_content_suitable_for_sheet_presentation"
+    layer_actions:
+      from_layer: "floating_non_modal"
+      to_layer: "modal_surfaces"
+      notes:
+        - "dismiss menu before modal sheet enter"
+    focus_scrim:
+      focus_policy: "contained_or_trap"
+      scrim: "required"
+    motion_profile: "menu_fade_out_then_sheet_slide_y_in"
+
+  - id: "TR-003"
+    from: "standard_side_sheet"
+    to: "modal_dialog"
+    triggers:
+      - "task_intent_becomes_blocking"
+      - "available_space_or_context_change"
+    preconditions:
+      - "dialog_variant_available_for_task"
+    layer_actions:
+      from_layer: "docked_surfaces"
+      to_layer: "modal_surfaces"
+      notes:
+        - "layer rebind is mandatory"
+        - "if modal exists: push by default, replace_top for same task group"
+    focus_scrim:
+      focus_policy: "trap"
+      scrim: "required"
+    motion_profile: "side_exit_x_then_dialog_enter_scale"
+
+  - id: "TR-004"
+    from: "standard_navigation_drawer"
+    to: "modal_navigation_drawer"
+    triggers:
+      - "window_class_to_compact"
+      - "layout_cannot_support_coplanar_drawer"
+    preconditions:
+      - "drawer_destinations_preserved"
+    layer_actions:
+      from_layer: "docked_surfaces"
+      to_layer: "modal_surfaces"
+      notes:
+        - "enable modal scrim and block background input"
+    focus_scrim:
+      focus_policy: "contained"
+      scrim: "required"
+    motion_profile: "slide_x_modal"
+
+  - id: "TR-005"
+    from: "modal_navigation_drawer"
+    to: "standard_navigation_drawer"
+    triggers:
+      - "window_class_to_medium_or_expanded"
+      - "layout_allows_coplanar_drawer"
+    preconditions:
+      - "space_for_content_plus_drawer"
+    layer_actions:
+      from_layer: "modal_surfaces"
+      to_layer: "docked_surfaces"
+      notes:
+        - "remove modal scrim after transition completes"
+    focus_scrim:
+      focus_policy: "return_to_content_or_drawer_context"
+      scrim: "disabled"
+    motion_profile: "slide_x_to_docked"
+
+  - id: "TR-006"
+    from: "modal_bottom_sheet"
+    to: "menu"
+    triggers:
+      - "window_class_to_non_compact"
+      - "action_set_simplified"
+    preconditions:
+      - "anchor_available"
+      - "menu_density_readable"
+    layer_actions:
+      from_layer: "modal_surfaces"
+      to_layer: "floating_non_modal"
+      notes:
+        - "drop scrim and return to non-modal interaction"
+    focus_scrim:
+      focus_policy: "anchor_context"
+      scrim: "disabled"
+    motion_profile: "sheet_exit_y_then_menu_fade_in"
+
+  - id: "TR-007"
+    from: "standard_side_sheet"
+    to: "modal_side_sheet"
+    triggers:
+      - "window_class_change_or_layout_compaction"
+      - "task_requires_blocking_focus"
+    preconditions:
+      - "side_sheet_content_remains_valid_in_modal_mode"
+    layer_actions:
+      from_layer: "docked_surfaces"
+      to_layer: "modal_surfaces"
+      notes:
+        - "keep side anchor continuity (prefer end/right edge)"
+        - "rebind to modal layer and release docked layout space as one transaction"
+        - "show modal scrim during transition"
+    focus_scrim:
+      focus_policy: "trap"
+      scrim: "required"
+    motion_profile: "raise_elevation_pin_end_scrim_in_layout_reflow"
+
+global_guards:
+  - id: "TG-001"
+    statement: "When modal stack is non-empty, background-attached menus cannot open."
+  - id: "TG-002"
+    statement: "Any transition changing modality must define explicit focus and scrim actions."
+  - id: "TG-003"
+    statement: "Layer rebind and geometry change should be executed as one transaction."
diff --git a/evidence/surface/panel/boundaries.yaml b/evidence/surface/panel/boundaries.yaml
new file mode 100644
index 0000000..3b70ddc
--- /dev/null
+++ b/evidence/surface/panel/boundaries.yaml
@@ -0,0 +1,74 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface_panel"
+
+family:
+  id: "surface_panel"
+  working_name: "Surface panel"
+  purpose: "Generalized temporary or edge-anchored surface container family."
+
+includes:
+  - id: "dialog"
+    role: "centered modal surface"
+    covered: true
+  - id: "menu"
+    role: "anchor-based temporary surface"
+    covered: true
+  - id: "bottom_sheet"
+    role: "bottom edge-anchored surface"
+    covered: true
+  - id: "side_sheet"
+    role: "side edge-anchored surface"
+    covered: true
+  - id: "navigation_drawer"
+    role: "navigation-specialized side surface"
+    covered: true
+
+excludes:
+  - id: "card"
+    reason: "Static containment surface, not a temporary layer surface."
+  - id: "route_level_page_layout"
+    reason: "Page-level composition, outside panel lifecycle."
+  - id: "app_bar_and_navigation_rail"
+    reason: "Different semantics and lifecycle."
+
+variation_axes:
+  - name: "placement"
+    values: ["center", "bottom", "start", "end", "anchor"]
+  - name: "modality"
+    values: ["standard", "modal"]
+  - name: "layout_interaction"
+    values: ["overlay", "coplanar"]
+  - name: "dismiss_model"
+    values: ["outside_click", "back", "swipe_or_drag"]
+  - name: "scrim"
+    values: ["none", "required"]
+  - name: "focus_policy"
+    values: ["none", "contained", "trap"]
+  - name: "motion_profile"
+    values: ["fade_scale", "slide_y", "slide_x"]
+  - name: "edge_inset_policy"
+    values: ["none", "inset_16dp_optional"]
+
+invariants:
+  - "surface_role: container color layer must be explicit."
+  - "shape_profile: radius family must be tokenized."
+  - "elevation_profile: base and state deltas must be tokenized."
+  - "size_constraints: min/max constraints must be explicit."
+  - "edge_policy: side surfaces must define preferred edge and inset policy."
+  - "accessibility_behavior: focus, keyboard/back and dismiss semantics must be explicit."
+
+known_limits:
+  - id: "side_sheet_numeric_geometry_unresolved"
+    severity: "high"
+    detail: "No direct numeric side-sheet redline/spec table available in accessible runtime payload."
+    impact: "Side-sheet geometry cannot be promoted to final baseline yet."
+
+evidence_refs:
+  - "evidence/surface/panel/side-sheet-guidance.md"
+  - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+  - "https://m3.material.io/components/side-sheets/overview"
+  - "https://m3.material.io/components/side-sheets/specs"
+  - "https://m3.material.io/components/side-sheets/guidelines"
+  - "https://m3.material.io/components/side-sheets/accessibility"
+  - "https://m3.material.io/components/sheets-side"
diff --git a/evidence/surface/panel/decisions.yaml b/evidence/surface/panel/decisions.yaml
new file mode 100644
index 0000000..55d54d6
--- /dev/null
+++ b/evidence/surface/panel/decisions.yaml
@@ -0,0 +1,79 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface_panel"
+
+decisions:
+  - id: "DL-001"
+    date: "2026-02-22"
+    topic: "bottom_sheet_elevation"
+    context:
+      compose_value: "1dp"
+      mdc_android_value: "3dp"
+    decision: "keep_platform_specific_tokens"
+    outcome:
+      - "surface.bottom_sheet.container.elevation@android_compose = 1dp"
+      - "surface.bottom_sheet.container.elevation@android_mdc = 3dp"
+    rationale: "Forced unification would introduce visible drift in at least one implementation branch."
+    revisit_trigger:
+      - "Direct M3 side/spec runtime tables become available and conflict model changes."
+    status: "active"
+
+  - id: "DL-002"
+    date: "2026-02-22"
+    topic: "navigation_drawer_width"
+    context:
+      compose_values:
+        min: "240dp"
+        max: "360dp"
+      mdc_android_value:
+        max: "280dp"
+    decision: "keep_platform_specific_tokens"
+    outcome:
+      - "surface.navigation_drawer.container.width.min@android_compose = 240dp"
+      - "surface.navigation_drawer.container.width.max@android_compose = 360dp"
+      - "surface.navigation_drawer.container.width.max@android_mdc = 280dp"
+    rationale: "Width is layout-critical; premature normalization risks adaptive layout regressions."
+    revisit_trigger:
+      - "Interactive M3/Figma redlines confirm a unified canonical width model."
+    status: "active"
+
+  - id: "DL-003"
+    date: "2026-02-22"
+    topic: "side_sheet_geometry"
+    context:
+      runtime_page_data:
+        components_m3_document_id: "5634981699387392"
+        endpoint: "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+        payload_observation: "overview metadata present, numeric spec/redline tables absent, platform blocks empty"
+      legacy_route_check:
+        route: "/components/sheets-side"
+        document_id: "5696654316666880"
+        page_data_result: "404 for tested Components and ComponentsM3 variants"
+    decision: "keep_side_sheet_tokens_in_inference_status"
+    outcome:
+      - "Do not promote side-sheet geometry to final baseline."
+      - "Keep side-sheet geometry as inference-only working hypotheses."
+    rationale: "No machine-readable primary source with numeric geometry values is currently available."
+    revisit_trigger:
+      - "Interactive redlines become accessible in M3/Figma."
+      - "Runtime payload starts exposing side-sheet numeric tables."
+    status: "active"
+
+  - id: "DL-004"
+    date: "2026-02-23"
+    topic: "side_sheet_placement_and_inset_guidance"
+    context:
+      local_guidance_excerpt: "evidence/surface/panel/side-sheet-guidance.md"
+      extracted_rules:
+        - "fixed width"
+        - "typically full-height"
+        - "preferred edge: end/right"
+        - "optional inset: 16dp"
+    decision: "record_as_guidance_constraints_without_promoting_to_numeric_baseline"
+    outcome:
+      - "Added structured side-sheet guidance tokens and modal profile sidecar."
+      - "Kept numeric side-sheet geometry in inference status."
+    rationale: "Guidance text is actionable for behavior policy, but it is not a full redline table."
+    revisit_trigger:
+      - "Live redlines/spec tables confirm or adjust edge/inset policy."
+    status: "active"
diff --git a/evidence/surface/panel/side-sheet-guidance.md b/evidence/surface/panel/side-sheet-guidance.md
new file mode 100644
index 0000000..d53ec18
--- /dev/null
+++ b/evidence/surface/panel/side-sheet-guidance.md
@@ -0,0 +1,30 @@
+# Side Sheet Guidance
+
+Date: 2026-02-23  
+Status: derived guidance snapshot
+
+## Source
+
+Primary source:
+- `https://m3.material.io/components/side-sheets/guidelines`
+
+This file preserves the local guidance statements that were used by the structured panel evidence.
+
+## Captured guidance
+
+- Side sheets use a fixed-width presentation model.
+- Side sheets typically span the full available height.
+- Side-sheet dimensions depend on how the layout is divided into regions.
+- The preferred edge is usually `end/right` to avoid conflict with left-edge navigation.
+- A slight `16dp` inset may be used as an optional variant.
+
+## Usage in this evidence package
+
+This guidance is referenced by:
+- `panel/tokens.yaml`
+- `panel/boundaries.yaml`
+- `panel/decisions.yaml`
+- `panel/side-sheet-modal.yaml`
+- `model/spec-findings.yaml`
+
+Numeric side-sheet redlines are still unavailable in the accessible runtime payload, so this file should be treated as guidance, not as a final numeric baseline.
diff --git a/evidence/surface/panel/side-sheet-modal.yaml b/evidence/surface/panel/side-sheet-modal.yaml
new file mode 100644
index 0000000..1213fe0
--- /dev/null
+++ b/evidence/surface/panel/side-sheet-modal.yaml
@@ -0,0 +1,59 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface_panel_side_sheet_modal"
+status: "draft"
+
+sources:
+  - id: "SRC-001"
+    type: "guidance_excerpt_local_capture"
+    ref: "evidence/surface/panel/side-sheet-guidance.md"
+    derived_from:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    confidence: "medium"
+  - id: "SRC-002"
+    type: "runtime_page_data_metadata"
+    ref: "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+    confidence: "high"
+
+behavior_profile:
+  geometry:
+    width_mode: "fixed"
+    height_mode: "full_height_typical"
+    layout_region_dependency: true
+  placement:
+    edge: "end_or_right_preferred"
+    rationale: "avoid_conflict_with_left_navigation_components"
+    inset:
+      value: "16dp"
+      optional: true
+  modality:
+    variants:
+      - "standard"
+      - "modal"
+
+modalization_transition:
+  id: "SS-MODAL-001"
+  from: "standard_side_sheet"
+  to: "modal_side_sheet"
+  expectations:
+    - "no_teleport_visual_continuity"
+    - "elevation_ramp_during_transition"
+    - "pin_to_viewport_end_edge"
+    - "scrim_enters_while_modalization_happens"
+    - "layout_space_released_transactionally"
+  layer_binding:
+    from: "docked_surfaces"
+    to: "modal_surfaces"
+  focus_policy: "trap"
+
+constraints:
+  numeric_redlines_available: false
+  interpretation_policy: "treat_as_guidance_until_redlines_confirmed"
+
+links:
+  markdown:
+    - "evidence/surface/summary.md"
+    - "evidence/surface/panel/side-sheet-guidance.md"
+  yaml:
+    - "evidence/surface/panel/tokens.yaml"
+    - "evidence/surface/model/transitions.yaml"
diff --git a/evidence/surface/panel/tokens.yaml b/evidence/surface/panel/tokens.yaml
new file mode 100644
index 0000000..175fb24
--- /dev/null
+++ b/evidence/surface/panel/tokens.yaml
@@ -0,0 +1,277 @@
+schema_version: 1
+updated_at: "2026-02-23"
+scope: "surface_panel"
+
+status_legend:
+  baseline: "Candidate for shared foundation baseline."
+  platform_specific: "Kept split by implementation branch."
+  inference: "Working hypothesis pending direct redline/spec confirmation."
+  guidance: "Guidance-level rule from textual source; not a strict numeric redline."
+
+tokens:
+  - id: "surface.dialog.container.shape.radius"
+    component: "dialog"
+    platform: "android"
+    breakpoint: "all"
+    value: "28dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/DialogTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/5732087063379968.json"
+    note: "MDC Android payload confirms shapeAppearanceMediumComponent corner size 28dp."
+
+  - id: "surface.dialog.container.width.min"
+    component: "dialog"
+    platform: "android"
+    breakpoint: "all"
+    value: "280dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AlertDialog.kt"
+
+  - id: "surface.dialog.container.width.max"
+    component: "dialog"
+    platform: "android"
+    breakpoint: "all"
+    value: "560dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/AlertDialog.kt"
+
+  - id: "surface.menu.container.shape.radius"
+    component: "menu"
+    platform: "android"
+    breakpoint: "all"
+    value: "4dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/MenuTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/4984542628413440.json"
+
+  - id: "surface.menu.container.elevation"
+    component: "menu"
+    platform: "android"
+    breakpoint: "all"
+    value: "3dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/MenuTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/4984542628413440.json"
+
+  - id: "surface.bottom_sheet.container.max_width"
+    component: "bottom_sheet"
+    platform: "android"
+    breakpoint: "all"
+    value: "640dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/SheetDefaults.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+
+  - id: "surface.bottom_sheet.container.elevation"
+    component: "bottom_sheet"
+    platform: "android_compose"
+    breakpoint: "all"
+    value: "1dp"
+    status: "platform_specific"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/SheetBottomTokens.kt"
+
+  - id: "surface.bottom_sheet.container.elevation"
+    component: "bottom_sheet"
+    platform: "android_mdc"
+    breakpoint: "all"
+    value: "3dp"
+    status: "platform_specific"
+    confidence: "high"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5317529291587584.json"
+    note: "MDC Android payload default android:elevation is 3dp."
+
+  - id: "surface.navigation_drawer.container.width.min"
+    component: "navigation_drawer"
+    platform: "android_compose"
+    breakpoint: "all"
+    value: "240dp"
+    status: "platform_specific"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt"
+
+  - id: "surface.navigation_drawer.container.width.max"
+    component: "navigation_drawer"
+    platform: "android_compose"
+    breakpoint: "all"
+    value: "360dp"
+    status: "platform_specific"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/NavigationDrawer.kt"
+
+  - id: "surface.navigation_drawer.container.width.max"
+    component: "navigation_drawer"
+    platform: "android_mdc"
+    breakpoint: "all"
+    value: "280dp"
+    status: "platform_specific"
+    confidence: "high"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5584597953544192.json"
+    note: "MDC Android payload default android:maxWidth is 280dp for NavigationView."
+
+  - id: "surface.card.container.elevation.filled"
+    component: "card"
+    platform: "android"
+    breakpoint: "all"
+    value: "0dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/FilledCardTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/5274907658944512.json"
+
+  - id: "surface.card.container.elevation.elevated"
+    component: "card"
+    platform: "android"
+    breakpoint: "all"
+    value: "1dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/ElevatedCardTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/5274907658944512.json"
+
+  - id: "surface.card.container.stroke_width.outlined"
+    component: "card"
+    platform: "android"
+    breakpoint: "all"
+    value: "1dp"
+    status: "baseline"
+    confidence: "high"
+    source_refs:
+      - "https://android.googlesource.com/platform/frameworks/support/+/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/OutlinedCardTokens.kt"
+      - "https://m3.material.io/page-data/ComponentsM3/5274907658944512.json"
+
+  - id: "surface.side_sheet.container.width.min"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "240dp"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "No numeric side-sheet spec table available in runtime payload."
+
+  - id: "surface.side_sheet.container.width.mode"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "fixed"
+    status: "guidance"
+    confidence: "medium"
+    source_refs:
+      - "evidence/surface/panel/side-sheet-guidance.md"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "Guidance excerpt indicates fixed width."
+
+  - id: "surface.side_sheet.container.width.max"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "360dp"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "No numeric side-sheet spec table available in runtime payload."
+
+  - id: "surface.side_sheet.container.height"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "full-height"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/components/side-sheets/guidelines"
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+    note: "Derived from metadata/snippet wording, not from explicit numeric redline."
+
+  - id: "surface.side_sheet.container.height.mode"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "full-height-typical"
+    status: "guidance"
+    confidence: "medium"
+    source_refs:
+      - "evidence/surface/panel/side-sheet-guidance.md"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "Guidance excerpt says side sheets typically span full screen height."
+
+  - id: "surface.side_sheet.container.edge.preferred"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "end/right"
+    status: "guidance"
+    confidence: "medium"
+    source_refs:
+      - "evidence/surface/panel/side-sheet-guidance.md"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "Guidance excerpt prefers right edge to avoid interference with left navigation."
+
+  - id: "surface.side_sheet.container.inset.inline"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "16dp_optional"
+    status: "guidance"
+    confidence: "medium"
+    source_refs:
+      - "evidence/surface/panel/side-sheet-guidance.md"
+      - "https://m3.material.io/components/side-sheets/guidelines"
+    note: "Guidance excerpt allows slight inset by 16dp as optional mode."
+
+  - id: "surface.side_sheet.container.shape.radius.open_side"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "~16dp"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+    note: "Approximation via drawer-like geometry behavior."
+
+  - id: "surface.side_sheet.container.elevation.standard"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "~0dp"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+    note: "Approximation via standard drawer-like behavior."
+
+  - id: "surface.side_sheet.container.elevation.modal"
+    component: "side_sheet"
+    platform: "android"
+    breakpoint: "medium_to_expanded"
+    value: "~1dp"
+    status: "inference"
+    confidence: "low"
+    source_refs:
+      - "https://m3.material.io/page-data/ComponentsM3/5634981699387392.json"
+    note: "Approximation via modal drawer-like behavior."
diff --git a/evidence/surface/summary.md b/evidence/surface/summary.md
new file mode 100644
index 0000000..dfe271e
--- /dev/null
+++ b/evidence/surface/summary.md
@@ -0,0 +1,194 @@
+# Surface
+
+Date: 2026-02-23  
+Status: working draft, promoted to canonical evidence
+
+## Outcome
+
+This package captures the design model for a generalized M3 `surface`.
+That model later informed the `M3Surface` components in `m3-vue` and `m3-react`.
+
+## Context and goal
+
+We defined `surface` as a central container primitive that can represent or transform into:
+- dialog,
+- bottom sheet,
+- side sheet,
+- navigation drawer,
+- menu,
+- card, when it grows into a larger container or page-like state.
+
+The goal was to establish the boundaries and requirements for one adaptive container model rather than a disconnected set of special-purpose implementations.
+
+## Working definition
+
+`Surface` is a rectangular container whose visual hierarchy is driven by M3 surface roles and elevation, while its geometry is controlled by tokens and layout rules and may change dynamically.
+
+## Default behavior
+
+- Shape: rectangle, with no forced rounding by default.
+- Size: fills the available space inside its own layout context.
+- Spacing: does not impose its own `margin` or `padding`.
+- Positioning: does not force placement relative to neighboring elements.
+- Visual baseline: uses M3 surface and elevation hierarchy for fill and emphasis.
+
+## Required geometry capabilities
+
+- Width must be able to move through constrained ranges, including `narrow -> full-width`.
+- Height must be able to move through constrained ranges, including `content-height -> full-height`.
+- Corner treatment must support both uniform and side-specific changes.
+- Geometry must support `bottom`, `start`, `end`, `center`, and anchor-driven placement.
+
+## Required transformations
+
+- `card -> page_like_container`
+- `side_sheet <-> modal_dialog`
+- `menu -> modal_dialog` or `menu -> modal_bottom_sheet` on compact viewports
+- `standard_sheet_or_drawer -> modal_sheet_or_drawer`
+- `standard_side_sheet -> modal_side_sheet`
+
+The focus is on container behavior: geometry, modality, motion, focus, and scrim.
+Business logic and inner content composition stay outside the `surface` contract.
+
+## Entity boundaries
+
+Included:
+- container geometry,
+- surface, elevation, and shape profile,
+- modality and scrim behavior,
+- dismiss and focus rules at container level,
+- motion profiles for container transitions.
+
+Excluded:
+- business logic of inner content,
+- domain semantics of specific widgets,
+- full route-level page composition.
+
+## Key requirements
+
+Functional:
+- A surface container must be content-agnostic.
+- A surface container must support morphing between key surface archetypes.
+- A surface container must support modality switching with corresponding scrim and focus behavior.
+- A surface container must support layout-aware constraints by viewport and window class.
+
+Non-functional:
+- Geometry decisions must be deterministic.
+- Key geometry and visual parameters must be tokenizable.
+- Adaptation should be rule-driven rather than a pile of unrelated special cases.
+- Morph transitions should be reversible unless a one-way UX rule explicitly overrides that.
+
+## Main hypothesis
+
+A unified `surface` family can support dialog, sheet, drawer, menu, and card transitions without collapsing into an unusable abstraction.
+
+The main unresolved area is side-sheet geometry: the available runtime M3 payload does not expose direct numeric redlines, so side-sheet numbers remain either `guidance` or `inference`.
+
+## Strengths and risks
+
+Strengths:
+- reduces duplication between dialog, sheet, drawer, menu, and card behavior,
+- gives adaptive transitions one shared conceptual model,
+- matches the M3 emphasis on tokens, surface roles, and layered hierarchy.
+
+Risks:
+- over-generalization can erase useful constraints from specific component families,
+- Compose, MDC, and Web may diverge enough to require explicit branching,
+- missing direct side-sheet redlines lowers confidence in a final unified numeric baseline.
+
+## Evidence package
+
+Human-readable:
+- `summary.md`
+- `panel/side-sheet-guidance.md`
+
+Machine-readable:
+- `model/requirements.yaml`
+- `model/layers.yaml`
+- `model/transitions.yaml`
+- `model/spec-findings.yaml`
+- `panel/boundaries.yaml`
+- `panel/decisions.yaml`
+- `panel/tokens.yaml`
+- `panel/side-sheet-modal.yaml`
+- `fetch/manifest.yaml`
+
+Raw evidence:
+- `fetch/*.json`
+
+## Layer orchestration model
+
+The layer model assumes the following active strata:
+- `base_content`
+- `docked_surfaces`
+- `floating_non_modal`
+- `modal_scrim`
+- `modal_surfaces`
+- `top_overlays`
+
+Core rules:
+- every surface instance belongs to exactly one active layer at a time,
+- entering modal mode requires both modal layer binding and scrim policy,
+- `docked -> modal` is not just geometry change; it is explicit layer rebinding,
+- background-attached transient overlays should close or rebind when modal state begins.
+
+## Transition model
+
+The initial transition matrix covers:
+- `card -> page_like_container`
+- `menu -> modal_bottom_sheet`
+- `standard_side_sheet -> modal_dialog`
+- `standard_navigation_drawer -> modal_navigation_drawer`
+- `modal_navigation_drawer -> standard_navigation_drawer`
+- `modal_bottom_sheet -> menu`
+- `standard_side_sheet -> modal_side_sheet`
+
+For each transition we capture:
+- triggers and preconditions,
+- layer actions,
+- focus and scrim behavior,
+- motion profile.
+
+See `model/transitions.yaml` for the machine-readable matrix.
+
+## Key source-backed findings
+
+High-confidence findings from `page-data` and accessible platform markdown:
+- menus are temporary surfaces,
+- standard bottom sheets coexist with primary content,
+- modal bottom sheets block background interaction,
+- modal bottom sheets can replace inline menus or simple dialogs on mobile,
+- standard navigation drawers allow parallel interaction with drawer and content,
+- modal navigation drawers use scrim and block background interaction,
+- side sheets have explicit standard and modal semantics.
+
+Medium-confidence guidance and snippet findings:
+- compact windows may adapt menus into bottom sheets,
+- side sheets tend to use fixed width and usually full height,
+- side-sheet sizing depends on layout region structure,
+- the preferred side-sheet edge is usually `end/right`,
+- a `16dp` inset may be allowed as an optional mode,
+- similar content may move between bottom-sheet and side-sheet presentations,
+- coplanar side sheets appear to have a dedicated transition pattern.
+
+See `model/spec-findings.yaml` for the structured source list.
+
+## Current baseline judgment
+
+Ready for baseline promotion:
+- dialog shape and width,
+- menu shape and elevation,
+- bottom-sheet max width,
+- card elevation and outlined stroke width.
+
+Keep platform-specific:
+- bottom-sheet elevation,
+- navigation-drawer width.
+
+Keep out of final baseline for now:
+- numeric side-sheet geometry.
+
+## Implementation note
+
+This evidence package describes the intended `surface` model.
+The implementation question is not whether every detail already exists in `M3Surface`, but how closely the current `M3Surface` components in `m3-vue` and `m3-react` match this contract.
diff --git a/skills/exploration-workflow/SKILL.md b/skills/exploration-workflow/SKILL.md
new file mode 100644
index 0000000..f55ee48
--- /dev/null
+++ b/skills/exploration-workflow/SKILL.md
@@ -0,0 +1,272 @@
+---
+name: exploration-workflow
+description: Use this skill only when the user explicitly asks for exploration mode: autonomous hypothesis-driven work on uncertain functionality, with timeboxing, milestone logging, and tightly controlled escalation windows.
+---
+
+# Exploration Workflow
+
+[reread] Reread this skill immediately before starting any explicit exploration-mode run in this repository.
+
+## When To Use
+Use this skill only when the user explicitly switches the task into exploration mode.
+
+Typical signals:
+- the user wants autonomous long-running work with periodic checkpoints;
+- the target is a new or uncertain functional layer;
+- the goal is to validate or reject hypotheses, not just implement a known change;
+- the user expects structured evidence, logs, and bounded escalation behavior.
+
+Do not trigger this skill for ordinary implementation, refactoring, bugfixing, or short investigative questions.
+
+## Entry Handshake
+If the user gives a signal that exploration mode may be desired, do not silently start it.
+Instead, explicitly ask whether they want to start exploration mode now.
+
+That confirmation message must:
+- mention that this repository has an `exploration-workflow` skill;
+- say that exploration starts only after explicit confirmation;
+- say that the confirmation reply must include a concrete time budget.
+
+Accepted confirmation examples:
+- `Да, стартуем exploration на 30 минут`
+- `Да, запускай, бюджет 60 минут`
+- `Start exploration, 120 minutes`
+
+Once the user gives an affirmative answer with an explicit time budget, take this skill into use immediately and follow it from that point onward.
+
+## Source Of Truth
+- `AGENTS.md`
+- `Makefile`
+- `recipes/research.mk`
+- `recipes/research/fetch.sh`
+- `recipes/research/capture.sh`
+- `drafts/current.yml`
+
+## Core Intent
+- Reduce uncertainty around a proposed solution or functional layer.
+- Let the agent work autonomously for a bounded period without drifting into open-ended activity.
+- Keep all risky actions explicit, logged, and reviewable.
+- Produce artifacts that make it easy for the user to resume control at any checkpoint.
+
+## Drafts Layout
+- Exploration state in `drafts/` is owned by this skill.
+- If `drafts/current.yml` does not exist when exploration starts, create it.
+- Every exploration run gets its own dedicated activity directory inside `drafts/`.
+- Use a distinct directory name that is easy to differentiate from other runs.
+Recommended pattern:
+  `drafts/explorations/YYYYMMDD-HHMM-<short-slug>/`
+- `drafts/current.yml` must point to the current activity directory and contain a short run summary.
+- Inside the activity directory, `index.md` is mandatory and acts as the main entry point.
+- `index.md` must describe the task in Russian and link to other files relevant to this exploration.
+- Other files inside the activity directory are fully at the agent's disposal.
+Use them freely for:
+  notes, plans, milestones, facts, decisions, open questions, artifact inventories, external links, and recovery context.
+- Except for `index.md`, there is no fixed file set inside the activity directory.
+Choose the structure that best supports efficient autonomous work.
+- If screenshots, fetched JSON, or other generated artifacts live outside the activity directory, add links to them from `index.md` or another linked file.
+
+## `drafts/current.yml`
+Maintain `drafts/current.yml` as a short machine-readable pointer to the active exploration.
+Minimum fields:
+- `mode`: `exploration`
+- `slug`: short run identifier
+- `path`: relative path to the current activity directory inside `drafts/`
+- `goal`: short current goal
+- `status`: current state such as `planned`, `running`, `blocked`, `done`
+- `started_at`: run start timestamp
+- `timeout_minutes`: agreed timeout
+- `summary`: short human-readable summary
+
+Example:
+```yaml
+mode: exploration
+slug: 20260307-2015-surface-layer
+path: drafts/explorations/20260307-2015-surface-layer
+goal: Проверить новый слой surface/dialog parity и собрать артефакты по расхождениям
+status: running
+started_at: 2026-03-07T20:15:00+04:00
+timeout_minutes: 60
+summary: Исследуется новый слой surface parity; подготовлен план, открыт escalation budget, собираются локальные факты и артефакты.
+```
+
+## `index.md`
+`index.md` is the human entry point for the current exploration directory.
+It must be in Russian and should at least contain:
+- short task statement;
+- current hypothesis or focus;
+- timeout and current status;
+- links to notes, logs, plans, and generated artifacts.
+
+Minimal example:
+```md
+# Exploration: surface-layer parity
+
+## Задача
+Проверить, можно ли собрать новый слой surface/dialog parity без правок production-компонентов.
+
+## Статус
+- Старт: 2026-03-07 20:15 +04:00
+- Бюджет: 60 минут
+- Состояние: running
+
+## Ссылки
+- [План](./plan.md)
+- [Лог наблюдений](./notes.md)
+- [Решения](./decisions.md)
+- [Артефакты](./artifacts.md)
+```
+
+## Required Rules
+- Before execution, prepare a concrete exploration plan with phases, checkpoints, and expected outputs.
+- Before execution, estimate which actions require escalation and which can stay local-only.
+- Do not begin autonomous exploration until the initial plan and escalation budget are defined.
+- Before any non-trivial exploration, ask for a concrete time budget or timeout.
+- Record exploration start immediately in the current activity directory and update `drafts/current.yml`.
+- Keep a running log of milestones, missing inputs, blocked steps, and unavailable artifacts inside the current activity directory.
+- Escalations are forbidden by default.
+- Escalations are allowed only after explicit user sanction for the current scope.
+- Before any sanctioned escalation phase, define an escalation window:
+  exact command set, start marker, and freeze condition.
+- Log `escalation-needed` before requesting escalation.
+- Log `escalation-result` after the sanctioned command set finishes.
+- After escalation freeze, do not issue new escalation requests.
+- Never request a new escalation in the middle of an autonomous run unless the user explicitly re-opens planning.
+- If a needed command was not included in the pre-agreed escalation window, do not request it ad hoc.
+- Instead, log `escalation-blocked` and `missing`, continue with local-only work, and report the gap at the next checkpoint or final handoff.
+- Periodically check elapsed time against the agreed timeout and record time checks.
+- If timeout is reached or likely to be exceeded, stop and ask whether to extend, narrow scope, or finish with current findings.
+
+## Repository Conventions
+- Prefer repository exploration helpers where they exist.
+  At the moment, this includes `m3/experiment/*` Makefile targets.
+- Direct `research-*` commands are allowed only when they are listed in the current escalation window.
+- Prefer one-shot privileged bootstrap:
+  `make m3/experiment/bootstrap/evidence`
+- Treat literal `m3/experiment/*` target names as the current repository command interface for exploration runs until the namespace is renamed in-repo.
+- During exploration-driven component development, do not modify current production
+  components in `src/components` unless explicitly requested.
+- For agent-driven exploratory components, create and use `src/experimental`
+  directories at the same level as `src/components` inside each workspace.
+- Exploratory implementation order is mandatory: implement in
+  `m3-vue/src/experimental` first; port to `m3-react/src/experimental` only after
+  the exploration outcome is explicitly confirmed as successful.
+
+## Workflow
+1. Confirm exploration mode was explicitly requested.
+If it was not, do not use this skill.
+
+2. If the user only hinted at exploration mode, run the entry handshake first.
+Do not start exploration until the user explicitly confirms it and gives a time budget.
+
+3. Build the initial exploration plan before starting execution.
+The plan must include:
+- goal and current uncertainty;
+- ordered phases;
+- checkpoints between phases;
+- expected artifacts;
+- safe local steps;
+- steps that probably require escalation.
+
+4. Build an escalation budget.
+List every command or command family that may need escalation during this run.
+For each item, record:
+- exact command or bounded command set;
+- reason;
+- expected output or artifact;
+- freeze condition after which no more escalation is allowed.
+
+5. Ask for a timeout.
+Examples:
+- `30 minutes`
+- `60 minutes`
+- `120 minutes`
+
+6. Create or select the activity directory under `drafts/`.
+Use a clear distinct name, for example:
+- `drafts/explorations/20260307-2015-surface-layer/`
+- `drafts/explorations/20260307-2015-dialog-parity/`
+
+7. Initialize `drafts/current.yml`.
+Write at least:
+- active path;
+- short goal;
+- current status;
+- start timestamp;
+- timeout;
+- short summary.
+
+8. Create `index.md` inside the activity directory.
+`index.md` must be in Russian and should link to the other files used during the run.
+
+9. If escalation is likely, ask for sanction on the whole planned escalation window before the run starts.
+Prefer one bounded approval phase over incremental requests.
+Do not defer obvious escalation planning to later checkpoints.
+
+10. Create the first run notes inside the activity directory.
+At minimum record:
+- start timestamp;
+- agreed timeout;
+- current goal;
+- planned checkpoints;
+- escalation budget summary;
+- the main hypothesis;
+- sub-hypotheses if already known;
+- known missing inputs.
+
+11. Choose the lowest-risk path first.
+Order of preference:
+- local inspection;
+- safe local recipes;
+- analysis of existing artifacts;
+- sanctioned escalation window only if needed.
+
+12. When escalation is needed, define the window before requesting it.
+The window must include:
+- exact commands;
+- why they are needed;
+- what condition ends the window.
+
+13. During execution, keep the activity directory current.
+Log:
+- hypothesis start;
+- hypothesis completion;
+- missing data;
+- escalation-needed;
+- escalation-result;
+- escalation-blocked;
+- timeout checks.
+Update `drafts/current.yml` whenever run status changes materially.
+
+14. If unplanned escalation becomes necessary during the run, do not request it immediately.
+Instead:
+- log the block;
+- continue with safe/local analysis;
+- collect all remaining non-privileged findings;
+- stop at the next checkpoint or end-of-run synthesis.
+
+15. When sufficient evidence exists, stop exploring and synthesize.
+Summarize:
+- what was validated;
+- what was disproved;
+- what remains unknown;
+- which next move is safest.
+
+## Expected Outputs
+- Updated `drafts/current.yml`
+- A dedicated activity directory under `drafts/`
+- `index.md` in Russian inside that activity directory
+- Any notes, facts, plans, logs, or inventories that help resume context later
+- Links to generated local artifacts such as screenshots, fetched JSON, and derived analysis
+- A concise user-facing summary with findings, blockers, and recommended next step
+
+## Stop Conditions
+Stop exploration and hand back control when:
+- the agreed timeout is reached;
+- the next required action is outside the current escalation window;
+- the remaining uncertainty is mostly product or design uncertainty rather than technical uncertainty;
+- enough evidence exists to recommend a clear next step.
+
+Before handoff:
+- update `drafts/current.yml` to reflect the latest status;
+- ensure `index.md` links to the most important notes and artifacts;
+- leave enough written context for the next session to resume without reconstructing the whole run from memory.

From c82bdd756658194428a0d94a0a24d2477d29d09a Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 22:41:36 +0400
Subject: [PATCH 21/37] refactor: Make recipes were reorganized by workflow

---
 Makefile                             | 235 +--------------------------
 recipes/ci.mk                        |  42 +++++
 recipes/exploration.mk               | 101 ++++++++++++
 recipes/exploration/init.sh          |  69 ++++++++
 recipes/exploration/summarize.sh     |  71 ++++++++
 recipes/research.mk                  |   4 +-
 recipes/tests.mk                     |   7 +
 skills/commit-workflow/SKILL.md      |   2 +
 skills/exploration-workflow/SKILL.md |  16 +-
 9 files changed, 312 insertions(+), 235 deletions(-)
 create mode 100644 recipes/ci.mk
 create mode 100644 recipes/exploration.mk
 create mode 100644 recipes/exploration/init.sh
 create mode 100644 recipes/exploration/summarize.sh

diff --git a/Makefile b/Makefile
index da0694c..1276beb 100644
--- a/Makefile
+++ b/Makefile
@@ -3,22 +3,8 @@
 TARGET_HEADER=@echo -e '===== \e[34m' $@ '\e[0m'
 TARGET_OK=@echo -e '\e[32mOK\e[0m'
 YARN=@docker-compose run --rm node yarn
-YARN_PLAYWRIGHT=@docker-compose run --rm playwright yarn
-PLAYWRIGHT_NODE=@docker-compose run --rm playwright node
-PLAYWRIGHT_NODE_CMD=$(patsubst @%,%,$(PLAYWRIGHT_NODE))
-COVERAGE_PARTS_DIR=coverage/.parts
-COVERAGE_UNIT_DIR=coverage/unit
-COVERAGE_E2E_REACT_DIR=coverage/e2e-react
-COVERAGE_E2E_VUE_DIR=coverage/e2e-vue
-NYC_OUTPUT_DIR=.nyc_output
-M3_FETCH_OUT_DIR?=/tmp/m3-fetch
+PLAYWRIGHT_NODE_CMD=docker-compose run --rm playwright node
 M3_UA?=m3-web-research/1.0
-M3_CAPTURE_OUT_DIR?=drafts/screenshots
-M3_RESEARCH_PACKS_DIR?=recipes/research/packs
-M3_DEFAULT_RESEARCH_PACK?=surfaces
-M3_EXPERIMENT_ROOT?=drafts/experiment
-M3_EXPERIMENT_URLS_DIR?=$(M3_EXPERIMENT_ROOT)/urls
-M3_EXPERIMENT_BOOTSTRAP_PROFILES?=compact medium expanded
 
 .PHONY: up
 up: ## [Dev][docker] Starts storybook
@@ -47,225 +33,12 @@ build: node_modules ## [Build][docker] Creates a dist catalogue with library bui
 	$(TARGET_HEADER)
 	$(YARN) build
 
-include recipes/storybook.mk
 include recipes/lint.mk
 include recipes/tests.mk
+include recipes/storybook.mk
+include recipes/ci.mk
 include recipes/research.mk
-
-.PHONY: ci-actionlint
-ci-actionlint: ## [CI][docker][lint] Lints GitHub Actions workflows locally (actionlint binary or docker image)
-	$(TARGET_HEADER)
-	@if command -v actionlint >/dev/null 2>&1; then \
-		actionlint; \
-	elif command -v docker >/dev/null 2>&1; then \
-		docker run --rm -v "$$(pwd):/repo" -w /repo rhysd/actionlint:latest; \
-	else \
-		echo "actionlint is not installed and docker is unavailable"; \
-		exit 1; \
-	fi
-	$(TARGET_OK)
-
-.PHONY: ci-act-plan
-ci-act-plan: ## [CI][docker] Shows act execution plan for tests workflow without running jobs
-	$(TARGET_HEADER)
-	@if command -v act >/dev/null 2>&1; then \
-		act -P ubuntu-latest=catthehacker/ubuntu:act-latest -n pull_request -W .github/workflows/tests.yml; \
-	elif command -v docker >/dev/null 2>&1; then \
-		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$$(pwd):/repo" -w /repo alpine:3.20 sh -lc "apk add --no-cache curl tar >/dev/null && curl -fsSL https://github.com/nektos/act/releases/download/v0.2.84/act_Linux_x86_64.tar.gz | tar -xz -C /tmp && /tmp/act -P ubuntu-latest=catthehacker/ubuntu:act-latest -n pull_request -W .github/workflows/tests.yml"; \
-	else \
-		echo "act is not installed and docker is unavailable"; \
-		exit 1; \
-	fi
-	$(TARGET_OK)
-
-.PHONY: ci-act-tests
-ci-act-tests: ## [CI][docker][heavy][network] Runs tests workflow locally via act (pr-check, eslint, tests, storybook-tests)
-	$(TARGET_HEADER)
-	@if command -v act >/dev/null 2>&1; then \
-		act -P ubuntu-latest=catthehacker/ubuntu:act-latest pull_request -W .github/workflows/tests.yml -j pr-check -j eslint -j tests -j storybook-tests; \
-	elif command -v docker >/dev/null 2>&1; then \
-		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$$(pwd):/repo" -w /repo alpine:3.20 sh -lc "apk add --no-cache curl tar >/dev/null && curl -fsSL https://github.com/nektos/act/releases/download/v0.2.84/act_Linux_x86_64.tar.gz | tar -xz -C /tmp && /tmp/act -P ubuntu-latest=catthehacker/ubuntu:act-latest pull_request -W .github/workflows/tests.yml -j pr-check -j eslint -j tests -j storybook-tests"; \
-	else \
-		echo "act is not installed and docker is unavailable"; \
-		exit 1; \
-	fi
-	$(TARGET_OK)
-
-.PHONY: ci-check
-ci-check: ci-actionlint ci-act-plan ## [CI][alias] Validates CI workflow config and prints local act plan
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/list
-m3/experiment/list: ## [Experiment][safe] Lists experiment-tagged recipes and their purpose
-	@$(MAKE) --no-print-directory help filter=experiment
-
-.PHONY: m3/experiment/list-escalation
-m3/experiment/list-escalation: ## [Experiment][safe] Lists recipes blocked in no-escalation experiment mode
-	@$(MAKE) --no-print-directory help filter='[escalated]'
-
-.PHONY: m3/experiment/list-safe
-m3/experiment/list-safe: ## [Experiment][safe] Lists local-only recipes safe in no-escalation mode
-	@$(MAKE) --no-print-directory help filter='[safe]'
-
-.PHONY: m3/experiment/init
-m3/experiment/init: ## [Experiment][safe] Creates an experiment run directory with standard subfolders
-	$(TARGET_HEADER)
-	@RUN_DIR="$(if $(run_dir),$(run_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S))"; \
-	mkdir -p "$$RUN_DIR"/screenshots "$$RUN_DIR"/fetch "$$RUN_DIR"/notes; \
-	echo "$$RUN_DIR"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/preflight
-m3/experiment/preflight: ## [Experiment][escalated][docker][network] Validates docker/playwright/network prerequisites for long runs
-	$(TARGET_HEADER)
-	@set -e; \
-	command -v jq >/dev/null; \
-	command -v rg >/dev/null; \
-	docker-compose ps >/dev/null; \
-	$(PLAYWRIGHT_NODE_CMD) -e "console.log('playwright node', process.version)"; \
-	curl -fLsS -A "$(M3_UA)" "https://m3.material.io/" -o /dev/null; \
-	echo "preflight:ok"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/bootstrap
-m3/experiment/bootstrap: ## [Experiment][escalated][docker] One-shot setup: list recipes, init run dir, run preflight checks
-	$(TARGET_HEADER)
-	@$(MAKE) --no-print-directory m3/experiment/list
-	@$(MAKE) --no-print-directory m3/experiment/init $(if $(run_dir),run_dir="$(run_dir)",)
-	@$(MAKE) --no-print-directory m3/experiment/preflight
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/bootstrap/evidence
-# Example:
-#   make m3/experiment/bootstrap/evidence pack=surfaces profiles='compact medium expanded'
-m3/experiment/bootstrap/evidence: ## [Experiment][escalated][docker][network][heavy] One-shot privileged bootstrap: preflight + fetch + multi-profile capture
-	$(TARGET_HEADER)
-	@set -e; \
-	RUN_DIR="$(if $(run_dir),$(run_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S))"; \
-	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
-	PROFILES="$(if $(profiles),$(profiles),$(M3_EXPERIMENT_BOOTSTRAP_PROFILES))"; \
-	$(MAKE) --no-print-directory m3/experiment/init run_dir="$$RUN_DIR"; \
-	$(MAKE) --no-print-directory m3/experiment/preflight; \
-	$(MAKE) --no-print-directory m3/experiment/fetch/pack pack="$$PACK" out_dir="$$RUN_DIR/fetch"; \
-	for profile in $$PROFILES; do \
-		$(MAKE) --no-print-directory m3/experiment/capture/pack \
-			pack="$$PACK" \
-			profile="$$profile" \
-			out_dir="$$RUN_DIR/screenshots/$${profile}-$${PACK}" \
-			wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
-			full_page="$(if $(full_page),$(full_page),true)"; \
-	done; \
-	echo "$$RUN_DIR"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/capture/pack
-# Example:
-#   make m3/experiment/capture/pack pack=surfaces profile=compact
-#   make m3/experiment/capture/pack manifest=recipes/research/packs/surfaces.urls.txt profile=expanded
-m3/experiment/capture/pack: ## [Experiment][escalated][docker][playwright] Captures a research URL pack with viewport profile (compact|medium|expanded)
-	$(TARGET_HEADER)
-	@set -e; \
-	PROFILE="$(if $(profile),$(profile),expanded)"; \
-	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
-	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
-	case "$$PROFILE" in \
-		compact) WIDTH=390; HEIGHT=844 ;; \
-		medium) WIDTH=840; HEIGHT=1080 ;; \
-		expanded) WIDTH=1440; HEIGHT=1024 ;; \
-		*) echo "unsupported profile: $$PROFILE (expected compact|medium|expanded)"; exit 2 ;; \
-	esac; \
-	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/screenshots/$$PROFILE-$${PACK})"; \
-	$(MAKE) --no-print-directory research-capture-batch \
-		manifest="$$MANIFEST" \
-		out_dir="$$OUT_DIR" \
-		width="$$WIDTH" \
-		height="$$HEIGHT" \
-		wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
-		full_page="$(if $(full_page),$(full_page),true)"; \
-	echo "$$OUT_DIR"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/capture/urls-file
-m3/experiment/capture/urls-file: ## [Experiment][escalated][docker][playwright] Captures URLs from a file with viewport profile (compact|medium|expanded)
-	$(TARGET_HEADER)
-	@if [ -z "$(in)" ]; then echo "usage: make m3/experiment/capture/urls-file in=$(M3_EXPERIMENT_URLS_DIR)/<pack>.txt [profile=compact|medium|expanded] [out_dir=...]"; exit 2; fi
-	@set -e; \
-	PROFILE="$(if $(profile),$(profile),expanded)"; \
-	case "$$PROFILE" in \
-		compact) WIDTH=390; HEIGHT=844 ;; \
-		medium) WIDTH=840; HEIGHT=1080 ;; \
-		expanded) WIDTH=1440; HEIGHT=1024 ;; \
-		*) echo "unsupported profile: $$PROFILE (expected compact|medium|expanded)"; exit 2 ;; \
-	esac; \
-	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/screenshots/$$PROFILE)"; \
-	$(MAKE) --no-print-directory research-capture-batch \
-		in="$(in)" \
-		out_dir="$$OUT_DIR" \
-		width="$$WIDTH" \
-		height="$$HEIGHT" \
-		wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
-		full_page="$(if $(full_page),$(full_page),true)" \
-		$(if $(wait_selector),wait_selector="$(wait_selector)",); \
-	echo "$$OUT_DIR"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/fetch/pack
-# Example:
-#   make m3/experiment/fetch/pack pack=surfaces out_dir=drafts/experiment/run-1/fetch
-#   make m3/experiment/fetch/pack manifest=recipes/research/packs/surfaces.page-data.tsv
-m3/experiment/fetch/pack: ## [Experiment][escalated][network][fetch] Fetches a research page-data pack into an experiment run directory
-	$(TARGET_HEADER)
-	@set -e; \
-	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
-	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.page-data.tsv)"; \
-	OUT_DIR="$(if $(out_dir),$(out_dir),$(M3_EXPERIMENT_ROOT)/runs/$$(date +%Y%m%d-%H%M%S)/fetch)"; \
-	mkdir -p "$$OUT_DIR"; \
-	$(MAKE) --no-print-directory research-fetch-batch format=json manifest="$$MANIFEST" out_dir="$$OUT_DIR"; \
-	echo "$$OUT_DIR"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/urls-template
-# Example:
-#   make m3/experiment/urls-template pack=surfaces
-#   make m3/experiment/urls-template manifest=recipes/research/packs/surfaces.urls.txt out=drafts/experiment/urls/custom.txt
-m3/experiment/urls-template: ## [Experiment][safe] Creates a starter URL list for batch captures from a research pack
-	$(TARGET_HEADER)
-	@set -e; \
-	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
-	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
-	OUT="$(if $(out),$(out),$(M3_EXPERIMENT_URLS_DIR)/$${PACK}.txt)"; \
-	mkdir -p "$$(dirname "$$OUT")"; \
-	cp "$$MANIFEST" "$$OUT"; \
-	echo "$$OUT"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/manifest
-m3/experiment/manifest: ## [Experiment][safe] Prints recommended order for a long experiment run
-	$(TARGET_HEADER)
-	@printf '%s\n' \
-		"1) make m3/experiment/list && make m3/experiment/list-escalation" \
-		"2) (if sanctioned) make m3/experiment/bootstrap/evidence [pack=surfaces] [run_dir=...] [profiles='compact medium expanded']" \
-		"3) switch to no-escalation mode and keep only local analysis" \
-		"4) make m3/experiment/analyze/local-summary run_dir=..." \
-		"5) continue milestones/decisions based on local artifacts"
-	$(TARGET_OK)
-
-.PHONY: m3/experiment/analyze/local-summary
-m3/experiment/analyze/local-summary: ## [Experiment][safe] Prints local artifact summary for a completed/ongoing run (no escalation)
-	$(TARGET_HEADER)
-	@if [ -z "$(run_dir)" ]; then echo "usage: make m3/experiment/analyze/local-summary run_dir=drafts/experiment/runs/<id>"; exit 2; fi
-	@set -e; \
-	FETCH_DIR="$(run_dir)/fetch"; \
-	SCREEN_DIR="$(run_dir)/screenshots"; \
-	FETCH_COUNT=$$(find "$$FETCH_DIR" -maxdepth 1 -type f -name '*.json' 2>/dev/null | wc -l); \
-	echo "fetch_json=$$FETCH_COUNT"; \
-	find "$$SCREEN_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort | while IFS= read -r dir; do \
-		name="$$(basename "$$dir")"; \
-		META_COUNT=$$(find "$$dir" -maxdepth 1 -type f -name '*.meta.json' 2>/dev/null | wc -l); \
-		PNG_COUNT=$$(find "$$dir" -maxdepth 1 -type f -name '*.png' 2>/dev/null | wc -l); \
-		echo "$$name: png=$$PNG_COUNT meta=$$META_COUNT"; \
-	done
-	$(TARGET_OK)
+include recipes/exploration.mk
 
 .PHONY: help
 help: ## [General] Shows grouped command help
diff --git a/recipes/ci.mk b/recipes/ci.mk
new file mode 100644
index 0000000..30dd1cf
--- /dev/null
+++ b/recipes/ci.mk
@@ -0,0 +1,42 @@
+.PHONY: ci-actionlint
+ci-actionlint: ## [CI][docker][lint] Lints GitHub Actions workflows locally (actionlint binary or docker image)
+	$(TARGET_HEADER)
+	@if command -v actionlint >/dev/null 2>&1; then \
+		actionlint; \
+	elif command -v docker >/dev/null 2>&1; then \
+		docker run --rm -v "$$(pwd):/repo" -w /repo rhysd/actionlint:latest; \
+	else \
+		echo "actionlint is not installed and docker is unavailable"; \
+		exit 1; \
+	fi
+	$(TARGET_OK)
+
+.PHONY: ci-act-plan
+ci-act-plan: ## [CI][docker] Shows act execution plan for tests workflow without running jobs
+	$(TARGET_HEADER)
+	@if command -v act >/dev/null 2>&1; then \
+		act -P ubuntu-latest=catthehacker/ubuntu:act-latest -n pull_request -W .github/workflows/tests.yml; \
+	elif command -v docker >/dev/null 2>&1; then \
+		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$$(pwd):/repo" -w /repo alpine:3.20 sh -lc "apk add --no-cache curl tar >/dev/null && curl -fsSL https://github.com/nektos/act/releases/download/v0.2.84/act_Linux_x86_64.tar.gz | tar -xz -C /tmp && /tmp/act -P ubuntu-latest=catthehacker/ubuntu:act-latest -n pull_request -W .github/workflows/tests.yml"; \
+	else \
+		echo "act is not installed and docker is unavailable"; \
+		exit 1; \
+	fi
+	$(TARGET_OK)
+
+.PHONY: ci-act-tests
+ci-act-tests: ## [CI][docker][heavy][network] Runs tests workflow locally via act (pr-check, eslint, tests, storybook-tests)
+	$(TARGET_HEADER)
+	@if command -v act >/dev/null 2>&1; then \
+		act -P ubuntu-latest=catthehacker/ubuntu:act-latest pull_request -W .github/workflows/tests.yml -j pr-check -j eslint -j tests -j storybook-tests; \
+	elif command -v docker >/dev/null 2>&1; then \
+		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$$(pwd):/repo" -w /repo alpine:3.20 sh -lc "apk add --no-cache curl tar >/dev/null && curl -fsSL https://github.com/nektos/act/releases/download/v0.2.84/act_Linux_x86_64.tar.gz | tar -xz -C /tmp && /tmp/act -P ubuntu-latest=catthehacker/ubuntu:act-latest pull_request -W .github/workflows/tests.yml -j pr-check -j eslint -j tests -j storybook-tests"; \
+	else \
+		echo "act is not installed and docker is unavailable"; \
+		exit 1; \
+	fi
+	$(TARGET_OK)
+
+.PHONY: ci-check
+ci-check: ci-actionlint ci-act-plan ## [CI][alias] Validates CI workflow config and prints local act plan
+	$(TARGET_OK)
diff --git a/recipes/exploration.mk b/recipes/exploration.mk
new file mode 100644
index 0000000..fd9a9b0
--- /dev/null
+++ b/recipes/exploration.mk
@@ -0,0 +1,101 @@
+include recipes/common.mk
+
+M3_RESEARCH_PACKS_DIR?=recipes/research/packs
+M3_DEFAULT_RESEARCH_PACK?=surfaces
+EXPLORATION_ACTIVITIES_ROOT?=drafts/explorations
+EXPLORATION_INPUTS_ROOT?=$(EXPLORATION_ACTIVITIES_ROOT)/inputs
+EXPLORATION_BOOTSTRAP_PROFILES?=compact medium expanded
+
+.PHONY: exploration-init
+exploration-init: ## [Exploration][safe] Creates an activity directory skeleton from exploration-workflow without starting exploration
+	$(TARGET_HEADER)
+	@EXPLORATION_ACTIVITIES_ROOT='$(EXPLORATION_ACTIVITIES_ROOT)' sh ./recipes/exploration/init.sh \
+		$(if $(slug),--slug '$(slug)',) \
+		$(if $(activity_dir),--activity-dir '$(activity_dir)',)
+	$(TARGET_OK)
+
+.PHONY: exploration-preflight-local
+exploration-preflight-local: ## [Exploration][safe] Validates required local CLI tools for exploration support
+	$(TARGET_HEADER)
+	@command -v jq >/dev/null
+	@command -v rg >/dev/null
+	@echo "preflight-local:ok"
+	$(TARGET_OK)
+
+.PHONY: exploration-preflight-docker
+exploration-preflight-docker: ## [Exploration][escalated][docker] Validates docker-compose and Playwright runtime prerequisites
+	$(TARGET_HEADER)
+	@set -e; \
+	docker-compose ps >/dev/null; \
+	$(PLAYWRIGHT_NODE_CMD) -e "console.log('playwright node', process.version)"; \
+	echo "preflight-docker:ok"
+	$(TARGET_OK)
+
+.PHONY: exploration-preflight-network
+exploration-preflight-network: ## [Exploration][escalated][network] Validates remote network access required for evidence collection
+	$(TARGET_HEADER)
+	@set -e; \
+	curl -fLsS -A "$(M3_UA)" "https://m3.material.io/" -o /dev/null; \
+	echo "preflight-network:ok"
+	$(TARGET_OK)
+
+.PHONY: exploration-bootstrap
+# Example:
+#   make exploration-bootstrap activity_dir=drafts/explorations/20260307-2015-surface-layer pack=surfaces profiles='compact medium expanded'
+exploration-bootstrap: ## [Exploration][escalated][docker][network][heavy] Runs bounded evidence bootstrap into an initialized activity directory
+	$(TARGET_HEADER)
+	@if [ -z "$(activity_dir)" ] && [ -z "$(run_dir)" ]; then echo "usage: make exploration-bootstrap activity_dir=drafts/explorations/<id> [pack=surfaces]"; exit 2; fi
+	@set -e; \
+	ACTIVITY_DIR="$(if $(activity_dir),$(activity_dir),$(run_dir))"; \
+	if [ ! -f "$$ACTIVITY_DIR/index.md" ]; then \
+		echo "activity_dir is not initialized: $$ACTIVITY_DIR (run make exploration-init first)"; \
+		exit 2; \
+	fi; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	PROFILES="$(if $(profiles),$(profiles),$(EXPLORATION_BOOTSTRAP_PROFILES))"; \
+	FETCH_MANIFEST="$(if $(fetch_manifest),$(fetch_manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.page-data.tsv)"; \
+	CAPTURE_MANIFEST="$(if $(capture_manifest),$(capture_manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
+	$(MAKE) --no-print-directory exploration-preflight-local; \
+	$(MAKE) --no-print-directory exploration-preflight-docker; \
+	$(MAKE) --no-print-directory exploration-preflight-network; \
+	$(MAKE) --no-print-directory research-fetch-batch format=json manifest="$$FETCH_MANIFEST" out_dir="$$ACTIVITY_DIR/artifacts/fetch"; \
+	for profile in $$PROFILES; do \
+		case "$$profile" in \
+			compact) WIDTH=390; HEIGHT=844 ;; \
+			medium) WIDTH=840; HEIGHT=1080 ;; \
+			expanded) WIDTH=1440; HEIGHT=1024 ;; \
+			*) echo "unsupported profile: $$profile (expected compact|medium|expanded)"; exit 2 ;; \
+		esac; \
+		$(MAKE) --no-print-directory research-capture-batch \
+			manifest="$$CAPTURE_MANIFEST" \
+			out_dir="$$ACTIVITY_DIR/artifacts/screenshots/$${profile}-$${PACK}" \
+			width="$$WIDTH" \
+			height="$$HEIGHT" \
+			wait_ms="$(if $(wait_ms),$(wait_ms),1200)" \
+			full_page="$(if $(full_page),$(full_page),true)" \
+			$(if $(wait_selector),wait_selector="$(wait_selector)",); \
+	done; \
+	echo "$$ACTIVITY_DIR"
+	$(TARGET_OK)
+
+.PHONY: exploration-prepare-batch
+# Example:
+#   make exploration-prepare-batch activity_dir=drafts/explorations/20260307-2015-surface-layer pack=surfaces
+#   make exploration-prepare-batch manifest=recipes/research/packs/surfaces.urls.txt out=drafts/explorations/inputs/custom.urls.txt
+exploration-prepare-batch: ## [Exploration][safe] Prepares a URL batch input file for research capture recipes from a research pack
+	$(TARGET_HEADER)
+	@set -e; \
+	PACK="$(if $(pack),$(pack),$(M3_DEFAULT_RESEARCH_PACK))"; \
+	MANIFEST="$(if $(manifest),$(manifest),$(M3_RESEARCH_PACKS_DIR)/$${PACK}.urls.txt)"; \
+	OUT="$(if $(out),$(out),$(if $(activity_dir),$(activity_dir)/inputs/$${PACK}.urls.txt,$(EXPLORATION_INPUTS_ROOT)/$${PACK}.urls.txt))"; \
+	mkdir -p "$$(dirname "$$OUT")"; \
+	cp "$$MANIFEST" "$$OUT"; \
+	echo "$$OUT"
+	$(TARGET_OK)
+
+.PHONY: exploration-summarize
+exploration-summarize: ## [Exploration][safe] Writes and prints a local artifact summary for an exploration activity directory
+	$(TARGET_HEADER)
+	@ACTIVITY_DIR='$(if $(activity_dir),$(activity_dir),$(run_dir))' sh ./recipes/exploration/summarize.sh \
+		$(if $(out),--out '$(out)',)
+	$(TARGET_OK)
diff --git a/recipes/exploration/init.sh b/recipes/exploration/init.sh
new file mode 100644
index 0000000..be40b2c
--- /dev/null
+++ b/recipes/exploration/init.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env sh
+
+set -eu
+
+slug_raw="activity"
+activity_dir=""
+activities_root="${EXPLORATION_ACTIVITIES_ROOT:-drafts/explorations}"
+
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+		--slug)
+			shift
+			slug_raw="${1:-}"
+			;;
+		--activity-dir)
+			shift
+			activity_dir="${1:-}"
+			;;
+		*)
+			echo "usage: $0 [--slug <slug>] [--activity-dir <dir>]" >&2
+			exit 2
+			;;
+	esac
+	shift
+done
+
+slug="$(printf '%s' "$slug_raw" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g' | sed 's/--*/-/g' | sed 's/^-//; s/-$//')"
+
+if [ -z "$slug" ]; then
+	slug="activity"
+fi
+
+if [ -z "$activity_dir" ]; then
+	activity_dir="$activities_root/$(date +%Y%m%d-%H%M)-$slug"
+fi
+
+mkdir -p \
+	"$activity_dir" \
+	"$activity_dir/inputs" \
+	"$activity_dir/artifacts/fetch" \
+	"$activity_dir/artifacts/screenshots"
+
+for file in plan.md notes.md decisions.md artifacts.md summary.md; do
+	if [ ! -f "$activity_dir/$file" ]; then
+		: > "$activity_dir/$file"
+	fi
+done
+
+if [ ! -f "$activity_dir/index.md" ]; then
+	cat > "$activity_dir/index.md" <<EOF
+# Exploration: $slug
+
+## Задача
+- Заполнить перед фактическим стартом exploration.
+
+## Статус
+- Состояние: planned
+- Примечание: каталог подготовлен через \`make exploration-init\`, exploration еще не запущен.
+
+## Ссылки
+- [План](./plan.md)
+- [Лог наблюдений](./notes.md)
+- [Решения](./decisions.md)
+- [Артефакты](./artifacts.md)
+- [Сводка](./summary.md)
+EOF
+fi
+
+printf '%s\n' "$activity_dir"
diff --git a/recipes/exploration/summarize.sh b/recipes/exploration/summarize.sh
new file mode 100644
index 0000000..0527ac6
--- /dev/null
+++ b/recipes/exploration/summarize.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env sh
+
+set -eu
+
+activity_dir="${ACTIVITY_DIR:-}"
+out=""
+
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+		--out)
+			shift
+			out="${1:-}"
+			;;
+		*)
+			echo "usage: ACTIVITY_DIR=<dir> $0 [--out <file>]" >&2
+			exit 2
+			;;
+	esac
+	shift
+done
+
+if [ -z "$activity_dir" ]; then
+	echo "usage: make exploration-summarize activity_dir=drafts/explorations/<id> [out=...]" >&2
+	exit 2
+fi
+
+if [ -z "$out" ]; then
+	out="$activity_dir/summary.md"
+fi
+
+fetch_dir="$activity_dir/artifacts/fetch"
+screens_dir="$activity_dir/artifacts/screenshots"
+
+if [ ! -d "$fetch_dir" ] && [ -d "$activity_dir/fetch" ]; then
+	fetch_dir="$activity_dir/fetch"
+fi
+
+if [ ! -d "$screens_dir" ] && [ -d "$activity_dir/screenshots" ]; then
+	screens_dir="$activity_dir/screenshots"
+fi
+
+mkdir -p "$(dirname "$out")"
+
+fetch_count="$(find "$fetch_dir" -maxdepth 1 -type f -name '*.json' 2>/dev/null | wc -l | tr -d ' ')"
+
+{
+	printf '# Exploration Summary\n\n'
+	printf -- '- Activity dir: `%s`\n' "$activity_dir"
+	printf -- '- Fetch JSON: %s\n' "$fetch_count"
+	printf '\n## Screenshot Sets\n'
+
+	found=0
+	for dir in "$screens_dir"/*; do
+		if [ ! -d "$dir" ]; then
+			continue
+		fi
+
+		found=1
+		name="$(basename "$dir")"
+		meta_count="$(find "$dir" -maxdepth 1 -type f -name '*.meta.json' 2>/dev/null | wc -l | tr -d ' ')"
+		png_count="$(find "$dir" -maxdepth 1 -type f -name '*.png' 2>/dev/null | wc -l | tr -d ' ')"
+		printf -- '- `%s`: png=%s meta=%s\n' "$name" "$png_count" "$meta_count"
+	done
+
+	if [ "$found" -eq 0 ]; then
+		printf -- '- No screenshot directories found.\n'
+	fi
+} > "$out"
+
+cat "$out"
+printf '\nsummary_file=%s\n' "$out"
diff --git a/recipes/research.mk b/recipes/research.mk
index 405ad46..b05676b 100644
--- a/recipes/research.mk
+++ b/recipes/research.mk
@@ -1,3 +1,5 @@
+M3_FETCH_OUT_DIR?=/tmp/m3-fetch
+
 # Example:
 #   make research-fetch url='https://m3.material.io/'
 #   make research-fetch format=json collection=ComponentsM3 document=5634981699387392
@@ -71,7 +73,7 @@ research-capture: ## [Research][docker][playwright][capture] Captures screenshot
 
 # Example:
 #   make research-capture-batch manifest=recipes/research/packs/surfaces.urls.txt out_dir=drafts/screenshots/surfaces
-#   make research-capture-batch in=drafts/experiment/urls/surfaces.txt out_dir=drafts/screenshots/custom
+#   make research-capture-batch in=drafts/explorations/20260307-2015-surface-layer/inputs/surfaces.urls.txt out_dir=drafts/screenshots/custom
 # Input format:
 #   One URL per line; empty lines and #comments are ignored.
 .PHONY: research-capture-batch
diff --git a/recipes/tests.mk b/recipes/tests.mk
index 7c36431..f8db30a 100644
--- a/recipes/tests.mk
+++ b/recipes/tests.mk
@@ -1,5 +1,12 @@
 include recipes/common.mk
 
+YARN_PLAYWRIGHT=@docker-compose run --rm playwright yarn
+COVERAGE_PARTS_DIR=coverage/.parts
+COVERAGE_UNIT_DIR=coverage/unit
+COVERAGE_E2E_REACT_DIR=coverage/e2e-react
+COVERAGE_E2E_VUE_DIR=coverage/e2e-vue
+NYC_OUTPUT_DIR=.nyc_output
+
 .PHONY: test-smoke
 test-smoke: node_modules ## [Tests][docker][smoke] Runs smoke tests for all UI workspaces
 	$(TARGET_HEADER)
diff --git a/skills/commit-workflow/SKILL.md b/skills/commit-workflow/SKILL.md
index 358dd7b..baae500 100644
--- a/skills/commit-workflow/SKILL.md
+++ b/skills/commit-workflow/SKILL.md
@@ -5,6 +5,8 @@ description: Use this skill when creating git commits in this repository. It sta
 
 # Commit Workflow
 
+Reread this skill immediately before preparing or creating any commit in this repository.
+
 ## When To Use
 Use this skill when the user asks to:
 - create one or more commits;
diff --git a/skills/exploration-workflow/SKILL.md b/skills/exploration-workflow/SKILL.md
index f55ee48..ce58072 100644
--- a/skills/exploration-workflow/SKILL.md
+++ b/skills/exploration-workflow/SKILL.md
@@ -138,11 +138,19 @@ Minimal example:
 
 ## Repository Conventions
 - Prefer repository exploration helpers where they exist.
-  At the moment, this includes `m3/experiment/*` Makefile targets.
+  At the moment, this includes `exploration-init`, `exploration-preflight-*`,
+  `exploration-prepare-batch`, `exploration-bootstrap`, and
+  `exploration-summarize`.
+- Use `make exploration-init slug=<short-slug>` as the quickest way to prepare
+  the initial activity directory skeleton under `drafts/explorations/`.
+  This helper only creates directories and draft files; it does not start
+  exploration mode and must not replace the explicit start sequence from this skill.
 - Direct `research-*` commands are allowed only when they are listed in the current escalation window.
 - Prefer one-shot privileged bootstrap:
-  `make m3/experiment/bootstrap/evidence`
-- Treat literal `m3/experiment/*` target names as the current repository command interface for exploration runs until the namespace is renamed in-repo.
+  `make exploration-bootstrap activity_dir=drafts/explorations/<id>`
+- After the escalation window is closed, prefer local synthesis via:
+  `make exploration-summarize activity_dir=drafts/explorations/<id>`
+- Treat `exploration-*` target names as the current repository command interface for exploration support flows.
 - During exploration-driven component development, do not modify current production
   components in `src/components` unless explicitly requested.
 - For agent-driven exploratory components, create and use `src/experimental`
@@ -185,6 +193,8 @@ Examples:
 Use a clear distinct name, for example:
 - `drafts/explorations/20260307-2015-surface-layer/`
 - `drafts/explorations/20260307-2015-dialog-parity/`
+To scaffold this quickly before filling in the run state, you may use:
+- `make exploration-init slug=surface-layer`
 
 7. Initialize `drafts/current.yml`.
 Write at least:

From 8b383390cb5e27d7ff9fa8e9068c9e970fcc8eea Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sat, 7 Mar 2026 23:19:28 +0400
Subject: [PATCH 22/37] refactor: Surface theme styles were simplified

---
 .../stylesheets/components/surface/index.scss | 70 +++++++------------
 m3-react/src/components/surface/M3Surface.tsx | 11 ++-
 m3-react/tests/M3Surface.test.tsx             |  6 +-
 m3-vue/src/components/surface/M3Surface.vue   | 10 ++-
 m3-vue/storybook/components/M3RichTooltip.mdx |  2 +-
 m3-vue/storybook/components/M3Switch.mdx      |  2 +-
 m3-vue/storybook/utils/mdxCodeBlock.ts        |  2 +-
 m3-vue/tests/M3Surface.e2e.ts                 |  5 +-
 m3-vue/tests/M3Surface.test.ts                |  6 +-
 9 files changed, 55 insertions(+), 59 deletions(-)

diff --git a/m3-foundation/assets/stylesheets/components/surface/index.scss b/m3-foundation/assets/stylesheets/components/surface/index.scss
index 03560c7..2eb3c71 100644
--- a/m3-foundation/assets/stylesheets/components/surface/index.scss
+++ b/m3-foundation/assets/stylesheets/components/surface/index.scss
@@ -1,27 +1,25 @@
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/palette' as palette;
-@use '../../themes/dark' as dark;
 @use '../../themes/light' as light;
 
+$m3-surface-color: var(--m3-sys-surface, #{light.$m3-sys-light-surface});
+$m3-surface-dim-color: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+$m3-surface-bright-color: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+$m3-surface-container-lowest-color: var(--m3-sys-surface, #{palette.$m3-palette-neutral-100});
+$m3-surface-container-low-color: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
+$m3-surface-container-color: var(--m3-sys-surface-container, #{light.$m3-sys-light-surface-container});
+$m3-surface-container-high-color: var(--m3-sys-surface-container-high, #{light.$m3-sys-light-surface-container-high});
+$m3-surface-container-highest-color: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
+$m3-surface-on-surface-color: var(--m3-sys-on-surface, #{light.$m3-sys-light-on-surface});
+
 .m3-surface {
-  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{light.$m3-sys-light-surface});
-  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
-  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
-  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{palette.$m3-palette-neutral-100});
-  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{light.$m3-sys-light-surface-container-low});
-  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{light.$m3-sys-light-surface-container});
-  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{light.$m3-sys-light-surface-container-high});
-  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{light.$m3-sys-light-surface-container-highest});
-  --m3-surface-elevation-1: var(--m3-elevation-1, #{light.$m3-elevation-light-1});
-  --m3-surface-elevation-2: var(--m3-elevation-2, #{light.$m3-elevation-light-2});
-  --m3-surface-elevation-3: var(--m3-elevation-3, #{light.$m3-elevation-light-3});
-  --m3-surface-elevation-4: var(--m3-elevation-4, #{light.$m3-elevation-light-4});
-  --m3-surface-elevation-5: var(--m3-elevation-5, #{light.$m3-elevation-light-5});
   --m3-surface-radius-transition-duration: #{m3-motion.duration('medium2')};
 
   display: block;
   isolation: isolate;
   box-sizing: border-box;
+  background-color: $m3-surface-color;
+  color: $m3-surface-on-surface-color;
   transition:
     border-top-left-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')},
     border-top-right-radius var(--m3-surface-radius-transition-duration) #{m3-motion.easing('standard')},
@@ -33,24 +31,20 @@
     max-height: 100vh;
   }
 
-  &_role-surface {
-    background-color: var(--m3-surface-role-surface-bg);
-  }
-
-  &_role-surface-dim               { background-color: var(--m3-surface-role-surface-dim-bg); }
-  &_role-surface-bright            { background-color: var(--m3-surface-role-surface-bright-bg); }
-  &_role-surface-container-lowest  { background-color: var(--m3-surface-role-container-lowest-bg); }
-  &_role-surface-container-low     { background-color: var(--m3-surface-role-container-low-bg); }
-  &_role-surface-container         { background-color: var(--m3-surface-role-container-bg); }
-  &_role-surface-container-high    { background-color: var(--m3-surface-role-container-high-bg); }
-  &_role-surface-container-highest { background-color: var(--m3-surface-role-container-highest-bg); }
+  &_dim               { background-color: $m3-surface-dim-color; }
+  &_bright            { background-color: $m3-surface-bright-color; }
+  &_container-lowest  { background-color: $m3-surface-container-lowest-color; }
+  &_container-low     { background-color: $m3-surface-container-low-color; }
+  &_container         { background-color: $m3-surface-container-color; }
+  &_container-high    { background-color: $m3-surface-container-high-color; }
+  &_container-highest { background-color: $m3-surface-container-highest-color; }
 
   &_elevation-0 { box-shadow: none; }
-  &_elevation-1 { box-shadow: var(--m3-surface-elevation-1); }
-  &_elevation-2 { box-shadow: var(--m3-surface-elevation-2); }
-  &_elevation-3 { box-shadow: var(--m3-surface-elevation-3); }
-  &_elevation-4 { box-shadow: var(--m3-surface-elevation-4); }
-  &_elevation-5 { box-shadow: var(--m3-surface-elevation-5); }
+  &_elevation-1 { box-shadow: var(--m3-elevation-1, #{light.$m3-elevation-light-1}); }
+  &_elevation-2 { box-shadow: var(--m3-elevation-2, #{light.$m3-elevation-light-2}); }
+  &_elevation-3 { box-shadow: var(--m3-elevation-3, #{light.$m3-elevation-light-3}); }
+  &_elevation-4 { box-shadow: var(--m3-elevation-4, #{light.$m3-elevation-light-4}); }
+  &_elevation-5 { box-shadow: var(--m3-elevation-5, #{light.$m3-elevation-light-5}); }
 
   &__scrim {
     position: fixed;
@@ -58,19 +52,3 @@
     background: color-mix(in srgb, var(--m3-sys-shadow, #{palette.$m3-palette-neutral-0}) 38%, transparent);
   }
 }
-
-html.m3-theme-dark .m3-surface {
-  --m3-surface-role-surface-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
-  --m3-surface-role-surface-dim-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
-  --m3-surface-role-surface-bright-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
-  --m3-surface-role-container-lowest-bg: var(--m3-sys-surface, #{dark.$m3-sys-dark-surface});
-  --m3-surface-role-container-low-bg: var(--m3-sys-surface-container-low, #{dark.$m3-sys-dark-surface-container-low});
-  --m3-surface-role-container-bg: var(--m3-sys-surface-container, #{dark.$m3-sys-dark-surface-container});
-  --m3-surface-role-container-high-bg: var(--m3-sys-surface-container-high, #{dark.$m3-sys-dark-surface-container-high});
-  --m3-surface-role-container-highest-bg: var(--m3-sys-surface-container-highest, #{dark.$m3-sys-dark-surface-container-highest});
-  --m3-surface-elevation-1: var(--m3-elevation-1, #{dark.$m3-elevation-dark-1});
-  --m3-surface-elevation-2: var(--m3-elevation-2, #{dark.$m3-elevation-dark-2});
-  --m3-surface-elevation-3: var(--m3-elevation-3, #{dark.$m3-elevation-dark-3});
-  --m3-surface-elevation-4: var(--m3-elevation-4, #{dark.$m3-elevation-dark-4});
-  --m3-surface-elevation-5: var(--m3-elevation-5, #{dark.$m3-elevation-dark-5});
-}
diff --git a/m3-react/src/components/surface/M3Surface.tsx b/m3-react/src/components/surface/M3Surface.tsx
index 397e3fb..2342553 100644
--- a/m3-react/src/components/surface/M3Surface.tsx
+++ b/m3-react/src/components/surface/M3Surface.tsx
@@ -111,6 +111,14 @@ const getResolvedVariant = (variant: SurfaceVariant, elevation: number): Exclude
   }
 }
 
+const getVariantClassName = (variant: Exclude<SurfaceVariant, 'auto'>): string | null => {
+  if (variant === 'surface') {
+    return null
+  }
+
+  return `m3-surface_${variant.replace(/^surface-/, '')}`
+}
+
 const M3Surface: FC<M3SurfaceProps> = ({
   id,
   tag = 'section',
@@ -152,6 +160,7 @@ const M3Surface: FC<M3SurfaceProps> = ({
   const _id = useId(id, 'm3-surface')
   const isModal = mode === 'modal'
   const resolvedVariant = getResolvedVariant(variant, elevation)
+  const variantClassName = getVariantClassName(resolvedVariant)
   const SurfaceTag = tag
 
   const resolvedSizeStyle: CSSProperties = {
@@ -206,7 +215,7 @@ const M3Surface: FC<M3SurfaceProps> = ({
   const surfaceClassName = toClassName([className, {
     'm3-surface': true,
     'm3-surface_modal': isModal,
-    [`m3-surface_role-${resolvedVariant}`]: true,
+    [variantClassName || '']: Boolean(variantClassName),
     [`m3-surface_anchor-${anchor}`]: true,
     [`m3-surface_elevation-${elevation}`]: true,
   }])
diff --git a/m3-react/tests/M3Surface.test.tsx b/m3-react/tests/M3Surface.test.tsx
index 7307efc..f888596 100644
--- a/m3-react/tests/M3Surface.test.tsx
+++ b/m3-react/tests/M3Surface.test.tsx
@@ -98,7 +98,7 @@ describe('m3-react/surface', () => {
 
     let surface = screen.getByRole('region')
 
-    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
 
     rerender(
       <M3Surface elevation={3} variant="surface-bright" />
@@ -106,7 +106,7 @@ describe('m3-react/surface', () => {
 
     surface = screen.getByRole('region')
 
-    expect(surface.classList.contains('m3-surface_role-surface-bright')).toBe(true)
-    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(false)
+    expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
   })
 })
diff --git a/m3-vue/src/components/surface/M3Surface.vue b/m3-vue/src/components/surface/M3Surface.vue
index b04f651..02c4ca4 100644
--- a/m3-vue/src/components/surface/M3Surface.vue
+++ b/m3-vue/src/components/surface/M3Surface.vue
@@ -279,6 +279,14 @@ const resolvedVariant = computed<Exclude<SurfaceVariant, 'auto'>>(() => {
   }
 })
 
+const variantClassName = computed(() => {
+  if (resolvedVariant.value === 'surface') {
+    return null
+  }
+
+  return `m3-surface_${resolvedVariant.value.replace(/^surface-/, '')}`
+})
+
 const resolvedSizeStyle = computed(() => {
   const width = isDefined(props.width)
     ? toLength(props.width, 'auto')
@@ -359,7 +367,7 @@ const surfaceAttrs = computed(() => {
 const surfaceClass = computed(() => ({
   'm3-surface': true,
   'm3-surface_modal': isModal.value,
-  [`m3-surface_role-${resolvedVariant.value}`]: true,
+  [variantClassName.value || '']: Boolean(variantClassName.value),
   [`m3-surface_anchor-${props.anchor}`]: true,
   [`m3-surface_elevation-${props.elevation}`]: true,
 }))
diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index 509192b..4873fe4 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -15,7 +15,7 @@ Rich tooltips provide contextual, supplementary information near a trigger eleme
 
 <Unstyled>
   <div
-    className="m3-surface m3-surface_role-surface-container m3-surface_elevation-0 my-4"
+    className="m3-surface m3-surface_container m3-surface_elevation-0 my-4"
     style={{ maxWidth: '360px', padding: '32px', borderRadius: '16px', color: 'var(--m3-sys-on-surface)' }}
   >
     <Inline is={DeleteTooltip} />
diff --git a/m3-vue/storybook/components/M3Switch.mdx b/m3-vue/storybook/components/M3Switch.mdx
index 4c08932..f19d706 100644
--- a/m3-vue/storybook/components/M3Switch.mdx
+++ b/m3-vue/storybook/components/M3Switch.mdx
@@ -28,7 +28,7 @@ import * as M3SwitchStories from './M3Switch.stories'
 
 <Unstyled>
   <div
-    className="m3-surface m3-surface_role-surface-container m3-surface_elevation-0 my-4"
+    className="m3-surface m3-surface_container m3-surface_elevation-0 my-4"
     style={{ maxWidth: '360px', padding: '32px', borderRadius: '16px', color: 'var(--m3-sys-on-surface)' }}
   >
     <Inline is={FieldSwitch} label="Wi-Fi" class="mb-4" />
diff --git a/m3-vue/storybook/utils/mdxCodeBlock.ts b/m3-vue/storybook/utils/mdxCodeBlock.ts
index 86d2211..779b316 100644
--- a/m3-vue/storybook/utils/mdxCodeBlock.ts
+++ b/m3-vue/storybook/utils/mdxCodeBlock.ts
@@ -53,7 +53,7 @@ const COPY_SUCCESS_TEXT = 'Copied'
 const COPY_TEXT = 'Copy code'
 const LANGUAGE_BADGE_CLASS = 'm3-docs-code-language'
 const LANGUAGE_PREFIXES = ['language-', 'lang-']
-const PANEL_CLASS = 'm3-surface m3-surface_role-surface-container m3-surface_elevation-0'
+const PANEL_CLASS = 'm3-surface m3-surface_container m3-surface_elevation-0'
 const NON_SPECIFIC_LANGUAGES = new Set(['plain', 'plaintext', 'text', 'txt'])
 
 const HIGHLIGHT_LANGUAGE_ALIASES: Record<string, string> = {
diff --git a/m3-vue/tests/M3Surface.e2e.ts b/m3-vue/tests/M3Surface.e2e.ts
index 3745a74..d423fd9 100644
--- a/m3-vue/tests/M3Surface.e2e.ts
+++ b/m3-vue/tests/M3Surface.e2e.ts
@@ -114,7 +114,7 @@ describe('m3-vue/surface e2e', () => {
     staticRoles.forEach((role) => {
       const block = document.querySelector(`[data-testid="static-role-${role}"]`) as HTMLElement | null
       expect(block).not.toBeNull()
-      expect(block?.classList.contains(`m3-surface_role-${role}`)).toBe(true)
+      expect(block?.classList.contains(`m3-surface_${role.replace(/^surface-/, '')}`)).toBe(true)
     })
 
     const content = document.querySelector('[data-testid="sheet-layout-content"]') as HTMLElement
@@ -192,7 +192,8 @@ describe('m3-vue/surface e2e', () => {
     expect(afterRect.height).toBeGreaterThan(canvasRect.height - 44)
 
     const morphedSurface = document.querySelector('[data-testid="orchestrated-card-surface"]') as HTMLElement
-    expect(morphedSurface.classList.contains('m3-surface_role-surface')).toBe(true)
+    expect(morphedSurface.classList.contains('m3-surface')).toBe(true)
+    expect(morphedSurface.classList.contains('m3-surface_container')).toBe(false)
     expect(morphedSurface.style.borderTopLeftRadius).toBe('0px')
 
     await capture('scenario-b-card-after')
diff --git a/m3-vue/tests/M3Surface.test.ts b/m3-vue/tests/M3Surface.test.ts
index a527e22..40ec54d 100644
--- a/m3-vue/tests/M3Surface.test.ts
+++ b/m3-vue/tests/M3Surface.test.ts
@@ -96,7 +96,7 @@ describe('m3-vue/experimental/surface', () => {
 
     let surface = screen.getByRole('region')
 
-    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
 
     await view.rerender({
       elevation: 3,
@@ -105,7 +105,7 @@ describe('m3-vue/experimental/surface', () => {
 
     surface = screen.getByRole('region')
 
-    expect(surface.classList.contains('m3-surface_role-surface-bright')).toBe(true)
-    expect(surface.classList.contains('m3-surface_role-surface-container-high')).toBe(false)
+    expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
   })
 })

From 1931de73d744d5a9dd29bfb81de3ba9895ef17ae Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 16:45:43 +0400
Subject: [PATCH 23/37] feat(m3-foundation): Added shared surface orchestration
 primitives

---
 .../components/side-sheet/index.scss          | 110 +++++-----
 m3-foundation/lib/surface/descriptor.ts       | 146 +++++++++++++
 m3-foundation/lib/surface/orchestration.ts    |  72 +++++++
 m3-foundation/lib/surface/style.ts            | 201 ++++++++++++++++++
 4 files changed, 475 insertions(+), 54 deletions(-)
 create mode 100644 m3-foundation/lib/surface/descriptor.ts
 create mode 100644 m3-foundation/lib/surface/orchestration.ts
 create mode 100644 m3-foundation/lib/surface/style.ts

diff --git a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
index b911c36..f6a421d 100644
--- a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
+++ b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
@@ -1,7 +1,7 @@
 @use '../../basics/shape' as m3-shape;
 @use '../../basics/typography' as m3-typography;
 
-.m3-side-sheet {
+.m3-side-sheet.m3-surface {
   @include m3-shape.corner-left('large');
 
   display: flex;
@@ -11,69 +11,71 @@
   flex-direction: column;
   flex-shrink: 0;
   align-items: flex-start;
-  background: var(--m3-sys-surface-container-low);
-  color: var(--m3-sys-on-surface-variant);
   position: fixed;
   top: 0;
   right: 0;
   z-index: 1000;
 
-  &_docked {
-    @include m3-shape.corner(0);
-    width: 256px;
-    min-width: 256px;
-  }
+  background: var(--m3-sys-surface-container-low);
+  color: var(--m3-sys-on-surface-variant);
+}
 
-  &__header {
-    display: flex;
-    width: 100%;
-    padding: 12px 12px 16px 24px;
-    align-items: flex-start;
-    align-self: stretch;
+.m3-side-sheet.m3-surface.m3-side-sheet_docked {
+  @include m3-shape.corner(0);
+  width: 256px;
+  min-width: 256px;
+}
 
-    &_has-leading-affordance {
-      padding: 12px 12px 16px 4px;
-    }
-  }
+.m3-side-sheet__header {
+  display: flex;
+  width: 100%;
+  padding: 12px 12px 16px 24px;
+  align-items: flex-start;
+  align-self: stretch;
+}
 
-  &__affordance {
-    display: flex;
-    width: 48px;
-    height: 48px;
-    flex-direction: column;
-    justify-content: center;
-    align-items: center;
-    gap: 10px;
-  }
+.m3-side-sheet__header_has-leading-affordance {
+  padding: 12px 12px 16px 4px;
+}
 
-  &__title {
-    @include m3-typography.title-large;
-    flex: 1 0 0;
-    padding-top: 12px;
-  }
+.m3-side-sheet__affordance {
+  display: flex;
+  width: 48px;
+  height: 48px;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 10px;
+}
 
-  &__content {
-    display: flex;
-    width: 100%;
-    flex: 1 0 0;
-    flex-direction: column;
-    align-items: flex-start;
-    align-self: stretch;
-    overflow-y: auto;
-    -ms-overflow-style: none;
-    scrollbar-width: none;
+.m3-side-sheet__title {
+  @include m3-typography.title-large;
+  flex: 1 0 0;
+  padding-top: 12px;
+}
 
-    &::-webkit-scrollbar {
-      display: none;
-    }
-  }
+.m3-side-sheet__content {
+  display: flex;
+  width: 100%;
+  flex: 1 0 0;
+  min-height: 0;
+  flex-direction: column;
+  align-items: flex-start;
+  align-self: stretch;
+  overflow-y: auto;
+  -ms-overflow-style: none;
+  scrollbar-width: none;
 
-  &__footer {
-    display: flex;
-    width: 100%;
-    padding: 16px 24px 24px;
-    align-items: center;
-    align-self: stretch;
-    gap: 8px;
+  &::-webkit-scrollbar {
+    display: none;
   }
-}
\ No newline at end of file
+}
+
+.m3-side-sheet__footer {
+  display: flex;
+  width: 100%;
+  padding: 16px 24px 24px;
+  align-items: center;
+  align-self: stretch;
+  gap: 8px;
+}
diff --git a/m3-foundation/lib/surface/descriptor.ts b/m3-foundation/lib/surface/descriptor.ts
new file mode 100644
index 0000000..4856197
--- /dev/null
+++ b/m3-foundation/lib/surface/descriptor.ts
@@ -0,0 +1,146 @@
+import type {
+  Anchor as SurfaceAnchor,
+  Variant as SurfaceVariant,
+} from '../../types/components/surface'
+
+export type SurfaceStateKind =
+  | 'hidden'
+  | 'compact_card'
+  | 'page_like_parent_fill'
+  | 'docked_side_sheet'
+  | 'modal_side_sheet'
+  | 'modal_dialog_window'
+
+export type SurfaceLayerFamily = 'layout' | 'modal'
+export type SurfaceOverflow = 'visible' | 'auto' | 'hidden'
+
+export type SurfaceCornerRounding = {
+  readonly topLeft: number;
+  readonly topRight: number;
+  readonly bottomRight: number;
+  readonly bottomLeft: number;
+}
+
+export type SurfaceStateDescriptor = {
+  readonly kind: SurfaceStateKind;
+  readonly layer: SurfaceLayerFamily;
+  readonly anchor: SurfaceAnchor;
+  readonly fillWidth: boolean;
+  readonly fillHeight: boolean;
+  readonly variant: Exclude<SurfaceVariant, 'auto'>;
+  readonly elevation: number;
+  readonly scrim: boolean;
+  readonly overflow: SurfaceOverflow;
+  readonly rounding: SurfaceCornerRounding;
+}
+
+const SURFACE_STATE_DESCRIPTORS = {
+  hidden: {
+    kind: 'hidden',
+    layer: 'layout',
+    anchor: 'none',
+    fillWidth: false,
+    fillHeight: false,
+    variant: 'surface-container-low',
+    elevation: 0,
+    scrim: false,
+    overflow: 'hidden',
+    rounding: {
+      topLeft: 0,
+      topRight: 0,
+      bottomRight: 0,
+      bottomLeft: 0,
+    },
+  },
+  compact_card: {
+    kind: 'compact_card',
+    layer: 'layout',
+    anchor: 'none',
+    fillWidth: true,
+    fillHeight: false,
+    variant: 'surface-container-low',
+    elevation: 1,
+    scrim: false,
+    overflow: 'auto',
+    rounding: {
+      topLeft: 24,
+      topRight: 24,
+      bottomRight: 24,
+      bottomLeft: 24,
+    },
+  },
+  page_like_parent_fill: {
+    kind: 'page_like_parent_fill',
+    layer: 'layout',
+    anchor: 'none',
+    fillWidth: true,
+    fillHeight: true,
+    variant: 'surface',
+    elevation: 0,
+    scrim: false,
+    overflow: 'auto',
+    rounding: {
+      topLeft: 0,
+      topRight: 0,
+      bottomRight: 0,
+      bottomLeft: 0,
+    },
+  },
+  docked_side_sheet: {
+    kind: 'docked_side_sheet',
+    layer: 'layout',
+    anchor: 'end',
+    fillWidth: false,
+    fillHeight: false,
+    variant: 'surface-container-low',
+    elevation: 0,
+    scrim: false,
+    overflow: 'auto',
+    rounding: {
+      topLeft: 0,
+      topRight: 0,
+      bottomRight: 0,
+      bottomLeft: 0,
+    },
+  },
+  modal_side_sheet: {
+    kind: 'modal_side_sheet',
+    layer: 'modal',
+    anchor: 'end',
+    fillWidth: false,
+    fillHeight: false,
+    variant: 'surface-container-high',
+    elevation: 1,
+    scrim: true,
+    overflow: 'auto',
+    rounding: {
+      topLeft: 28,
+      topRight: 0,
+      bottomRight: 0,
+      bottomLeft: 28,
+    },
+  },
+  modal_dialog_window: {
+    kind: 'modal_dialog_window',
+    layer: 'modal',
+    anchor: 'center',
+    fillWidth: false,
+    fillHeight: false,
+    variant: 'surface-container-highest',
+    elevation: 2,
+    scrim: true,
+    overflow: 'auto',
+    rounding: {
+      topLeft: 28,
+      topRight: 28,
+      bottomRight: 28,
+      bottomLeft: 28,
+    },
+  },
+} as const satisfies Record<SurfaceStateKind, SurfaceStateDescriptor>
+
+export function getSurfaceStateDescriptor<TKind extends SurfaceStateKind>(
+  kind: TKind
+): (typeof SURFACE_STATE_DESCRIPTORS)[TKind] {
+  return SURFACE_STATE_DESCRIPTORS[kind]
+}
diff --git a/m3-foundation/lib/surface/orchestration.ts b/m3-foundation/lib/surface/orchestration.ts
new file mode 100644
index 0000000..d75e200
--- /dev/null
+++ b/m3-foundation/lib/surface/orchestration.ts
@@ -0,0 +1,72 @@
+export type SurfaceMotionRect = {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+export type SurfaceMotionStyle = {
+  top: string;
+  left: string;
+  width: string;
+  height: string;
+}
+
+export function wait(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    setTimeout(() => resolve(), ms)
+  })
+}
+
+export function raf(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve())
+  })
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value))
+}
+
+export function measureRelativeRect(
+  container: HTMLElement | null,
+  element: HTMLElement | null
+): SurfaceMotionRect | null {
+  if (!container || !element) {
+    return null
+  }
+
+  const containerRect = container.getBoundingClientRect()
+  const elementRect = element.getBoundingClientRect()
+
+  return {
+    top: elementRect.top - containerRect.top,
+    left: elementRect.left - containerRect.left,
+    width: elementRect.width,
+    height: elementRect.height,
+  }
+}
+
+export function measureContainerRect(container: HTMLElement | null): SurfaceMotionRect | null {
+  if (!container) {
+    return null
+  }
+
+  const rect = container.getBoundingClientRect()
+
+  return {
+    top: 0,
+    left: 0,
+    width: rect.width,
+    height: rect.height,
+  }
+}
+
+export function toMotionStyle(motion: SurfaceMotionRect): SurfaceMotionStyle {
+  return {
+    top: `${motion.top}px`,
+    left: `${motion.left}px`,
+    width: `${motion.width}px`,
+    height: `${motion.height}px`,
+  }
+}
diff --git a/m3-foundation/lib/surface/style.ts b/m3-foundation/lib/surface/style.ts
new file mode 100644
index 0000000..431d998
--- /dev/null
+++ b/m3-foundation/lib/surface/style.ts
@@ -0,0 +1,201 @@
+import type {
+  Anchor as SurfaceAnchor,
+  Length as SurfaceLength,
+  Variant as SurfaceVariant,
+} from '../../types/components/surface'
+
+import { m3MotionEasings } from '../motion'
+
+export type SurfaceStyleValue = string | number | undefined
+export type SurfaceStyleObject = Record<string, SurfaceStyleValue>
+
+export type SurfaceInset = {
+  top: string;
+  right: string;
+  bottom: string;
+  left: string;
+}
+
+type AnchorStyleFactory = (inset: SurfaceInset) => SurfaceStyleObject
+
+export type SurfacePanelStyleOptions = {
+  fillWidth?: boolean;
+  fillHeight?: boolean;
+  width?: SurfaceLength | null;
+  height?: SurfaceLength | null;
+  minWidth?: SurfaceLength | null;
+  maxWidth?: SurfaceLength | null;
+  minHeight?: SurfaceLength | null;
+  maxHeight?: SurfaceLength | null;
+  rounding?: SurfaceLength;
+  roundingTopLeft?: SurfaceLength | null;
+  roundingTopRight?: SurfaceLength | null;
+  roundingBottomRight?: SurfaceLength | null;
+  roundingBottomLeft?: SurfaceLength | null;
+  transitionMs?: number;
+  transitionTiming?: string;
+  overflow?: string;
+  style?: object;
+}
+
+export const DEFAULT_SURFACE_TRANSITION_TIMING = m3MotionEasings.standard
+
+const MODAL_ANCHOR_STYLE: Record<SurfaceAnchor, AnchorStyleFactory> = {
+  none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
+  center: () => ({
+    top: '50%',
+    left: '50%',
+    right: 'auto',
+    bottom: 'auto',
+    transform: 'translate(-50%, -50%)',
+  }),
+  start: ({ top, bottom, left }) => ({ top, bottom, left, right: 'auto' }),
+  end: ({ top, right, bottom }) => ({ top, right, bottom, left: 'auto' }),
+  top: ({ top, left, right }) => ({ top, left, right, bottom: 'auto' }),
+  bottom: ({ bottom, left, right }) => ({ bottom, left, right, top: 'auto' }),
+  'top-start': ({ top, left }) => ({ top, left, right: 'auto', bottom: 'auto' }),
+  'top-end': ({ top, right }) => ({ top, right, left: 'auto', bottom: 'auto' }),
+  'bottom-start': ({ bottom, left }) => ({ bottom, left, right: 'auto', top: 'auto' }),
+  'bottom-end': ({ bottom, right }) => ({ bottom, right, left: 'auto', top: 'auto' }),
+}
+
+export const toLength = (value: SurfaceLength | null | undefined, fallback: string): string => {
+  if (value == null) {
+    return fallback
+  }
+
+  return typeof value === 'number'
+    ? `${value}px`
+    : value
+}
+
+export const isDefined = <T,>(value: T | null | undefined): value is T => value !== null && value !== undefined
+
+export const getResolvedVariant = (
+  variant: SurfaceVariant,
+  elevation: number
+): Exclude<SurfaceVariant, 'auto'> => {
+  if (variant !== 'auto') {
+    return variant
+  }
+
+  switch (elevation) {
+    case 0: return 'surface'
+    case 1: return 'surface-container-low'
+    case 2: return 'surface-container'
+    case 3: return 'surface-container-high'
+    case 4: return 'surface-container-highest'
+    default: return 'surface-bright'
+  }
+}
+
+export const getVariantClassName = (
+  variant: Exclude<SurfaceVariant, 'auto'>
+): string | null => {
+  if (variant === 'surface') {
+    return null
+  }
+
+  return `m3-surface_${variant.replace(/^surface-/, '')}`
+}
+
+export const getSurfaceTransition = (
+  transitionMs: number,
+  transitionTiming: string
+): string => {
+  const duration = `${transitionMs}ms`
+
+  return [
+    `width ${duration} ${transitionTiming}`,
+    `height ${duration} ${transitionTiming}`,
+    `min-width ${duration} ${transitionTiming}`,
+    `max-width ${duration} ${transitionTiming}`,
+    `min-height ${duration} ${transitionTiming}`,
+    `max-height ${duration} ${transitionTiming}`,
+    `top ${duration} ${transitionTiming}`,
+    `right ${duration} ${transitionTiming}`,
+    `bottom ${duration} ${transitionTiming}`,
+    `left ${duration} ${transitionTiming}`,
+    `transform ${duration} ${transitionTiming}`,
+    `opacity ${duration} ${transitionTiming}`,
+    `background-color ${duration} ${transitionTiming}`,
+    `box-shadow ${duration} ${transitionTiming}`,
+  ].join(', ')
+}
+
+export const getSurfacePanelClassRecord = (
+  elevation: number,
+  variant: SurfaceVariant
+): Record<string, boolean> => {
+  const resolvedVariant = getResolvedVariant(variant, elevation)
+  const variantClassName = getVariantClassName(resolvedVariant)
+
+  return {
+    'm3-surface': true,
+    [variantClassName || '']: Boolean(variantClassName),
+    [`m3-surface_elevation-${elevation}`]: true,
+  }
+}
+
+const getSurfaceSizeStyle = ({
+  fillWidth = true,
+  fillHeight = true,
+  width = null,
+  height = null,
+  minWidth = null,
+  maxWidth = null,
+  minHeight = null,
+  maxHeight = null,
+}: SurfacePanelStyleOptions): SurfaceStyleObject => ({
+  width: isDefined(width)
+    ? toLength(width, 'auto')
+    : (fillWidth ? '100%' : 'auto'),
+  height: isDefined(height)
+    ? toLength(height, 'auto')
+    : (fillHeight ? '100%' : 'auto'),
+  minWidth: isDefined(minWidth) ? toLength(minWidth, '0px') : undefined,
+  maxWidth: isDefined(maxWidth) ? toLength(maxWidth, 'none') : undefined,
+  minHeight: isDefined(minHeight) ? toLength(minHeight, '0px') : undefined,
+  maxHeight: isDefined(maxHeight) ? toLength(maxHeight, 'none') : undefined,
+})
+
+const getSurfaceCornerStyle = ({
+  rounding = 0,
+  roundingTopLeft = null,
+  roundingTopRight = null,
+  roundingBottomRight = null,
+  roundingBottomLeft = null,
+}: SurfacePanelStyleOptions): SurfaceStyleObject => {
+  const baseRounding = toLength(rounding, '0px')
+
+  return {
+    borderTopLeftRadius: isDefined(roundingTopLeft) ? toLength(roundingTopLeft, baseRounding) : baseRounding,
+    borderTopRightRadius: isDefined(roundingTopRight) ? toLength(roundingTopRight, baseRounding) : baseRounding,
+    borderBottomRightRadius: isDefined(roundingBottomRight) ? toLength(roundingBottomRight, baseRounding) : baseRounding,
+    borderBottomLeftRadius: isDefined(roundingBottomLeft) ? toLength(roundingBottomLeft, baseRounding) : baseRounding,
+  }
+}
+
+export const getSurfacePanelStyle = ({
+  transitionMs = 220,
+  transitionTiming = DEFAULT_SURFACE_TRANSITION_TIMING,
+  overflow = 'visible',
+  style,
+  ...options
+}: SurfacePanelStyleOptions): SurfaceStyleObject => {
+  const duration = `${transitionMs}ms`
+
+  return {
+    ...getSurfaceSizeStyle(options),
+    ...getSurfaceCornerStyle(options),
+    '--m3-surface-radius-transition-duration': duration,
+    overflow,
+    transition: getSurfaceTransition(transitionMs, transitionTiming),
+    ...(style as SurfaceStyleObject | undefined),
+  }
+}
+
+export const getModalAnchorStyle = (
+  anchor: SurfaceAnchor,
+  inset: SurfaceInset
+): SurfaceStyleObject => MODAL_ANCHOR_STYLE[anchor](inset)

From ccbc3522fa6f50babee66bd9cb05b1dd5e4bb1f7 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 16:45:43 +0400
Subject: [PATCH 24/37] feat(m3-react): Refactored surface-based dialogs and
 side sheets

---
 m3-react/src/components/dialog/M3Dialog.tsx   | 187 ++++++----
 .../src/components/side-sheet/M3SideSheet.tsx | 208 ++++++++---
 m3-react/src/components/surface/M3Surface.tsx | 236 +++---------
 .../src/components/surface/M3SurfacePanel.tsx |  80 ++++
 m3-react/src/components/surface/index.ts      |   5 +
 .../surface/orchestration/useStateRef.ts      |  29 ++
 .../orchestration/useSurfaceCardPageMorph.ts  | 208 +++++++++++
 .../orchestration/useSurfaceSideSheetMorph.ts | 298 +++++++++++++++
 m3-react/src/components/surface/shared.ts     |  82 ++++
 m3-react/src/index.ts                         |   3 +
 m3-react/storybook/components/M3Surface.mdx   |   2 +
 .../examples/surface/SurfaceCardPageMorph.tsx | 296 +++++----------
 .../surface/SurfaceNestedDialogsChain.tsx     |  11 +-
 .../surface/SurfaceSideSheetAlwaysModal.tsx   |  13 +-
 .../SurfaceSideSheetDismissToRemove.tsx       |  13 +-
 .../surface/SurfaceSideSheetModalToWindow.tsx |  86 +++--
 .../surface/SurfaceSideSheetMorph.tsx         | 351 ++++--------------
 .../storybook/examples/surface/styles.scss    |  20 +
 m3-react/storybook/examples/surface/utils.ts  |  51 ---
 m3-react/tests/M3Dialog.test.tsx              | 160 +++++++-
 m3-react/tests/M3SideSheet.test.tsx           | 101 +++++
 m3-react/tests/M3SurfacePanel.test.tsx        |  61 +++
 22 files changed, 1589 insertions(+), 912 deletions(-)
 create mode 100644 m3-react/src/components/surface/M3SurfacePanel.tsx
 create mode 100644 m3-react/src/components/surface/orchestration/useStateRef.ts
 create mode 100644 m3-react/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
 create mode 100644 m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
 create mode 100644 m3-react/src/components/surface/shared.ts
 delete mode 100644 m3-react/storybook/examples/surface/utils.ts
 create mode 100644 m3-react/tests/M3SideSheet.test.tsx
 create mode 100644 m3-react/tests/M3SurfacePanel.test.tsx

diff --git a/m3-react/src/components/dialog/M3Dialog.tsx b/m3-react/src/components/dialog/M3Dialog.tsx
index 05300f2..fbe9cbe 100644
--- a/m3-react/src/components/dialog/M3Dialog.tsx
+++ b/m3-react/src/components/dialog/M3Dialog.tsx
@@ -1,15 +1,16 @@
 import type {
+  CSSProperties,
   FC,
   HTMLAttributes,
 } from 'react'
 
-import { createPortal } from 'react-dom'
-import { useMemo } from 'react'
-import { useTransition } from 'react-transition-state'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
 import {
-  useRecord,
-  useWatch,
-} from '@/hooks'
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+import { M3Surface } from '@/components/surface'
 import { distinct } from '@/utils/content'
 import { toClassName } from '@/utils/styling'
 
@@ -19,6 +20,16 @@ export interface M3DialogProps extends HTMLAttributes<HTMLElement> {
   onToggle?: (expanded: boolean) => void;
 }
 
+const DIALOG_WIDTH = 312
+const DIALOG_MIN_WIDTH = 280
+const DIALOG_MAX_WIDTH = 560
+const DIALOG_ROUNDING = 28
+const DIALOG_ENTRY_OFFSET_PX = 24
+const DIALOG_ELEVATION = 0
+const DIALOG_Z_INDEX = 1000
+const DIALOG_TRANSITION_MS = m3MotionDurations.medium2
+const DIALOG_TRANSITION_TIMING = m3MotionEasings.standard
+
 const Icon: FC<HTMLAttributes<HTMLElement>> = ({
   className = '',
   children = [],
@@ -53,6 +64,7 @@ const M3Dialog: FC<M3DialogProps> = ({
   opened = false,
   fullscreen = false,
   className = '',
+  style,
   children = [],
   onToggle = (_: boolean) => {},
   ...attrs
@@ -62,64 +74,115 @@ const M3Dialog: FC<M3DialogProps> = ({
     header: Header,
     footer: Footer,
   }), [children])
+  const [dialogMounted, setDialogMounted] = useState(opened)
+  const [dialogVisible, setDialogVisible] = useState(false)
+  const frameRef = useRef<number | null>(null)
+  const timeoutRef = useRef<number | null>(null)
+
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      setDialogMounted(opened)
+      setDialogVisible(opened)
+      return
+    }
+
+    if (frameRef.current !== null) {
+      window.cancelAnimationFrame(frameRef.current)
+      frameRef.current = null
+    }
+
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+
+    if (opened) {
+      setDialogMounted(true)
+      setDialogVisible(false)
+
+      frameRef.current = window.requestAnimationFrame(() => {
+        frameRef.current = null
+        setDialogVisible(true)
+      })
+
+      return () => {
+        if (frameRef.current !== null) {
+          window.cancelAnimationFrame(frameRef.current)
+          frameRef.current = null
+        }
+      }
+    }
+
+    setDialogVisible(false)
+
+    if (dialogMounted) {
+      timeoutRef.current = window.setTimeout(() => {
+        timeoutRef.current = null
+        setDialogMounted(false)
+      }, DIALOG_TRANSITION_MS)
+    }
+
+    return () => {
+      if (frameRef.current !== null) {
+        window.cancelAnimationFrame(frameRef.current)
+        frameRef.current = null
+      }
+
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current)
+        timeoutRef.current = null
+      }
+    }
+  }, [opened])
+
+  const dialogStyle: CSSProperties = {
+    opacity: dialogVisible ? 1 : 0,
+    transform: fullscreen
+      ? 'translate3d(0, 0, 0)'
+      : (dialogVisible
+        ? 'translate(-50%, -50%)'
+        : `translate(-50%, calc(-50% + ${DIALOG_ENTRY_OFFSET_PX}px))`),
+    transition: `opacity ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}, transform ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}`,
+    pointerEvents: dialogVisible ? 'auto' : 'none',
+    ...style,
+  }
 
-  const handlers = useRecord({
-    onToggle,
-  })
-
-  useWatch(onToggle, onToggle => handlers.onToggle = onToggle)
-
-  const [transition, toggle] = useTransition({
-    timeout: 500,
-    preEnter: true,
-    preExit: true,
-    mountOnEnter: true,
-    unmountOnExit: true,
-  })
-
-  toggle(opened)
-
-  return createPortal(
-    <div
-      className={toClassName(['m3-dialog-container', {
-        'm3-transition-fade-enter': transition.status === 'preEnter' || transition.status === 'entering',
-        'm3-transition-fade-enter-active': transition.status === 'entering',
-        'm3-transition-fade-leave-active': transition.status === 'preExit' || transition.status === 'exiting',
-        'm3-transition-fade-leave-to': transition.status === 'exiting',
-      }])}
-      style={transition.status === 'unmounted' ? { display: 'none' } : {}}
+  return (
+    <M3Surface
+      tag="section"
+      mode="modal"
+      shown={dialogMounted}
+      scrimShown={opened}
+      teleportTo="body"
+      scrim={!fullscreen}
+      anchor={fullscreen ? 'none' : 'center'}
+      fillWidth={fullscreen}
+      fillHeight={fullscreen}
+      width={fullscreen ? '100vw' : DIALOG_WIDTH}
+      height={fullscreen ? '100vh' : null}
+      minWidth={fullscreen ? 0 : DIALOG_MIN_WIDTH}
+      maxWidth={fullscreen ? '100vw' : DIALOG_MAX_WIDTH}
+      maxHeight={fullscreen ? '100vh' : null}
+      rounding={fullscreen ? 0 : DIALOG_ROUNDING}
+      variant="surface-container-high"
+      elevation={DIALOG_ELEVATION}
+      zIndex={DIALOG_Z_INDEX}
+      transitionMs={DIALOG_TRANSITION_MS}
+      transitionTiming={DIALOG_TRANSITION_TIMING}
+      className={toClassName(['m3-dialog', className])}
+      style={dialogStyle}
+      onDismiss={() => onToggle(false)}
+      {...attrs}
     >
-      {fullscreen ? null : (
-        <div
-          className="m3-scrim"
-          onClick={() => handlers.onToggle(false)}
-        />
-      )}
-
-      {transition.isMounted && (
-        <section
-          className={toClassName([className, {
-            'm3-dialog': true,
-            'm3-dialog_fullscreen': fullscreen,
-            'm3-dialog-appear-enter': transition.status === 'preEnter' || transition.status === 'entering',
-            'm3-dialog-appear-enter-active': transition.status === 'entering',
-            'm3-dialog-appear-leave-active': transition.status === 'preExit' || transition.status === 'exiting',
-            'm3-dialog-appear-leave-to': transition.status === 'exiting',
-          }])}
-          {...attrs}
-        >
-          {slots.icon}
-          {slots.header}
-          {content.length ? (
-            <div className="m3-dialog__content">
-              {content}
-            </div>
-          ) : null}
-          {slots.footer}
-        </section>
-      )}
-    </div>,
-    document.body
+      {slots.icon}
+      {slots.header}
+      {content.length ? (
+        <div className="m3-dialog__content">
+          {content}
+        </div>
+      ) : null}
+      {slots.footer}
+    </M3Surface>
   )
 }
 
diff --git a/m3-react/src/components/side-sheet/M3SideSheet.tsx b/m3-react/src/components/side-sheet/M3SideSheet.tsx
index ee0dc65..13108f7 100644
--- a/m3-react/src/components/side-sheet/M3SideSheet.tsx
+++ b/m3-react/src/components/side-sheet/M3SideSheet.tsx
@@ -1,28 +1,41 @@
 import type {
   FC,
-  HTMLAttributes,
   ReactNode,
 } from 'react'
+import type { M3SurfaceProps } from '@/components/surface'
 
 import { M3IconButton } from '@/components/icon-button'
 import { M3ScrollRail } from '@/components/scroll-rail'
+import { M3Surface } from '@/components/surface'
+import { m3MotionDurations } from '@modulify/m3-foundation/lib/motion'
 
 import {
   useId,
 } from '@/hooks'
 
-import { createPortal } from 'react-dom'
-
 import { useMemo } from 'react'
+import { useTransition } from 'react-transition-state'
 
 import { distinct } from '@/utils/content'
 import { toClassName } from '@/utils/styling'
 
-export interface M3SideSheetProps extends HTMLAttributes<HTMLElement> {
+export interface M3SideSheetProps extends Omit<
+  M3SurfaceProps,
+  | 'anchor'
+  | 'children'
+  | 'mode'
+  | 'onDismiss'
+  | 'onToggle'
+  | 'scrim'
+  | 'shown'
+  | 'tag'
+> {
   id?: string;
   shown?: boolean;
   docked?: boolean;
+  children?: ReactNode | ReactNode[];
   onToggle?: (shown: boolean) => void;
+  onDismiss?: () => void;
 }
 
 const Affordance: FC<{ children: ReactNode }> = props => <>{props.children}</>
@@ -30,13 +43,41 @@ const Title: FC<{ children: ReactNode }> = props => <>{props.children}</>
 const CloseIcon: FC<{ children: ReactNode }> = props => <>{props.children}</>
 const Footer: FC<{ children: ReactNode }> = props => <>{props.children}</>
 
+const DOCKED_WIDTH = 256
+const MODAL_MIN_WIDTH = 320
+const MODAL_MAX_WIDTH = 400
+const MODAL_RADIUS = 16
+const SIDE_SHEET_Z_INDEX = 1000
+const SIDE_SHEET_TRANSITION_MS = m3MotionDurations['extra-long2']
+
 const M3SideSheet: FC<M3SideSheetProps> = ({
   id,
   shown = false,
   docked = false,
   className = '',
+  style,
+  fillWidth = false,
+  fillHeight = true,
+  width = null,
+  minWidth = null,
+  maxWidth = null,
+  minHeight = null,
+  maxHeight = null,
+  rounding = 0,
+  roundingTopLeft = null,
+  roundingTopRight = 0,
+  roundingBottomRight = 0,
+  roundingBottomLeft = null,
+  transitionMs = 220,
+  transitionTiming,
+  overflow = 'hidden',
+  elevation = 0,
+  variant = 'surface-container-low',
+  role = 'dialog',
+  zIndex = SIDE_SHEET_Z_INDEX,
   children = [],
   onToggle = (_: boolean) => {},
+  onDismiss = () => {},
   ...attrs
 }) => {
   const _id = useId(id, 'm3-side-sheet')
@@ -52,69 +93,118 @@ const M3SideSheet: FC<M3SideSheetProps> = ({
     ? {}
     : { 'aria-labelledby': _id + '-title' }
 
-  return createPortal(
-    <>
-      {docked ? null : (
-        <div
-          className="m3-scrim"
-          style={shown ? undefined : { display: 'none' }}
-          onClick={() => onToggle(false)}
-        />
-      )}
-
-      <div
-        id={_id}
-        role="dialog"
-        className={toClassName([className, {
-          'm3-side-sheet': true,
-          'm3-side-sheet_docked': docked,
-        }])}
-        style={shown ? undefined : { display: 'none' }}
-        {...{
-          ...aria,
-          ...attrs,
-        }}
+  const surfaceWidth = width ?? (docked ? DOCKED_WIDTH : null)
+  const surfaceMinWidth = minWidth ?? (docked ? DOCKED_WIDTH : MODAL_MIN_WIDTH)
+  const surfaceMaxWidth = maxWidth ?? (docked ? DOCKED_WIDTH : MODAL_MAX_WIDTH)
+  const surfaceTopLeft = roundingTopLeft ?? (docked ? 0 : MODAL_RADIUS)
+  const surfaceBottomLeft = roundingBottomLeft ?? (docked ? 0 : MODAL_RADIUS)
+
+  const [transition, toggle] = useTransition({
+    timeout: SIDE_SHEET_TRANSITION_MS,
+    preEnter: true,
+    preExit: true,
+    mountOnEnter: true,
+    unmountOnExit: true,
+  })
+
+  toggle(shown)
+
+  const surfaceScrimShown = !docked && shown && transition.status !== 'preEnter'
+  const ariaModal = 'aria-modal' in attrs ? attrs['aria-modal'] : (docked ? 'false' : undefined)
+
+  if (typeof document === 'undefined') {
+    return null
+  }
+
+  const surfaceNode = (
+    <M3Surface
+      id={_id}
+      tag="div"
+      shown={true}
+      mode="modal"
+      scrim={true}
+      scrimShown={surfaceScrimShown}
+      anchor="end"
+      fillWidth={fillWidth}
+      fillHeight={fillHeight}
+      width={surfaceWidth}
+      minWidth={surfaceMinWidth}
+      maxWidth={surfaceMaxWidth}
+      minHeight={minHeight}
+      maxHeight={maxHeight}
+      rounding={rounding}
+      roundingTopLeft={surfaceTopLeft}
+      roundingTopRight={roundingTopRight}
+      roundingBottomRight={roundingBottomRight}
+      roundingBottomLeft={surfaceBottomLeft}
+      transitionMs={transitionMs}
+      transitionTiming={transitionTiming}
+      overflow={overflow}
+      elevation={elevation}
+      variant={variant}
+      role={role}
+      aria-modal={ariaModal}
+      zIndex={zIndex}
+      className={toClassName([className, {
+        'm3-side-sheet': true,
+        'm3-side-sheet_docked': docked,
+        'm3-transition-slide-right-enter': transition.status === 'preEnter' || transition.status === 'entering',
+        'm3-transition-slide-right-enter-active': transition.status === 'entering',
+        'm3-transition-slide-right-leave-active': transition.status === 'preExit' || transition.status === 'exiting',
+        'm3-transition-slide-right-leave-to': transition.status === 'exiting',
+      }])}
+      style={style}
+      onToggle={onToggle}
+      onDismiss={onDismiss}
+      {...{
+        ...aria,
+        ...attrs,
+      }}
+    >
+      <header
+        className={toClassName({
+          'm3-side-sheet__header': true,
+          'm3-side-sheet__header_has-leading-affordance': !!slots.affordance,
+        })}
       >
-        <header
-          className={toClassName({
-            'm3-side-sheet__header': true,
-            'm3-side-sheet__header_has-leading-affordance': !!slots.affordance,
-          })}
-        >
-          {slots.affordance ? (
-            <div className="m3-side-sheet__affordance">
-              {slots.affordance}
-            </div>
-          ) : null}
-
-          <div
-            id={_id + '-title'}
-            className="m3-side-sheet__title"
-          >
-            {slots.title}
-          </div>
-
+        {slots.affordance ? (
           <div className="m3-side-sheet__affordance">
-            <M3IconButton onClick={() => onToggle(false)}>
-              {slots.closeIcon}
-            </M3IconButton>
+            {slots.affordance}
           </div>
-        </header>
+        ) : null}
 
-        <div className="m3-side-sheet__content">
-          <M3ScrollRail />
-          {content}
+        <div
+          id={_id + '-title'}
+          className="m3-side-sheet__title"
+        >
+          {slots.title}
         </div>
 
-        {slots.footer ? (
-          <footer className="m3-side-sheet__footer">
-            {slots.footer}
-          </footer>
-        ) : null}
+        <div className="m3-side-sheet__affordance">
+          <M3IconButton onClick={() => onToggle(false)}>
+            {slots.closeIcon}
+          </M3IconButton>
+        </div>
+      </header>
+
+      <div className="m3-side-sheet__content">
+        <M3ScrollRail />
+        {content}
       </div>
-    </>,
-    document.body
+
+      {slots.footer ? (
+        <footer className="m3-side-sheet__footer">
+          {slots.footer}
+        </footer>
+      ) : null}
+    </M3Surface>
   )
+
+  if (!transition.isMounted) {
+    return null
+  }
+
+  return surfaceNode
 }
 
 export default Object.assign(M3SideSheet, {
diff --git a/m3-react/src/components/surface/M3Surface.tsx b/m3-react/src/components/surface/M3Surface.tsx
index 2342553..8ec5ba5 100644
--- a/m3-react/src/components/surface/M3Surface.tsx
+++ b/m3-react/src/components/surface/M3Surface.tsx
@@ -1,192 +1,91 @@
 import type {
   CSSProperties,
   FC,
-  HTMLAttributes,
 } from 'react'
+
 import type {
   Anchor as SurfaceAnchor,
   Length as SurfaceLength,
   Mode as SurfaceMode,
-  Variant as SurfaceVariant,
 } from '@modulify/m3-foundation/types/components/surface'
 
+import type {
+  M3SurfacePanelProps,
+  M3SurfacePanelVariant,
+} from './shared'
+
 import { createPortal } from 'react-dom'
-import { m3MotionEasings } from '@modulify/m3-foundation/lib/motion'
+import { useTransition } from 'react-transition-state'
 
-import {
-  useId,
-} from '@/hooks'
+import { useId } from '@/hooks'
 
-import { toClassName } from '@/utils/styling'
+import M3SurfacePanel from './M3SurfacePanel'
 
-type Inset = {
-  top: string;
-  right: string;
-  bottom: string;
-  left: string;
-}
+import { toClassName } from '@/utils/styling'
+import {
+  getModalAnchorStyle,
+  toLength,
+} from './shared'
 
 export type M3SurfaceMode = SurfaceMode
-export type M3SurfaceVariant = SurfaceVariant
+export type M3SurfaceVariant = M3SurfacePanelVariant
 export type M3SurfaceAnchor = SurfaceAnchor
 
-export interface M3SurfaceProps extends HTMLAttributes<HTMLElement> {
-  id?: string;
-  tag?: keyof HTMLElementTagNameMap;
+export interface M3SurfaceProps extends M3SurfacePanelProps {
   shown?: boolean;
   mode?: M3SurfaceMode;
   teleportTo?: string;
   scrim?: boolean;
-  elevation?: number;
-  variant?: M3SurfaceVariant;
-  fillWidth?: boolean;
-  fillHeight?: boolean;
-  width?: SurfaceLength | null;
-  height?: SurfaceLength | null;
-  minWidth?: SurfaceLength | null;
-  maxWidth?: SurfaceLength | null;
-  minHeight?: SurfaceLength | null;
-  maxHeight?: SurfaceLength | null;
-  rounding?: SurfaceLength;
-  roundingTopLeft?: SurfaceLength | null;
-  roundingTopRight?: SurfaceLength | null;
-  roundingBottomRight?: SurfaceLength | null;
-  roundingBottomLeft?: SurfaceLength | null;
+  scrimShown?: boolean;
   anchor?: M3SurfaceAnchor;
   insetTop?: SurfaceLength;
   insetRight?: SurfaceLength;
   insetBottom?: SurfaceLength;
   insetLeft?: SurfaceLength;
   zIndex?: number;
-  transitionMs?: number;
-  transitionTiming?: string;
-  overflow?: CSSProperties['overflow'];
   onToggle?: (shown: boolean) => void;
   onDismiss?: () => void;
 }
 
-type AnchorStyleFactory = (inset: Inset) => CSSProperties
-
-const MODAL_ANCHOR_STYLE: Record<SurfaceAnchor, AnchorStyleFactory> = {
-  none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
-  center: () => ({
-    top: '50%',
-    left: '50%',
-    right: 'auto',
-    bottom: 'auto',
-    transform: 'translate(-50%, -50%)',
-  }),
-  start: ({ top, bottom, left }) => ({ top, bottom, left, right: 'auto' }),
-  end: ({ top, right, bottom }) => ({ top, right, bottom, left: 'auto' }),
-  top: ({ top, left, right }) => ({ top, left, right, bottom: 'auto' }),
-  bottom: ({ bottom, left, right }) => ({ bottom, left, right, top: 'auto' }),
-  'top-start': ({ top, left }) => ({ top, left, right: 'auto', bottom: 'auto' }),
-  'top-end': ({ top, right }) => ({ top, right, left: 'auto', bottom: 'auto' }),
-  'bottom-start': ({ bottom, left }) => ({ bottom, left, right: 'auto', top: 'auto' }),
-  'bottom-end': ({ bottom, right }) => ({ bottom, right, left: 'auto', top: 'auto' }),
-}
-
-const toLength = (value: SurfaceLength | null | undefined, fallback: string): string => {
-  if (value == null) {
-    return fallback
-  }
-
-  return typeof value === 'number'
-    ? `${value}px`
-    : value
-}
-
-const isDefined = <T,>(value: T | null | undefined): value is T => value !== null && value !== undefined
-
-const getResolvedVariant = (variant: SurfaceVariant, elevation: number): Exclude<SurfaceVariant, 'auto'> => {
-  if (variant !== 'auto') return variant
-
-  switch (elevation) {
-    case 0: return 'surface'
-    case 1: return 'surface-container-low'
-    case 2: return 'surface-container'
-    case 3: return 'surface-container-high'
-    case 4: return 'surface-container-highest'
-    default: return 'surface-bright'
-  }
-}
-
-const getVariantClassName = (variant: Exclude<SurfaceVariant, 'auto'>): string | null => {
-  if (variant === 'surface') {
-    return null
-  }
-
-  return `m3-surface_${variant.replace(/^surface-/, '')}`
-}
-
 const M3Surface: FC<M3SurfaceProps> = ({
   id,
-  tag = 'section',
   shown = true,
   mode = 'standard',
   teleportTo = 'body',
   scrim = true,
-  elevation = 0,
-  variant = 'auto',
-  fillWidth = true,
-  fillHeight = true,
-  width = null,
-  height = null,
-  minWidth = null,
-  maxWidth = null,
-  minHeight = null,
-  maxHeight = null,
-  rounding = 0,
-  roundingTopLeft = null,
-  roundingTopRight = null,
-  roundingBottomRight = null,
-  roundingBottomLeft = null,
+  scrimShown,
   anchor = 'none',
   insetTop = 0,
   insetRight = 0,
   insetBottom = 0,
   insetLeft = 0,
-  zIndex = 400,
   transitionMs = 220,
-  transitionTiming = m3MotionEasings.standard,
-  overflow = 'visible',
+  zIndex = 400,
   onToggle = (_: boolean) => {},
   onDismiss = () => {},
+  role,
+  'aria-modal': ariaModal,
   className = '',
   style,
-  children = [],
-  ...attrs
+  children,
+  ...panelProps
 }) => {
-  const _id = useId(id, 'm3-surface')
   const isModal = mode === 'modal'
-  const resolvedVariant = getResolvedVariant(variant, elevation)
-  const variantClassName = getVariantClassName(resolvedVariant)
-  const SurfaceTag = tag
+  const resolvedScrimShown = scrimShown ?? shown
+  const [modalTransition, toggleModalTransition] = useTransition({
+    timeout: transitionMs,
+    preEnter: true,
+    preExit: true,
+    mountOnEnter: true,
+    unmountOnExit: true,
+  })
 
-  const resolvedSizeStyle: CSSProperties = {
-    width: isDefined(width)
-      ? toLength(width, 'auto')
-      : (fillWidth ? '100%' : 'auto'),
-    height: isDefined(height)
-      ? toLength(height, 'auto')
-      : (fillHeight ? '100%' : 'auto'),
-    minWidth: isDefined(minWidth) ? toLength(minWidth, '0px') : undefined,
-    maxWidth: isDefined(maxWidth) ? toLength(maxWidth, 'none') : undefined,
-    minHeight: isDefined(minHeight) ? toLength(minHeight, '0px') : undefined,
-    maxHeight: isDefined(maxHeight) ? toLength(maxHeight, 'none') : undefined,
-  }
-
-  const baseRounding = toLength(rounding, '0px')
+  toggleModalTransition(isModal && scrim && resolvedScrimShown)
 
-  const cornerStyle: CSSProperties = {
-    borderTopLeftRadius: isDefined(roundingTopLeft) ? toLength(roundingTopLeft, baseRounding) : baseRounding,
-    borderTopRightRadius: isDefined(roundingTopRight) ? toLength(roundingTopRight, baseRounding) : baseRounding,
-    borderBottomRightRadius: isDefined(roundingBottomRight) ? toLength(roundingBottomRight, baseRounding) : baseRounding,
-    borderBottomLeftRadius: isDefined(roundingBottomLeft) ? toLength(roundingBottomLeft, baseRounding) : baseRounding,
-  }
+  const modalMounted = !isModal || shown || (scrim && modalTransition.isMounted)
 
   const anchorStyle: CSSProperties = isModal
-    ? MODAL_ANCHOR_STYLE[anchor]({
+    ? getModalAnchorStyle(anchor, {
       top: toLength(insetTop, '0px'),
       right: toLength(insetRight, '0px'),
       bottom: toLength(insetBottom, '0px'),
@@ -194,59 +93,26 @@ const M3Surface: FC<M3SurfaceProps> = ({
     })
     : {}
 
-  const duration = `${transitionMs}ms`
-  const transition = [
-    `width ${duration} ${transitionTiming}`,
-    `height ${duration} ${transitionTiming}`,
-    `min-width ${duration} ${transitionTiming}`,
-    `max-width ${duration} ${transitionTiming}`,
-    `min-height ${duration} ${transitionTiming}`,
-    `max-height ${duration} ${transitionTiming}`,
-    `top ${duration} ${transitionTiming}`,
-    `right ${duration} ${transitionTiming}`,
-    `bottom ${duration} ${transitionTiming}`,
-    `left ${duration} ${transitionTiming}`,
-    `transform ${duration} ${transitionTiming}`,
-    `opacity ${duration} ${transitionTiming}`,
-    `background-color ${duration} ${transitionTiming}`,
-    `box-shadow ${duration} ${transitionTiming}`,
-  ].join(', ')
-
-  const surfaceClassName = toClassName([className, {
-    'm3-surface': true,
-    'm3-surface_modal': isModal,
-    [variantClassName || '']: Boolean(variantClassName),
-    [`m3-surface_anchor-${anchor}`]: true,
-    [`m3-surface_elevation-${elevation}`]: true,
-  }])
-
-  const radiusTransitionStyle = {
-    '--m3-surface-radius-transition-duration': duration,
-  } as CSSProperties
-
   const surfaceNode = (
-    <SurfaceTag
-      id={_id}
-      className={surfaceClassName}
+    <M3SurfacePanel
+      id={useId(id, 'm3-surface')}
+      {...panelProps}
+      className={toClassName([className, {
+        ['m3-surface_modal']: isModal,
+        [`m3-surface_anchor-${anchor}`]: true,
+      }])}
       style={{
-        ...resolvedSizeStyle,
-        ...cornerStyle,
         ...anchorStyle,
-        ...radiusTransitionStyle,
-        overflow,
-        transition,
         position: isModal ? 'fixed' : 'relative',
         zIndex: isModal ? zIndex : undefined,
         display: shown ? undefined : 'none',
         ...style,
       }}
-      {...(isModal
-        ? { role: 'dialog', 'aria-modal': 'true' as const }
-        : { role: 'region' })}
-      {...attrs}
+      role={role ?? (isModal ? 'dialog' : 'region')}
+      aria-modal={isModal ? (ariaModal ?? 'true') : ariaModal}
     >
       {children}
-    </SurfaceTag>
+    </M3SurfacePanel>
   )
 
   if (!isModal) {
@@ -261,14 +127,22 @@ const M3Surface: FC<M3SurfaceProps> = ({
     return null
   }
 
+  if (!modalMounted) {
+    return null
+  }
+
   return createPortal(
     <>
-      {scrim ? (
+      {scrim && modalTransition.isMounted ? (
         <div
-          className="m3-surface__scrim"
+          className={toClassName(['m3-surface__scrim', {
+            'm3-transition-fade-enter': modalTransition.status === 'preEnter' || modalTransition.status === 'entering',
+            'm3-transition-fade-enter-active': modalTransition.status === 'entering',
+            'm3-transition-fade-leave-active': modalTransition.status === 'preExit' || modalTransition.status === 'exiting',
+            'm3-transition-fade-leave-to': modalTransition.status === 'exiting',
+          }])}
           style={{
             zIndex: zIndex - 1,
-            display: shown ? undefined : 'none',
           }}
           onClick={() => {
             onToggle(false)
diff --git a/m3-react/src/components/surface/M3SurfacePanel.tsx b/m3-react/src/components/surface/M3SurfacePanel.tsx
new file mode 100644
index 0000000..9d51b63
--- /dev/null
+++ b/m3-react/src/components/surface/M3SurfacePanel.tsx
@@ -0,0 +1,80 @@
+import type { FC } from 'react'
+
+import type {
+  M3SurfacePanelProps,
+  M3SurfacePanelVariant,
+} from './shared'
+
+import {
+  getSurfacePanelClassName,
+  getSurfacePanelStyle,
+} from './shared'
+
+export type {
+  M3SurfacePanelProps,
+  M3SurfacePanelVariant,
+}
+
+const M3SurfacePanel: FC<M3SurfacePanelProps> = ({
+  id,
+  tag = 'section',
+  elevation = 0,
+  variant = 'auto',
+  fillWidth = true,
+  fillHeight = true,
+  width = null,
+  height = null,
+  minWidth = null,
+  maxWidth = null,
+  minHeight = null,
+  maxHeight = null,
+  rounding = 0,
+  roundingTopLeft = null,
+  roundingTopRight = null,
+  roundingBottomRight = null,
+  roundingBottomLeft = null,
+  transitionMs = 220,
+  transitionTiming,
+  overflow = 'visible',
+  className = '',
+  style,
+  children,
+  ...attrs
+}) => {
+  const SurfaceTag = tag
+
+  return (
+    <SurfaceTag
+      id={id}
+      className={getSurfacePanelClassName({
+        className,
+        elevation,
+        variant,
+      })}
+      style={getSurfacePanelStyle({
+        fillWidth,
+        fillHeight,
+        width,
+        height,
+        minWidth,
+        maxWidth,
+        minHeight,
+        maxHeight,
+        rounding,
+        roundingTopLeft,
+        roundingTopRight,
+        roundingBottomRight,
+        roundingBottomLeft,
+        transitionMs,
+        transitionTiming,
+        overflow,
+        style,
+      })}
+      {...attrs}
+    >
+      {children}
+    </SurfaceTag>
+  )
+}
+
+export default M3SurfacePanel
diff --git a/m3-react/src/components/surface/index.ts b/m3-react/src/components/surface/index.ts
index f76f3b4..469cf7c 100644
--- a/m3-react/src/components/surface/index.ts
+++ b/m3-react/src/components/surface/index.ts
@@ -4,5 +4,10 @@ export type {
   M3SurfaceProps,
   M3SurfaceVariant,
 } from './M3Surface'
+export type {
+  M3SurfacePanelProps,
+  M3SurfacePanelVariant,
+} from './M3SurfacePanel'
 
+export { default as M3SurfacePanel } from './M3SurfacePanel'
 export { default as M3Surface } from './M3Surface'
diff --git a/m3-react/src/components/surface/orchestration/useStateRef.ts b/m3-react/src/components/surface/orchestration/useStateRef.ts
new file mode 100644
index 0000000..0e7d22f
--- /dev/null
+++ b/m3-react/src/components/surface/orchestration/useStateRef.ts
@@ -0,0 +1,29 @@
+import type {
+  MutableRefObject,
+  SetStateAction,
+} from 'react'
+
+import {
+  useRef,
+  useState,
+} from 'react'
+
+export function useStateRef<T>(
+  initial: T
+): [T, (next: SetStateAction<T>) => void, MutableRefObject<T>] {
+  const [state, setState] = useState<T>(initial)
+  const ref = useRef(state)
+
+  const set = (next: SetStateAction<T>) => {
+    setState((previous) => {
+      const resolved = typeof next === 'function'
+        ? (next as (value: T) => T)(previous)
+        : next
+
+      ref.current = resolved
+      return resolved
+    })
+  }
+
+  return [state, set, ref]
+}
diff --git a/m3-react/src/components/surface/orchestration/useSurfaceCardPageMorph.ts b/m3-react/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
new file mode 100644
index 0000000..e4a3e65
--- /dev/null
+++ b/m3-react/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
@@ -0,0 +1,208 @@
+/* eslint-disable max-lines-per-function */
+import type {
+  CSSProperties,
+  MutableRefObject,
+} from 'react'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import {
+  measureContainerRect,
+  measureRelativeRect,
+  raf,
+  toMotionStyle,
+  type SurfaceMotionRect,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+import { useStateRef } from './useStateRef'
+
+type UseSurfaceCardPageMorphResult = {
+  expanded: boolean;
+  busy: boolean;
+  backgroundCollapsed: boolean;
+  originHeight: number;
+  overlayStyle: CSSProperties;
+  canvasRef: MutableRefObject<HTMLDivElement | null>;
+  originSlotRef: MutableRefObject<HTMLDivElement | null>;
+  toggleCardMode: () => Promise<void>;
+}
+
+export function useSurfaceCardPageMorph(transitionMs: number): UseSurfaceCardPageMorphResult {
+  const [expanded, setExpanded, expandedRef] = useStateRef(false)
+  const [busy, setBusy, busyRef] = useStateRef(false)
+  const [backgroundCollapsed, setBackgroundCollapsed, backgroundCollapsedRef] = useStateRef(false)
+  const [originHeight, setOriginHeight] = useStateRef(220)
+  const [motion, setMotion] = useStateRef<SurfaceMotionRect>({
+    top: 16,
+    left: 16,
+    width: 320,
+    height: 220,
+  })
+
+  const canvasRef = useRef<HTMLDivElement | null>(null)
+  const originSlotRef = useRef<HTMLDivElement | null>(null)
+  const syncFrameRef = useRef<number | null>(null)
+
+  const measureOrigin = () => measureRelativeRect(canvasRef.current, originSlotRef.current)
+
+  const measureExpanded = () => measureContainerRect(canvasRef.current)
+
+  const syncMotionToLayout = () => {
+    const origin = measureOrigin()
+
+    if (origin) {
+      setOriginHeight(origin.height)
+    }
+
+    if (expandedRef.current) {
+      const full = measureExpanded()
+
+      if (full) {
+        setMotion(full)
+      }
+
+      return
+    }
+
+    if (!origin || backgroundCollapsedRef.current) {
+      return
+    }
+
+    setMotion(origin)
+  }
+
+  const scheduleSyncMotion = () => {
+    if (syncFrameRef.current !== null) {
+      cancelAnimationFrame(syncFrameRef.current)
+    }
+
+    syncFrameRef.current = requestAnimationFrame(() => {
+      syncFrameRef.current = null
+      syncMotionToLayout()
+    })
+  }
+
+  const initMotion = async () => {
+    await raf()
+
+    const origin = measureOrigin()
+    if (!origin) {
+      return
+    }
+
+    setMotion(origin)
+    setOriginHeight(origin.height)
+  }
+
+  const expandCard = async () => {
+    setBackgroundCollapsed(false)
+
+    const origin = measureOrigin()
+    if (origin) {
+      setMotion(origin)
+      setOriginHeight(origin.height)
+    }
+
+    setExpanded(true)
+    await raf()
+
+    const full = measureExpanded()
+    if (!full) {
+      return
+    }
+
+    setMotion(full)
+    await wait(transitionMs)
+    setBackgroundCollapsed(true)
+  }
+
+  const collapseCard = async () => {
+    if (backgroundCollapsed) {
+      setBackgroundCollapsed(false)
+      await raf()
+    }
+
+    const full = measureExpanded()
+    if (full) {
+      setMotion(full)
+    }
+
+    const origin = measureOrigin()
+    if (origin) {
+      setOriginHeight(origin.height)
+    }
+
+    setExpanded(false)
+    await raf()
+
+    if (!origin) {
+      return
+    }
+
+    setMotion(origin)
+    await wait(transitionMs)
+  }
+
+  const toggleCardMode = async () => {
+    if (busyRef.current) {
+      return
+    }
+
+    setBusy(true)
+
+    if (expandedRef.current) {
+      await collapseCard()
+      setBusy(false)
+      return
+    }
+
+    await expandCard()
+    setBusy(false)
+  }
+
+  useEffect(() => {
+    void initMotion()
+  }, [])
+
+  useEffect(() => {
+    if (typeof ResizeObserver === 'undefined') {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      scheduleSyncMotion()
+    })
+
+    if (canvasRef.current) {
+      observer.observe(canvasRef.current)
+    }
+
+    if (originSlotRef.current) {
+      observer.observe(originSlotRef.current)
+    }
+
+    return () => {
+      observer.disconnect()
+
+      if (syncFrameRef.current !== null) {
+        cancelAnimationFrame(syncFrameRef.current)
+        syncFrameRef.current = null
+      }
+    }
+  }, [])
+
+  return {
+    expanded,
+    busy,
+    backgroundCollapsed,
+    originHeight,
+    overlayStyle: toMotionStyle(motion),
+    canvasRef,
+    originSlotRef,
+    toggleCardMode,
+  }
+}
diff --git a/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts b/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
new file mode 100644
index 0000000..fb14894
--- /dev/null
+++ b/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
@@ -0,0 +1,298 @@
+/* eslint-disable max-lines-per-function */
+import type {
+  CSSProperties,
+  MutableRefObject,
+} from 'react'
+
+import {
+  useEffect,
+  useRef,
+} from 'react'
+
+import { getSurfaceStateDescriptor } from '@modulify/m3-foundation/lib/surface/descriptor'
+import { m3MotionDurations } from '@modulify/m3-foundation/lib/motion'
+import {
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+import { useStateRef } from './useStateRef'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 32
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const DOCKED_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('docked_side_sheet')
+const MODAL_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('modal_side_sheet')
+const DOCKED_HOST_WIDTH = `clamp(${SIDE_SHEET_WIDTH_MIN}px, ${SIDE_SHEET_WIDTH_RATIO}%, ${SIDE_SHEET_WIDTH_MAX}px)`
+
+type ModalRole = 'surface-container-low' | 'surface-container-high'
+type SurfaceGeometry = {
+  width: number;
+  insetTop: number;
+  insetRight: number;
+  insetBottom: number;
+}
+
+type UseSurfaceSideSheetMorphResult = {
+  sideSheetModal: boolean;
+  sideSheetWidth: number;
+  transitioning: boolean;
+  modalShown: boolean;
+  dockedPanelShown: boolean;
+  dockedPanelStyle: CSSProperties;
+  modalPanelProps: {
+    shown: true;
+    scrimShown: boolean;
+    anchor: 'end';
+    fillWidth: false;
+    fillHeight: false;
+    width: number;
+    insetTop: number;
+    insetRight: number;
+    insetBottom: number;
+    roundingTopLeft: number;
+    roundingBottomLeft: number;
+    roundingTopRight: number;
+    roundingBottomRight: number;
+    transitionMs: number;
+    zIndex: number;
+    variant: ModalRole;
+    elevation: number;
+    overflow: 'auto';
+  };
+  dockedHostStyle: {
+    width: string;
+  };
+  dockedHostRef: MutableRefObject<HTMLDivElement | null>;
+  layoutRootRef: MutableRefObject<HTMLDivElement | null>;
+  toggleSideSheetMode: () => Promise<void>;
+  closeModalFromPanel: () => Promise<void>;
+}
+
+export function useSurfaceSideSheetMorph(): UseSurfaceSideSheetMorphResult {
+  const [sideSheetModal, setSideSheetModal, sideSheetModalRef] = useStateRef(false)
+  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(SIDE_SHEET_WIDTH_MIN)
+  const [dockedHostExpanded, setDockedHostExpanded, dockedHostExpandedRef] = useStateRef(true)
+  const [dockedPanelShown, setDockedPanelShown] = useStateRef(true)
+  const [dockedPanelHidden, setDockedPanelHidden] = useStateRef(false)
+  const [modalShown, setModalShown] = useStateRef(false)
+  const [modalScrimShown, setModalScrimShown] = useStateRef(false)
+  const [modalWidth, setModalWidth] = useStateRef(sideSheetWidthRef.current)
+  const [modalInsetTop, setModalInsetTop] = useStateRef(MODAL_INSET_TOP)
+  const [modalInsetRight, setModalInsetRight] = useStateRef(MODAL_INSET_END)
+  const [modalInsetBottom, setModalInsetBottom] = useStateRef(MODAL_INSET_BOTTOM)
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef<number>(DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+  const [modalElevation, setModalElevation] = useStateRef<number>(DOCKED_SIDE_SHEET_DESCRIPTOR.elevation)
+  const [modalRole, setModalRole] = useStateRef<ModalRole>(DOCKED_SIDE_SHEET_DESCRIPTOR.variant)
+  const [modalTransitionMs, setModalTransitionMs] = useStateRef<number>(PANEL_TRANSITION_MS)
+  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
+  const [lastDockedGeometry, setLastDockedGeometry, lastDockedGeometryRef] = useStateRef<SurfaceGeometry | null>(null)
+
+  const dockedHostRef = useRef<HTMLDivElement | null>(null)
+  const layoutRootRef = useRef<HTMLDivElement | null>(null)
+
+  const measureDockedGeometry = () => {
+    const host = dockedHostRef.current
+    if (!host) {
+      return null
+    }
+
+    const rect = host.getBoundingClientRect()
+    const width = Math.round(rect.width)
+
+    if (width > 0) {
+      setSideSheetWidth(width)
+    }
+
+    return {
+      width: width > 0 ? width : sideSheetWidthRef.current,
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+  }
+
+  const measureDockedPanelGeometry = (): SurfaceGeometry | null => {
+    const panel = dockedHostRef.current?.querySelector('[data-panel-mode="docked"]') as HTMLElement | null
+    if (!panel) {
+      return null
+    }
+
+    const rect = panel.getBoundingClientRect()
+    const geometry = {
+      width: Math.round(rect.width),
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+
+    setSideSheetWidth(geometry.width)
+    setLastDockedGeometry(geometry)
+
+    return geometry
+  }
+
+  const syncDockedGeometry = () => {
+    requestAnimationFrame(() => {
+      const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+      if (!docked || sideSheetModalRef.current) {
+        return
+      }
+
+      setModalWidth(docked.width)
+      setModalInsetTop(docked.insetTop)
+      setModalInsetRight(docked.insetRight)
+      setModalInsetBottom(docked.insetBottom)
+    })
+  }
+
+  const switchDockedToModal = async () => {
+    const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+    if (!docked) {
+      return
+    }
+
+    setModalTransitionMs(PANEL_TRANSITION_MS)
+    setModalWidth(docked.width)
+    setModalInsetTop(docked.insetTop)
+    setModalInsetRight(docked.insetRight)
+    setModalInsetBottom(docked.insetBottom)
+    setModalRadiusLeft(DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+    setModalElevation(DOCKED_SIDE_SHEET_DESCRIPTOR.elevation)
+    setModalRole(DOCKED_SIDE_SHEET_DESCRIPTOR.variant)
+    setDockedPanelShown(true)
+    setDockedPanelHidden(true)
+    setModalShown(true)
+
+    await raf()
+
+    setModalScrimShown(MODAL_SIDE_SHEET_DESCRIPTOR.scrim)
+    setDockedHostExpanded(false)
+    setSideSheetModal(true)
+    setModalWidth(docked.width)
+    setModalInsetTop(MODAL_INSET_TOP)
+    setModalInsetRight(MODAL_INSET_END)
+    setModalInsetBottom(MODAL_INSET_BOTTOM)
+    setModalRadiusLeft(MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+    setModalElevation(MODAL_SIDE_SHEET_DESCRIPTOR.elevation)
+    setModalRole(MODAL_SIDE_SHEET_DESCRIPTOR.variant)
+
+    await wait(PANEL_TRANSITION_MS)
+
+    setDockedPanelShown(false)
+  }
+
+  const switchModalToDocked = async () => {
+    setDockedHostExpanded(true)
+    setDockedPanelShown(true)
+    setDockedPanelHidden(true)
+
+    await raf()
+
+    const dockedTarget = lastDockedGeometryRef.current ?? measureDockedPanelGeometry() ?? measureDockedGeometry()
+    if (!dockedTarget) {
+      return
+    }
+
+    setModalTransitionMs(PANEL_TRANSITION_MS)
+    setModalScrimShown(false)
+    setModalElevation(DOCKED_SIDE_SHEET_DESCRIPTOR.elevation)
+    setModalRole(DOCKED_SIDE_SHEET_DESCRIPTOR.variant)
+    setModalRadiusLeft(DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+    setModalWidth(dockedTarget.width)
+    setModalInsetTop(dockedTarget.insetTop)
+    setModalInsetRight(dockedTarget.insetRight)
+    setModalInsetBottom(dockedTarget.insetBottom)
+
+    await wait(PANEL_TRANSITION_MS)
+
+    setSideSheetModal(false)
+    setModalShown(false)
+    setDockedPanelHidden(false)
+  }
+
+  const toggleSideSheetMode = async () => {
+    if (transitioningRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+
+    if (!sideSheetModalRef.current) {
+      await switchDockedToModal()
+      setTransitioning(false)
+      return
+    }
+
+    await switchModalToDocked()
+    setTransitioning(false)
+  }
+
+  const closeModalFromPanel = async () => {
+    if (!sideSheetModalRef.current || transitioningRef.current) {
+      return
+    }
+
+    setTransitioning(true)
+    await switchModalToDocked()
+    setTransitioning(false)
+  }
+
+  useEffect(() => {
+    const onResize = () => {
+      if (dockedHostExpandedRef.current) {
+        syncDockedGeometry()
+      }
+    }
+
+    syncDockedGeometry()
+    window.addEventListener('resize', onResize, { passive: true })
+
+    return () => {
+      window.removeEventListener('resize', onResize)
+    }
+  }, [])
+
+  return {
+    sideSheetModal,
+    sideSheetWidth,
+    transitioning,
+    modalShown,
+    dockedPanelShown,
+    dockedPanelStyle: {
+      visibility: dockedPanelHidden ? 'hidden' : 'visible',
+    },
+    modalPanelProps: {
+      shown: true,
+      scrimShown: modalScrimShown,
+      anchor: MODAL_SIDE_SHEET_DESCRIPTOR.anchor,
+      fillWidth: MODAL_SIDE_SHEET_DESCRIPTOR.fillWidth,
+      fillHeight: MODAL_SIDE_SHEET_DESCRIPTOR.fillHeight,
+      width: modalWidth,
+      insetTop: modalInsetTop,
+      insetRight: modalInsetRight,
+      insetBottom: modalInsetBottom,
+      roundingTopLeft: modalRadiusLeft,
+      roundingBottomLeft: modalRadiusLeft,
+      roundingTopRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight,
+      roundingBottomRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight,
+      transitionMs: modalTransitionMs,
+      zIndex: 520,
+      variant: modalRole,
+      elevation: modalElevation,
+      overflow: MODAL_SIDE_SHEET_DESCRIPTOR.overflow,
+    },
+    dockedHostStyle: {
+      width: dockedHostExpanded ? DOCKED_HOST_WIDTH : '0px',
+    },
+    dockedHostRef,
+    layoutRootRef,
+    toggleSideSheetMode,
+    closeModalFromPanel,
+  }
+}
diff --git a/m3-react/src/components/surface/shared.ts b/m3-react/src/components/surface/shared.ts
new file mode 100644
index 0000000..1753352
--- /dev/null
+++ b/m3-react/src/components/surface/shared.ts
@@ -0,0 +1,82 @@
+import type {
+  CSSProperties,
+  HTMLAttributes,
+} from 'react'
+import type {
+  Length as SurfaceLength,
+  Variant as SurfaceVariant,
+} from '@modulify/m3-foundation/types/components/surface'
+
+import {
+  getSurfacePanelClassRecord,
+  getSurfacePanelStyle as getFoundationSurfacePanelStyle,
+} from '@modulify/m3-foundation/lib/surface/style'
+
+export {
+  DEFAULT_SURFACE_TRANSITION_TIMING,
+  getModalAnchorStyle,
+  getResolvedVariant,
+  getSurfaceTransition,
+  getVariantClassName,
+  isDefined,
+  toLength,
+} from '@modulify/m3-foundation/lib/surface/style'
+
+import { toClassName } from '@/utils/styling'
+
+export type M3SurfacePanelVariant = SurfaceVariant
+
+export interface M3SurfacePanelProps extends HTMLAttributes<HTMLElement> {
+  id?: string;
+  tag?: keyof HTMLElementTagNameMap;
+  elevation?: number;
+  variant?: M3SurfacePanelVariant;
+  fillWidth?: boolean;
+  fillHeight?: boolean;
+  width?: SurfaceLength | null;
+  height?: SurfaceLength | null;
+  minWidth?: SurfaceLength | null;
+  maxWidth?: SurfaceLength | null;
+  minHeight?: SurfaceLength | null;
+  maxHeight?: SurfaceLength | null;
+  rounding?: SurfaceLength;
+  roundingTopLeft?: SurfaceLength | null;
+  roundingTopRight?: SurfaceLength | null;
+  roundingBottomRight?: SurfaceLength | null;
+  roundingBottomLeft?: SurfaceLength | null;
+  transitionMs?: number;
+  transitionTiming?: string;
+  overflow?: CSSProperties['overflow'];
+}
+
+export const getSurfacePanelClassName = ({
+  className = '',
+  elevation = 0,
+  variant = 'auto',
+}: Pick<M3SurfacePanelProps, 'className' | 'elevation' | 'variant'>): string => {
+  return toClassName([className, getSurfacePanelClassRecord(elevation, variant)])
+}
+
+export const getSurfacePanelStyle = (options: Pick<
+  M3SurfacePanelProps,
+  | 'fillWidth'
+  | 'fillHeight'
+  | 'width'
+  | 'height'
+  | 'minWidth'
+  | 'maxWidth'
+  | 'minHeight'
+  | 'maxHeight'
+  | 'rounding'
+  | 'roundingTopLeft'
+  | 'roundingTopRight'
+  | 'roundingBottomRight'
+  | 'roundingBottomLeft'
+  | 'transitionMs'
+  | 'transitionTiming'
+  | 'overflow'
+  | 'style'
+>): CSSProperties => getFoundationSurfacePanelStyle({
+  ...options,
+  style: options.style as object | undefined,
+}) as CSSProperties
diff --git a/m3-react/src/index.ts b/m3-react/src/index.ts
index 0491e4f..2f47713 100644
--- a/m3-react/src/index.ts
+++ b/m3-react/src/index.ts
@@ -84,6 +84,8 @@ export type {
 export type {
   M3SurfaceAnchor,
   M3SurfaceMode,
+  M3SurfacePanelProps,
+  M3SurfacePanelVariant,
   M3SurfaceProps,
   M3SurfaceVariant,
 } from '@/components/surface'
@@ -158,6 +160,7 @@ export {
 } from '@/components/side-sheet'
 
 export {
+  M3SurfacePanel,
   M3Surface,
 } from '@/components/surface'
 
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
index 5650ce0..b4221ec 100644
--- a/m3-react/storybook/components/M3Surface.mdx
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -5,6 +5,8 @@ import * as M3SurfaceStories from './M3Surface.stories'
 
 # Surfaces
 
+Use `M3SurfacePanel` for static decorative surfaces such as cards, docs wrappers, and nested surface blocks. Reserve `M3Surface` for modal behavior and richer container orchestration.
+
 - [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
 - [Card Replacing Page](?path=/story/components-m3surface--card-replacing-page)
 - [Side Sheet Modal Dismiss Removes Surface](?path=/story/components-m3surface--side-sheet-modal-dismiss-removes-surface)
diff --git a/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx b/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
index 76ba141..aaee138 100644
--- a/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceCardPageMorph.tsx
@@ -1,5 +1,4 @@
 import type {
-  CSSProperties,
   FC,
 } from 'react'
 
@@ -10,174 +9,75 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import { M3Surface } from '@/components/surface'
+import { M3SurfacePanel } from '@/components/surface'
+import { useSurfaceCardPageMorph } from '@/components/surface/orchestration/useSurfaceCardPageMorph'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
 import {
   m3MotionDurations,
   m3MotionEasings,
 } from '@modulify/m3-foundation/lib/motion'
 
-import {
-  useEffect,
-  useRef,
-} from 'react'
-
 import { toClassName } from '@/utils/styling'
 
-import {
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
 const TRANSITION_MS = m3MotionDurations.medium3
 const TRANSITION_EASING = m3MotionEasings.standard
 
 type NavTab = 'files' | 'timeline' | 'tasks' | 'analytics'
 
-type Motion = {
-  top: number;
-  left: number;
-  width: number;
-  height: number;
-}
-
 const SurfaceCardPageMorph: FC = () => {
-  const [expanded, setExpanded, expandedRef] = useStateRef(false)
-  const [busy, setBusy, busyRef] = useStateRef(false)
   const [navExpanded, setNavExpanded] = useStateRef(false)
-  const [backgroundCollapsed, setBackgroundCollapsed] = useStateRef(false)
   const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('files')
-  const [originHeight, setOriginHeight] = useStateRef(220)
-
-  const [motion, setMotion] = useStateRef<Motion>({
-    top: 16,
-    left: 16,
-    width: 320,
-    height: 220,
-  })
-
-  const canvas = useRef<HTMLDivElement | null>(null)
-  const originSlot = useRef<HTMLDivElement | null>(null)
-
-  const overlayStyle: CSSProperties = {
-    top: `${motion.top}px`,
-    left: `${motion.left}px`,
-    width: `${motion.width}px`,
-    height: `${motion.height}px`,
-  }
-
-  const measureOrigin = (): Motion | null => {
-    if (!canvas.current || !originSlot.current) {
-      return null
-    }
-
-    const canvasRect = canvas.current.getBoundingClientRect()
-    const originRect = originSlot.current.getBoundingClientRect()
-
-    return {
-      top: originRect.top - canvasRect.top,
-      left: originRect.left - canvasRect.left,
-      width: originRect.width,
-      height: originRect.height,
-    }
-  }
-
-  const measureExpanded = (): Motion | null => {
-    if (!canvas.current) {
-      return null
-    }
-
-    const canvasRect = canvas.current.getBoundingClientRect()
-
-    return {
-      top: 0,
-      left: 0,
-      width: canvasRect.width,
-      height: canvasRect.height,
-    }
-  }
-
-  const initMotion = async () => {
-    await raf()
-
-    const origin = measureOrigin()
-    if (!origin) {
-      return
-    }
-
-    setMotion(origin)
-    setOriginHeight(origin.height)
-  }
-
-  const expandCard = async () => {
-    setBackgroundCollapsed(false)
-
-    const origin = measureOrigin()
-    if (origin) {
-      setMotion(origin)
-      setOriginHeight(origin.height)
-    }
-
-    setExpanded(true)
-    await raf()
-
-    const full = measureExpanded()
-    if (!full) {
-      return
-    }
-
-    setMotion(full)
-    await wait(TRANSITION_MS)
-    setBackgroundCollapsed(true)
-  }
-
-  const collapseCard = async () => {
-    if (backgroundCollapsed) {
-      setBackgroundCollapsed(false)
-      await raf()
-    }
-
-    const full = measureExpanded()
-    if (full) {
-      setMotion(full)
-    }
-
-    const origin = measureOrigin()
-    if (origin) {
-      setOriginHeight(origin.height)
-    }
-
-    setExpanded(false)
-    await raf()
-
-    if (!origin) {
-      return
-    }
-
-    setMotion(origin)
-    await wait(TRANSITION_MS)
-  }
-
-  const toggleCardMode = async () => {
-    if (busyRef.current) {
-      return
-    }
-
-    setBusy(true)
-
-    if (expandedRef.current) {
-      await collapseCard()
-      setBusy(false)
-      return
-    }
-
-    await expandCard()
-    setBusy(false)
-  }
-
-  useEffect(() => {
-    void initMotion()
-  }, [])
+  const {
+    expanded,
+    busy,
+    backgroundCollapsed,
+    originHeight,
+    overlayStyle,
+    canvasRef: canvas,
+    originSlotRef: originSlot,
+    toggleCardMode,
+  } = useSurfaceCardPageMorph(TRANSITION_MS)
+  const overlayActive = busy || expanded
+  const compactWrapStyle = {
+    width: '100%',
+  } as const
+
+  const morphSurfaceNode = (
+    <M3SurfacePanel
+      className={toClassName([
+        'surface-card-page__morph-surface',
+        expanded
+          ? 'surface-card-page__morph-surface_expanded'
+          : 'surface-card-page__morph-surface_compact',
+      ])}
+      fillWidth={true}
+      fillHeight={overlayActive}
+      rounding={expanded ? 0 : 24}
+      transitionMs={TRANSITION_MS}
+      transitionTiming={TRANSITION_EASING}
+      variant={expanded ? 'surface' : 'surface-container-low'}
+      elevation={expanded ? 0 : 1}
+      overflow="auto"
+      data-testid="surface-card-morph"
+    >
+      <h3>Morph target surface</h3>
+      <p>
+        In compact mode this surface behaves like a card. In expanded mode it replaces the
+        page work area while keeping top bar and rail reserved.
+      </p>
+
+      <M3SurfacePanel
+        className="surface-card-page__morph-nested"
+        fillHeight={false}
+        height={120}
+        rounding={14}
+        variant={expanded ? 'surface-container-low' : 'surface-container-high'}
+        elevation={expanded ? 1 : 3}
+      >
+        Nested surface demonstrates composability in both states.
+      </M3SurfacePanel>
+    </M3SurfacePanel>
+  )
 
   return (
     <div
@@ -185,7 +85,7 @@ const SurfaceCardPageMorph: FC = () => {
       data-card-expanded={expanded ? 'true' : 'false'}
       data-testid="surface-card-page-root"
     >
-      <M3Surface
+      <M3SurfacePanel
         className="surface-card-page__topbar"
         fillHeight={false}
         height={72}
@@ -207,7 +107,7 @@ const SurfaceCardPageMorph: FC = () => {
             {expanded ? 'Return to card state' : 'Expand card to page state'}
           </M3Button>
         </div>
-      </M3Surface>
+      </M3SurfacePanel>
 
       <M3Navigation
         expanded={navExpanded}
@@ -272,7 +172,7 @@ const SurfaceCardPageMorph: FC = () => {
 
       <div className="surface-card-page__body">
         <div className="surface-card-page__workspace">
-          <M3Surface
+          <M3SurfacePanel
             className="surface-card-page__header-card"
             fillHeight={false}
             height={120}
@@ -282,7 +182,7 @@ const SurfaceCardPageMorph: FC = () => {
           >
             <h3>Card-to-page transition playground</h3>
             <p>Original slot remains reserved while the morphing surface overlays the page area.</p>
-          </M3Surface>
+          </M3SurfacePanel>
 
           <div
             ref={canvas}
@@ -296,12 +196,27 @@ const SurfaceCardPageMorph: FC = () => {
               >
                 <div
                   ref={originSlot}
-                  className="surface-card-page__origin-slot"
-                  style={{ minHeight: `${originHeight}px` }}
+                  className={toClassName([
+                    'surface-card-page__origin-slot',
+                    {
+                      'surface-card-page__origin-slot_filled': !overlayActive,
+                    },
+                  ])}
+                  style={overlayActive ? { minHeight: `${originHeight}px` } : undefined}
                   data-testid="surface-card-origin"
-                />
-
-                <M3Surface
+                >
+                  {!overlayActive ? (
+                    <div
+                      className="surface-card-page__overlay-wrap surface-card-page__overlay-wrap_inline"
+                      style={compactWrapStyle}
+                      data-testid="surface-card-overlay-wrap"
+                    >
+                      {morphSurfaceNode}
+                    </div>
+                  ) : null}
+                </div>
+
+                <M3SurfacePanel
                   className="surface-card-page__grid-card"
                   fillHeight={false}
                   height={184}
@@ -311,9 +226,9 @@ const SurfaceCardPageMorph: FC = () => {
                 >
                   <strong>Static card A</strong>
                   <p>Background content remains in flow.</p>
-                </M3Surface>
+                </M3SurfacePanel>
 
-                <M3Surface
+                <M3SurfacePanel
                   className="surface-card-page__grid-card"
                   fillHeight={false}
                   height={184}
@@ -323,52 +238,21 @@ const SurfaceCardPageMorph: FC = () => {
                 >
                   <strong>Static card B</strong>
                   <p>Independent surface in the same scene.</p>
-                </M3Surface>
+                </M3SurfacePanel>
               </div>
             ) : null}
 
-            <div className="surface-card-page__overlay">
-              <div
-                className="surface-card-page__overlay-wrap"
-                style={overlayStyle}
-                data-testid="surface-card-overlay-wrap"
-              >
-                <M3Surface
-                  className={toClassName([
-                    'surface-card-page__morph-surface',
-                    expanded
-                      ? 'surface-card-page__morph-surface_expanded'
-                      : 'surface-card-page__morph-surface_compact',
-                  ])}
-                  fillWidth={true}
-                  fillHeight={true}
-                  rounding={expanded ? 0 : 24}
-                  transitionMs={TRANSITION_MS}
-                  transitionTiming={TRANSITION_EASING}
-                  variant={expanded ? 'surface' : 'surface-container-low'}
-                  elevation={expanded ? 0 : 1}
-                  overflow="auto"
-                  data-testid="surface-card-morph"
+            {overlayActive ? (
+              <div className="surface-card-page__overlay">
+                <div
+                  className="surface-card-page__overlay-wrap"
+                  style={overlayStyle}
+                  data-testid="surface-card-overlay-wrap"
                 >
-                  <h3>Morph target surface</h3>
-                  <p>
-                    In compact mode this surface behaves like a card. In expanded mode it replaces the
-                    page work area while keeping top bar and rail reserved.
-                  </p>
-
-                  <M3Surface
-                    className="surface-card-page__morph-nested"
-                    fillHeight={false}
-                    height={120}
-                    rounding={14}
-                    variant={expanded ? 'surface-container-low' : 'surface-container-high'}
-                    elevation={expanded ? 1 : 3}
-                  >
-                    Nested surface demonstrates composability in both states.
-                  </M3Surface>
-                </M3Surface>
+                  {morphSurfaceNode}
+                </div>
               </div>
-            </div>
+            ) : null}
           </div>
         </div>
       </div>
diff --git a/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
index a3f27a1..37aad3d 100644
--- a/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
@@ -11,18 +11,17 @@ import {
   M3NavigationTab,
 } from '@/components/navigation'
 import { M3Surface } from '@/components/surface'
+import {
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   m3MotionDurations,
   m3MotionEasings,
 } from '@modulify/m3-foundation/lib/motion'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
 import { toClassName } from '@/utils/styling'
 
-import {
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
 const DIALOG_TRANSITION_MS = m3MotionDurations.medium2
 const DIALOG_TRANSITION_EASING = m3MotionEasings.standard
 const DIALOG_ENTRY_OFFSET_PX = 24
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
index f997052..a83717e 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
@@ -8,6 +8,12 @@ import {
   M3NavigationTab,
 } from '@/components/navigation'
 import { M3Surface } from '@/components/surface'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   m3MotionDurations,
   m3MotionEasings,
@@ -18,13 +24,6 @@ import {
   useRef,
 } from 'react'
 
-import {
-  clamp,
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
 const SIDE_SHEET_WIDTH_RATIO = 0.32
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
index ed84dba..47dcd1f 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
@@ -8,6 +8,12 @@ import {
   M3NavigationTab,
 } from '@/components/navigation'
 import { M3Surface } from '@/components/surface'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   m3MotionDurations,
   m3MotionEasings,
@@ -18,13 +24,6 @@ import {
   useRef,
 } from 'react'
 
-import {
-  clamp,
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
 const SIDE_SHEET_WIDTH_RATIO = 0.32
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
index 7969c83..7f3b3ac 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
@@ -13,8 +13,18 @@ import {
   M3NavigationTab,
 } from '@/components/navigation'
 import { M3Select } from '@/components/select'
-import { M3Surface } from '@/components/surface'
+import {
+  M3Surface,
+  M3SurfacePanel,
+} from '@/components/surface'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import { M3TextField } from '@/components/text-field'
+import { getSurfaceStateDescriptor } from '@modulify/m3-foundation/lib/surface/descriptor'
 import {
   m3MotionDurations,
   m3MotionEasings,
@@ -27,13 +37,6 @@ import {
 
 import { toClassName } from '@/utils/styling'
 
-import {
-  clamp,
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
 const SIDE_SHEET_WIDTH_MIN = 280
 const SIDE_SHEET_WIDTH_MAX = 360
 const SIDE_SHEET_WIDTH_RATIO = 0.32
@@ -51,6 +54,9 @@ const PANEL_TRANSITION_MS = m3MotionDurations.medium4
 const PANEL_TRANSITION_EASING = m3MotionEasings.standard
 const SCRIM_FADE_MS = m3MotionDurations.long2
 const DIALOG_HIDE_MS = m3MotionDurations.long2
+const HIDDEN_SURFACE_DESCRIPTOR = getSurfaceStateDescriptor('hidden')
+const MODAL_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('modal_side_sheet')
+const MODAL_DIALOG_DESCRIPTOR = getSurfaceStateDescriptor('modal_dialog_window')
 
 type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
 type Priority = 'low' | 'normal' | 'high'
@@ -89,8 +95,8 @@ const SurfaceSideSheetModalToWindow: FC = () => {
   const [windowWidth, setWindowWidth] = useStateRef(720)
 
   const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
-  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
-  const [modalElevationBase, setModalElevationBase] = useStateRef(0)
+  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft)
+  const [modalElevationBase, setModalElevationBase] = useStateRef(HIDDEN_SURFACE_DESCRIPTOR.elevation)
 
   const [modalMounted, setModalMounted, modalMountedRef] = useStateRef(false)
   const [modalVisible, setModalVisible] = useStateRef(false)
@@ -101,15 +107,21 @@ const SurfaceSideSheetModalToWindow: FC = () => {
 
   const layoutRoot = useRef<HTMLDivElement | null>(null)
 
-  const panelAnchor = panelAsWindow ? 'center' : 'end'
+  const panelAnchor = panelAsWindow ? MODAL_DIALOG_DESCRIPTOR.anchor : MODAL_SIDE_SHEET_DESCRIPTOR.anchor
   const panelWidth = panelAsWindow ? windowWidth : sideSheetWidth
   const panelInsetRight = panelAsWindow ? 0 : modalInsetRight
-  const panelRoundingTopLeft = panelAsWindow ? 28 : modalRadiusLeft
-  const panelRoundingBottomLeft = panelAsWindow ? 28 : modalRadiusLeft
-  const panelRoundingTopRight = panelAsWindow ? 28 : 0
-  const panelRoundingBottomRight = panelAsWindow ? 28 : 0
-  const panelSurfaceRole = panelAsWindow ? 'surface-container-highest' : 'surface-container-high'
-  const panelElevation = panelAsWindow ? Math.max(2, modalElevationBase) : modalElevationBase
+  const panelRoundingTopLeft = panelAsWindow ? MODAL_DIALOG_DESCRIPTOR.rounding.topLeft : modalRadiusLeft
+  const panelRoundingBottomLeft = panelAsWindow ? MODAL_DIALOG_DESCRIPTOR.rounding.bottomLeft : modalRadiusLeft
+  const panelRoundingTopRight = panelAsWindow
+    ? MODAL_DIALOG_DESCRIPTOR.rounding.topRight
+    : MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight
+  const panelRoundingBottomRight = panelAsWindow
+    ? MODAL_DIALOG_DESCRIPTOR.rounding.bottomRight
+    : MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight
+  const panelSurfaceRole = panelAsWindow ? MODAL_DIALOG_DESCRIPTOR.variant : MODAL_SIDE_SHEET_DESCRIPTOR.variant
+  const panelElevation = panelAsWindow
+    ? Math.max(MODAL_DIALOG_DESCRIPTOR.elevation, modalElevationBase)
+    : modalElevationBase
   const panelTransitionMs = panelAsWindow && windowClosing
     ? DIALOG_HIDE_MS
     : PANEL_TRANSITION_MS
@@ -156,8 +168,8 @@ const SurfaceSideSheetModalToWindow: FC = () => {
     setWindowClosing(false)
     syncDimensions()
 
-    setModalRadiusLeft(0)
-    setModalElevationBase(0)
+    setModalRadiusLeft(HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft)
+    setModalElevationBase(HIDDEN_SURFACE_DESCRIPTOR.elevation)
     setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
     setModalMounted(true)
 
@@ -167,8 +179,8 @@ const SurfaceSideSheetModalToWindow: FC = () => {
     await raf()
 
     setModalInsetRight(MODAL_INSET_END)
-    setModalRadiusLeft(28)
-    setModalElevationBase(1)
+    setModalRadiusLeft(MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+    setModalElevationBase(MODAL_SIDE_SHEET_DESCRIPTOR.elevation)
     await wait(PANEL_TRANSITION_MS)
     setTransitioning(false)
   }
@@ -201,16 +213,16 @@ const SurfaceSideSheetModalToWindow: FC = () => {
     setModalMounted(false)
 
     setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
-    setModalRadiusLeft(0)
-    setModalElevationBase(0)
+    setModalRadiusLeft(HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft)
+    setModalElevationBase(HIDDEN_SURFACE_DESCRIPTOR.elevation)
     setWindowClosing(false)
     setPanelAsWindow(false)
   }
 
   const closeSideSheetModal = async () => {
     setModalInsetRight(hiddenInsetRight(sideSheetWidthRef.current))
-    setModalRadiusLeft(0)
-    setModalElevationBase(0)
+    setModalRadiusLeft(HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft)
+    setModalElevationBase(HIDDEN_SURFACE_DESCRIPTOR.elevation)
     await wait(PANEL_TRANSITION_MS)
 
     setModalVisible(false)
@@ -259,7 +271,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
       data-panel-mounted={modalMounted ? 'true' : 'false'}
       data-testid="surface-window-root"
     >
-      <M3Surface
+      <M3SurfacePanel
         className="surface-side-sheet-window__topbar"
         fillHeight={false}
         height={72}
@@ -281,7 +293,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
             {modalMounted ? 'Modal panel is open' : 'Show modal side sheet'}
           </M3Button>
         </div>
-      </M3Surface>
+      </M3SurfacePanel>
 
       <M3Navigation
         expanded={navExpanded}
@@ -346,7 +358,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
 
       <div className="surface-side-sheet-window__body">
         <div className="surface-side-sheet-window__workspace">
-          <M3Surface
+          <M3SurfacePanel
             className="surface-side-sheet-window__header-card"
             fillHeight={false}
             height={120}
@@ -356,7 +368,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
           >
             <h3>Workspace surfaces</h3>
             <p>Background layout stays in flow while the modal panel morphs between side-sheet and window geometries.</p>
-          </M3Surface>
+          </M3SurfacePanel>
 
           <div
             ref={layoutRoot}
@@ -367,7 +379,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
               className="surface-side-sheet-window__content-grid"
               data-testid="surface-window-content-grid"
             >
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet-window__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -377,9 +389,9 @@ const SurfaceSideSheetModalToWindow: FC = () => {
               >
                 <strong>surface-container-lowest</strong>
                 <p>Read-heavy content block in the page flow.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet-window__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -389,9 +401,9 @@ const SurfaceSideSheetModalToWindow: FC = () => {
               >
                 <strong>surface-container-low</strong>
                 <p>Secondary block with mild emphasis.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet-window__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -401,9 +413,9 @@ const SurfaceSideSheetModalToWindow: FC = () => {
               >
                 <strong>surface-container-high</strong>
                 <p>Contextual utility content.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet-window__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -413,7 +425,7 @@ const SurfaceSideSheetModalToWindow: FC = () => {
               >
                 <strong>surface-dim</strong>
                 <p>Low-brightness complementary content.</p>
-              </M3Surface>
+              </M3SurfacePanel>
             </main>
 
             {modalMounted ? (
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
index a8e72ea..2c4b752 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetMorph.tsx
@@ -7,236 +7,37 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import { M3Surface } from '@/components/surface'
 import {
-  m3MotionDurations,
+  M3Surface,
+  M3SurfacePanel,
+} from '@/components/surface'
+import { useSurfaceSideSheetMorph } from '@/components/surface/orchestration/useSurfaceSideSheetMorph'
+import {
   m3MotionEasings,
 } from '@modulify/m3-foundation/lib/motion'
+import { useStateRef } from '@/components/surface/orchestration/useStateRef'
 
-import {
-  useEffect,
-  useRef,
-} from 'react'
-
-import {
-  clamp,
-  raf,
-  useStateRef,
-  wait,
-} from './utils'
-
-const SIDE_SHEET_WIDTH_MIN = 280
-const SIDE_SHEET_WIDTH_MAX = 360
-const SIDE_SHEET_WIDTH_RATIO = 0.32
-const SIDE_SHEET_WIDTH_STEP = 4
-
-const MODAL_INSET_TOP = 0
-const MODAL_INSET_BOTTOM = 0
-const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = m3MotionDurations.medium2
-const PANEL_VERTICAL_EXPAND_MS = 120
 const PANEL_TRANSITION_EASING = m3MotionEasings.standard
 
 type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
-type ModalRole = 'surface-container-low' | 'surface-container-high'
 
 const SurfaceSideSheetMorph: FC = () => {
   const [navExpanded, setNavExpanded] = useStateRef(false)
   const [activeNavTab, setActiveNavTab] = useStateRef<NavTab>('inbox')
-  const [sideSheetModal, setSideSheetModal, sideSheetModalRef] = useStateRef(false)
-  const [sideSheetWidth, setSideSheetWidth, sideSheetWidthRef] = useStateRef(320)
-  const [sideSheetDockedWidth, setSideSheetDockedWidth] = useStateRef(sideSheetWidthRef.current)
-  const [modalShown, setModalShown] = useStateRef(false)
-  const [modalVisible, setModalVisible] = useStateRef(false)
-  const [modalWidth, setModalWidth, modalWidthRef] = useStateRef(sideSheetWidthRef.current)
-  const [modalInsetTop, setModalInsetTop] = useStateRef(MODAL_INSET_TOP)
-  const [modalInsetRight, setModalInsetRight] = useStateRef(-(sideSheetWidthRef.current + 12))
-  const [modalInsetBottom, setModalInsetBottom] = useStateRef(MODAL_INSET_BOTTOM)
-  const [modalRadiusLeft, setModalRadiusLeft] = useStateRef(0)
-  const [modalElevation, setModalElevation] = useStateRef(0)
-  const [modalRole, setModalRole] = useStateRef<ModalRole>('surface-container-low')
-  const [modalTransitionMs, setModalTransitionMs] = useStateRef(PANEL_TRANSITION_MS)
-  const [transitioning, setTransitioning, transitioningRef] = useStateRef(false)
-
-  const dockedHost = useRef<HTMLDivElement | null>(null)
-  const layoutRoot = useRef<HTMLDivElement | null>(null)
-
-  const hiddenInsetRight = (width: number) => -(width + 12)
-
-  const resolveSheetWidthFromLayout = () => {
-    const layoutWidth = Math.round(layoutRoot.current?.getBoundingClientRect().width ?? window.innerWidth)
-    const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
-
-    return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
-  }
-
-  const syncFixedWidth = () => {
-    const nextWidth = resolveSheetWidthFromLayout()
-
-    setSideSheetWidth(nextWidth)
-    setModalWidth(nextWidth)
-
-    if (!sideSheetModalRef.current) {
-      setSideSheetDockedWidth(nextWidth)
-      setModalInsetRight(hiddenInsetRight(nextWidth))
-    }
-
-    return nextWidth
-  }
-
-  const measureDockedGeometry = () => {
-    const host = dockedHost.current
-    if (!host) {
-      return null
-    }
-
-    const rect = host.getBoundingClientRect()
-
-    return {
-      width: Math.round(rect.width),
-      insetTop: Math.round(rect.top),
-      insetRight: Math.round(window.innerWidth - rect.right),
-      insetBottom: Math.round(window.innerHeight - rect.bottom),
-    }
-  }
-
-  const setModalGeometryFromDocked = (fallbackWidth: number) => {
-    const docked = measureDockedGeometry()
-
-    setModalWidth(docked?.width ?? fallbackWidth)
-    setModalInsetTop(docked?.insetTop ?? MODAL_INSET_TOP)
-    setModalInsetRight(docked?.insetRight ?? MODAL_INSET_END)
-    setModalInsetBottom(docked?.insetBottom ?? MODAL_INSET_BOTTOM)
-  }
-
-  const setModalGeometryTarget = (width: number) => {
-    setModalWidth(width)
-    setModalInsetTop(MODAL_INSET_TOP)
-    setModalInsetRight(MODAL_INSET_END)
-    setModalInsetBottom(MODAL_INSET_BOTTOM)
-  }
-
-  const expandModalToViewportHeight = async (width: number) => {
-    setModalTransitionMs(PANEL_VERTICAL_EXPAND_MS)
-    await raf()
-    setModalGeometryTarget(width)
-    await wait(PANEL_VERTICAL_EXPAND_MS)
-    setModalTransitionMs(PANEL_TRANSITION_MS)
-  }
-
-  const resolveDockedTargetGeometry = (width: number) => {
-    const layout = layoutRoot.current?.getBoundingClientRect()
-
-    if (!layout) {
-      return {
-        width,
-        insetTop: MODAL_INSET_TOP,
-        insetRight: MODAL_INSET_END,
-        insetBottom: MODAL_INSET_BOTTOM,
-      }
-    }
-
-    return {
-      width,
-      insetTop: Math.round(layout.top),
-      insetRight: Math.round(window.innerWidth - layout.right),
-      insetBottom: Math.round(window.innerHeight - layout.bottom),
-    }
-  }
-
-  const switchDockedToModal = async () => {
-    const nextWidth = syncFixedWidth()
-    setModalGeometryFromDocked(nextWidth)
-
-    setModalTransitionMs(PANEL_TRANSITION_MS)
-    setModalRadiusLeft(0)
-    setModalElevation(0)
-    setModalRole('surface-container-low')
-    setModalVisible(false)
-    setModalShown(true)
-
-    await raf()
-
-    setModalVisible(true)
-    await raf()
-
-    setSideSheetModal(true)
-    setSideSheetDockedWidth(0)
-    setModalWidth(nextWidth)
-    setModalInsetRight(MODAL_INSET_END)
-    setModalRadiusLeft(28)
-    setModalElevation(1)
-    setModalRole('surface-container-high')
-    await wait(PANEL_TRANSITION_MS)
-
-    await expandModalToViewportHeight(nextWidth)
-  }
-
-  const switchModalToDocked = async () => {
-    const nextWidth = syncFixedWidth()
-    const dockedTarget = resolveDockedTargetGeometry(nextWidth)
-
-    setModalTransitionMs(PANEL_TRANSITION_MS)
-    setModalElevation(0)
-    setModalRole('surface-container-low')
-    setModalRadiusLeft(0)
-
-    setSideSheetDockedWidth(nextWidth)
-    setModalWidth(dockedTarget.width)
-    setModalInsetTop(dockedTarget.insetTop)
-    setModalInsetRight(dockedTarget.insetRight)
-    setModalInsetBottom(dockedTarget.insetBottom)
-
-    await wait(PANEL_TRANSITION_MS)
-
-    setSideSheetModal(false)
-    setModalVisible(false)
-    setModalShown(false)
-
-    setModalInsetTop(MODAL_INSET_TOP)
-    setModalInsetRight(hiddenInsetRight(nextWidth))
-    setModalInsetBottom(MODAL_INSET_BOTTOM)
-  }
-
-  const toggleSideSheetMode = async () => {
-    if (transitioningRef.current) {
-      return
-    }
-
-    setTransitioning(true)
-
-    if (!sideSheetModalRef.current) {
-      await switchDockedToModal()
-      setTransitioning(false)
-      return
-    }
-
-    await switchModalToDocked()
-    setTransitioning(false)
-  }
-
-  const closeModalFromPanel = async () => {
-    if (!sideSheetModalRef.current || transitioningRef.current) {
-      return
-    }
-
-    setTransitioning(true)
-    await switchModalToDocked()
-    setTransitioning(false)
-  }
-
-  useEffect(() => {
-    const onResize = () => {
-      syncFixedWidth()
-    }
-
-    syncFixedWidth()
-    window.addEventListener('resize', onResize, { passive: true })
-
-    return () => {
-      window.removeEventListener('resize', onResize)
-    }
-  }, [])
+  const {
+    sideSheetModal,
+    sideSheetWidth,
+    transitioning,
+    modalShown,
+    dockedPanelShown,
+    dockedPanelStyle,
+    modalPanelProps,
+    dockedHostStyle,
+    dockedHostRef: dockedHost,
+    layoutRootRef: layoutRoot,
+    toggleSideSheetMode,
+    closeModalFromPanel,
+  } = useSurfaceSideSheetMorph()
 
   return (
     <div
@@ -244,7 +45,7 @@ const SurfaceSideSheetMorph: FC = () => {
       data-sheet-modal={sideSheetModal ? 'true' : 'false'}
       data-testid="surface-morph-root"
     >
-      <M3Surface
+      <M3SurfacePanel
         className="surface-side-sheet__topbar"
         fillHeight={false}
         height={72}
@@ -266,7 +67,7 @@ const SurfaceSideSheetMorph: FC = () => {
             {sideSheetModal ? 'Switch to docked sheet' : 'Switch to modal sheet'}
           </M3Button>
         </div>
-      </M3Surface>
+      </M3SurfacePanel>
 
       <M3Navigation
         expanded={navExpanded}
@@ -331,7 +132,7 @@ const SurfaceSideSheetMorph: FC = () => {
 
       <div className="surface-side-sheet__body">
         <div className="surface-side-sheet__workspace">
-          <M3Surface
+          <M3SurfacePanel
             className="surface-side-sheet__header-card"
             fillHeight={false}
             height={120}
@@ -341,7 +142,7 @@ const SurfaceSideSheetMorph: FC = () => {
           >
             <h3>Workspace surfaces</h3>
             <p>Static blocks keep flow while side-sheet changes modality.</p>
-          </M3Surface>
+          </M3SurfacePanel>
 
           <div
             ref={layoutRoot}
@@ -352,7 +153,7 @@ const SurfaceSideSheetMorph: FC = () => {
               className="surface-side-sheet__content-grid"
               data-testid="surface-morph-content-grid"
             >
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -362,9 +163,9 @@ const SurfaceSideSheetMorph: FC = () => {
               >
                 <strong>surface-container-lowest</strong>
                 <p>Read-heavy content block in the page flow.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -374,9 +175,9 @@ const SurfaceSideSheetMorph: FC = () => {
               >
                 <strong>surface-container-low</strong>
                 <p>Secondary block with mild emphasis.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -386,9 +187,9 @@ const SurfaceSideSheetMorph: FC = () => {
               >
                 <strong>surface-container-high</strong>
                 <p>Contextual utility content.</p>
-              </M3Surface>
+              </M3SurfacePanel>
 
-              <M3Surface
+              <M3SurfacePanel
                 className="surface-side-sheet__grid-surface"
                 fillHeight={false}
                 height={136}
@@ -398,33 +199,34 @@ const SurfaceSideSheetMorph: FC = () => {
               >
                 <strong>surface-dim</strong>
                 <p>Low-brightness complementary content.</p>
-              </M3Surface>
+              </M3SurfacePanel>
             </main>
 
             <div
               ref={dockedHost}
               className="surface-side-sheet__docked-host"
-              style={{ width: `${sideSheetDockedWidth}px` }}
+              style={dockedHostStyle}
               data-testid="surface-morph-docked-host"
             >
-              {!sideSheetModal ? (
-                <M3Surface
-                  className="surface-side-sheet__sheet"
+              {dockedPanelShown ? (
+                <M3SurfacePanel
+                  className="surface-side-sheet__sheet surface-side-sheet__sheet_docked"
                   fillWidth={true}
                   fillHeight={true}
-                  rounding={0}
+                  overflow="auto"
                   variant="surface-container-low"
                   elevation={0}
-                  overflow="auto"
-                  data-testid="surface-morph-docked-sheet"
+                  style={dockedPanelStyle}
+                  data-testid="surface-morph-sheet"
+                  data-panel-mode="docked"
                 >
                   <h3>Docked side sheet</h3>
-                  <p>Coplanar layout participant with fixed width per layout region.</p>
+                  <p>Coplanar layout participant with adaptive CSS width inside the layout host.</p>
                   <p>Main content remains interactive.</p>
                   <p className="surface-side-sheet__meta">
-                    Fixed width: {sideSheetWidth}px
+                    Adaptive width: {sideSheetWidth}px
                   </p>
-                </M3Surface>
+                </M3SurfacePanel>
               ) : null}
             </div>
 
@@ -432,49 +234,36 @@ const SurfaceSideSheetMorph: FC = () => {
               <M3Surface
                 className="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
                 mode="modal"
-                shown={modalVisible}
-                anchor="end"
-                fillWidth={false}
-                fillHeight={false}
-                width={modalWidth}
-                insetTop={modalInsetTop}
-                insetRight={modalInsetRight}
-                insetBottom={modalInsetBottom}
-                roundingTopLeft={modalRadiusLeft}
-                roundingBottomLeft={modalRadiusLeft}
-                roundingTopRight={0}
-                roundingBottomRight={0}
-                transitionMs={modalTransitionMs}
+                {...modalPanelProps}
                 transitionTiming={PANEL_TRANSITION_EASING}
-                zIndex={520}
-                variant={modalRole}
-                elevation={modalElevation}
-                overflow="auto"
-                data-testid="surface-morph-modal-sheet"
+                data-testid="surface-morph-sheet"
+                data-panel-mode="modal"
                 onDismiss={() => void closeModalFromPanel()}
               >
-                <div className="surface-side-sheet__modal-header">
-                  <h3>Modal side sheet</h3>
-
-                  {sideSheetModal ? (
-                    <M3IconButton
-                      className="surface-side-sheet__modal-close"
-                      appearance="standard"
-                      aria-label="Close modal side sheet"
-                      disabled={transitioning}
-                      data-testid="surface-morph-close"
-                      onClick={() => void closeModalFromPanel()}
-                    >
-                      <M3Icon name="close" />
-                    </M3IconButton>
-                  ) : null}
-                </div>
-
-                <p>Layer rebind: docked layer to modal layer.</p>
-                <p>Anchored to end/right edge with full-height modal surface.</p>
-                <p className="surface-side-sheet__meta">
-                  Fixed width: {modalWidth}px
-                </p>
+                {sideSheetModal ? (
+                  <>
+                    <div className="surface-side-sheet__modal-header">
+                      <h3>Modal side sheet</h3>
+
+                      <M3IconButton
+                        className="surface-side-sheet__modal-close"
+                        appearance="standard"
+                        aria-label="Close modal side sheet"
+                        disabled={transitioning}
+                        data-testid="surface-morph-close"
+                        onClick={() => void closeModalFromPanel()}
+                      >
+                        <M3Icon name="close" />
+                      </M3IconButton>
+                    </div>
+
+                    <p>Layer rebind: docked layer to modal layer.</p>
+                    <p>Stable modal state stays in overlay, while docked state remains layout-driven.</p>
+                    <p className="surface-side-sheet__meta">
+                      Measured transition width: {modalPanelProps.width}px
+                    </p>
+                  </>
+                ) : null}
               </M3Surface>
             ) : null}
           </div>
diff --git a/m3-react/storybook/examples/surface/styles.scss b/m3-react/storybook/examples/surface/styles.scss
index 9712ca0..c44b458 100644
--- a/m3-react/storybook/examples/surface/styles.scss
+++ b/m3-react/storybook/examples/surface/styles.scss
@@ -117,6 +117,11 @@ html.m3-theme-dark .surface-card-page {
   background: var(--surface-origin-slot);
 }
 
+.surface-card-page__origin-slot_filled {
+  border-color: transparent;
+  background: transparent;
+}
+
 .surface-card-page__overlay {
   position: absolute;
   inset: 0;
@@ -132,6 +137,15 @@ html.m3-theme-dark .surface-card-page {
     height #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')};
 }
 
+.surface-card-page__overlay-wrap_inline {
+  position: relative;
+  transition: none;
+}
+
+.surface-card-page__overlay-wrap_inline > .surface-card-page__morph-surface {
+  box-sizing: border-box;
+}
+
 .surface-card-page__morph-surface {
   pointer-events: auto;
 }
@@ -396,11 +410,17 @@ html.m3-theme-dark .surface-card-page {
 .surface-side-sheet__docked-host {
   flex: 0 0 auto;
   min-width: 0;
+  display: flex;
   overflow: hidden;
   border-left: 1px solid var(--surface-border);
   transition: width var(--surface-panel-transition-ms) var(--surface-panel-transition-easing);
 }
 
+.surface-side-sheet__sheet_docked {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
 .surface-side-sheet__sheet h3 {
   margin: 0 0 8px;
   font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
diff --git a/m3-react/storybook/examples/surface/utils.ts b/m3-react/storybook/examples/surface/utils.ts
deleted file mode 100644
index 3cb24ad..0000000
--- a/m3-react/storybook/examples/surface/utils.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import {
-  useRef,
-  useState,
-} from 'react'
-
-import type {
-  MutableRefObject,
-  SetStateAction,
-} from 'react'
-
-export function wait (ms: number): Promise<void> {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-export function raf (): Promise<void> {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-export function clamp (value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value))
-}
-
-export function useLatest<T> (value: T): MutableRefObject<T> {
-  const ref = useRef(value)
-  ref.current = value
-  return ref
-}
-
-export function useStateRef<T> (
-  initial: T
-): [T, (next: SetStateAction<T>) => void, MutableRefObject<T>] {
-  const [state, setState] = useState<T>(initial)
-  const ref = useRef(state)
-
-  const set = (next: SetStateAction<T>) => {
-    setState((prev) => {
-      const resolved = typeof next === 'function'
-        ? (next as (previous: T) => T)(prev)
-        : next
-
-      ref.current = resolved
-      return resolved
-    })
-  }
-
-  return [state, set, ref]
-}
diff --git a/m3-react/tests/M3Dialog.test.tsx b/m3-react/tests/M3Dialog.test.tsx
index f3f2668..d29a86a 100644
--- a/m3-react/tests/M3Dialog.test.tsx
+++ b/m3-react/tests/M3Dialog.test.tsx
@@ -3,19 +3,17 @@ import {
   fireEvent,
   render,
   screen,
+  waitFor,
 } from '@testing-library/react'
 
 import { M3Dialog } from '@/components/dialog'
 
 describe('m3-react/dialog', () => {
   afterEach(() => {
-    vi.runOnlyPendingTimers()
     vi.useRealTimers()
   })
 
-  test('content appears after opening with fake timers', () => {
-    vi.useFakeTimers()
-
+  test('content appears after opening', async () => {
     const { rerender } = render(
       <M3Dialog opened={false}>
         Dialog body
@@ -30,31 +28,163 @@ describe('m3-react/dialog', () => {
       </M3Dialog>
     )
 
-    act(() => {
-      vi.advanceTimersByTime(600)
+    await waitFor(() => {
+      expect(screen.getByText('Dialog body')).not.toBeNull()
     })
-
-    expect(screen.getByText('Dialog body')).not.toBeNull()
   })
 
-  test('scrim click requests closing when not fullscreen', () => {
-    vi.useFakeTimers()
-
+  test('scrim click requests closing when not fullscreen', async () => {
     const onToggle = vi.fn()
-    const { container } = render(
+    render(
       <M3Dialog opened={true} onToggle={onToggle}>
         Dialog body
       </M3Dialog>
     )
 
-    act(() => {
-      vi.advanceTimersByTime(600)
+    await waitFor(() => {
+      expect(document.body.querySelector('.m3-surface__scrim')).not.toBeNull()
     })
 
-    const scrim = container.ownerDocument.querySelector('.m3-scrim') as HTMLElement
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
 
     fireEvent.click(scrim)
 
+    expect(onToggle).toHaveBeenCalledTimes(1)
     expect(onToggle).toHaveBeenCalledWith(false)
   })
+
+  test('renders modal surface root instead of legacy container', async () => {
+    render(
+      <M3Dialog opened={true}>
+        Dialog body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(document.body.querySelector('.m3-surface[role="dialog"]')).not.toBeNull()
+    })
+
+    expect(document.body.querySelector('.m3-dialog-container')).toBeNull()
+  })
+
+  test('does not render scrim or legacy fullscreen class in fullscreen mode', async () => {
+    render(
+      <M3Dialog opened={true} fullscreen={true}>
+        Fullscreen body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('Fullscreen body')).not.toBeNull()
+    })
+
+    expect(document.body.querySelector('.m3-surface__scrim')).toBeNull()
+    expect(document.body.querySelector('.m3-dialog_fullscreen')).toBeNull()
+  })
+
+  test('renders icon, header, footer and content wrappers', async () => {
+    render(
+      <M3Dialog opened={true}>
+        <M3Dialog.Icon>
+          <span data-testid="icon-node">ICON</span>
+        </M3Dialog.Icon>
+
+        <M3Dialog.Header>
+          <h2 data-testid="header-node">Header</h2>
+        </M3Dialog.Header>
+
+        <div data-testid="content-node">Dialog body</div>
+
+        <M3Dialog.Footer>
+          <button type="button" data-testid="footer-node">Close</button>
+        </M3Dialog.Footer>
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('content-node')).not.toBeNull()
+    })
+
+    expect(document.body.querySelector('.m3-dialog__icon')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__header')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__footer')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__content')).not.toBeNull()
+    expect(screen.getByTestId('icon-node')).not.toBeNull()
+    expect(screen.getByTestId('header-node')).not.toBeNull()
+    expect(screen.getByTestId('footer-node')).not.toBeNull()
+    expect(screen.getByTestId('content-node')).not.toBeNull()
+  })
+
+  test('forwards dialog attributes and keeps default modal role', async () => {
+    render(
+      <M3Dialog
+        opened={true}
+        data-testid="dialog-root"
+        aria-label="Settings dialog"
+      >
+        Dialog body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('dialog-root')).not.toBeNull()
+    })
+
+    const dialog = document.body.querySelector('.m3-surface[role="dialog"]') as HTMLElement | null
+
+    expect(dialog?.getAttribute('aria-label')).toBe('Settings dialog')
+    expect(dialog?.getAttribute('role')).toBe('dialog')
+  })
+
+  test('keeps dialog mounted during close animation before unmounting', async () => {
+    const { rerender } = render(
+      <M3Dialog opened={true}>
+        Dialog body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog body')).not.toBeNull()
+    })
+
+    vi.useFakeTimers()
+
+    rerender(
+      <M3Dialog opened={false}>
+        Dialog body
+      </M3Dialog>
+    )
+
+    expect(screen.getByText('Dialog body')).not.toBeNull()
+
+    await act(async () => {
+      vi.advanceTimersByTime(300)
+    })
+
+    expect(screen.queryByText('Dialog body')).toBeNull()
+  })
+
+  test('toggles scrim visibility when fullscreen changes', async () => {
+    const { rerender } = render(
+      <M3Dialog opened={true} fullscreen={false}>
+        Dialog body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(document.body.querySelector('.m3-surface__scrim')).not.toBeNull()
+    })
+
+    rerender(
+      <M3Dialog opened={true} fullscreen={true}>
+        Dialog body
+      </M3Dialog>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('Dialog body')).not.toBeNull()
+    })
+
+    expect(document.body.querySelector('.m3-surface__scrim')).toBeNull()
+  })
 })
diff --git a/m3-react/tests/M3SideSheet.test.tsx b/m3-react/tests/M3SideSheet.test.tsx
new file mode 100644
index 0000000..7840a6b
--- /dev/null
+++ b/m3-react/tests/M3SideSheet.test.tsx
@@ -0,0 +1,101 @@
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+
+import { M3Icon } from '@/components/icon'
+import { M3SideSheet } from '@/components/side-sheet'
+
+vi.mock('@/components/scroll-rail', () => ({
+  M3ScrollRail: () => <div data-testid="scroll-rail-mock" />,
+}))
+
+describe('m3-react/side-sheet', () => {
+  test('renders dialog and default aria-labelledby', () => {
+    render(
+      <M3SideSheet shown={true}>
+        <M3SideSheet.Title>
+          Panel title
+        </M3SideSheet.Title>
+
+        Panel content
+      </M3SideSheet>
+    )
+
+    const dialog = screen.getByRole('dialog')
+    const labelId = dialog.getAttribute('aria-labelledby') as string
+
+    expect(screen.getByText('Panel content')).not.toBeNull()
+    expect(document.getElementById(labelId)?.textContent?.trim()).toBe('Panel title')
+  })
+
+  test('keeps title in header and footer outside scroll content', () => {
+    render(
+      <M3SideSheet shown={true}>
+        <M3SideSheet.Title>
+          Panel title
+        </M3SideSheet.Title>
+
+        <div>Panel content</div>
+
+        <M3SideSheet.Footer>
+          <div>Footer actions</div>
+        </M3SideSheet.Footer>
+      </M3SideSheet>
+    )
+
+    const title = screen.getByText('Panel title')
+    const content = screen.getByText('Panel content')
+    const footer = screen.getByText('Footer actions')
+
+    expect(title.closest('.m3-side-sheet__header')).not.toBeNull()
+    expect(title.closest('.m3-side-sheet__content')).toBeNull()
+    expect(content.closest('.m3-side-sheet__content')).not.toBeNull()
+    expect(footer.closest('.m3-side-sheet__footer')).not.toBeNull()
+    expect(footer.closest('.m3-side-sheet__content')).toBeNull()
+  })
+
+  test('emits close request on scrim click when not docked', async () => {
+    const onToggle = vi.fn()
+
+    render(
+      <M3SideSheet shown={true} docked={false} onToggle={onToggle}>
+        <M3SideSheet.Title>
+          Panel title
+        </M3SideSheet.Title>
+      </M3SideSheet>
+    )
+
+    await waitFor(() => {
+      expect(document.body.querySelector('.m3-surface__scrim')).not.toBeNull()
+    })
+
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
+
+    fireEvent.click(scrim)
+
+    expect(onToggle).toHaveBeenCalledWith(false)
+  })
+
+  test('emits close request on close button click', () => {
+    const onToggle = vi.fn()
+
+    render(
+      <M3SideSheet shown={true} onToggle={onToggle}>
+        <M3SideSheet.Title>
+          Panel title
+        </M3SideSheet.Title>
+
+        <M3SideSheet.CloseIcon>
+          <M3Icon name="close" />
+        </M3SideSheet.CloseIcon>
+      </M3SideSheet>
+    )
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(onToggle).toHaveBeenCalledWith(false)
+  })
+})
diff --git a/m3-react/tests/M3SurfacePanel.test.tsx b/m3-react/tests/M3SurfacePanel.test.tsx
new file mode 100644
index 0000000..04d5b92
--- /dev/null
+++ b/m3-react/tests/M3SurfacePanel.test.tsx
@@ -0,0 +1,61 @@
+import {
+  render,
+  screen,
+} from '@testing-library/react'
+
+import { M3SurfacePanel } from '@/components/surface'
+
+describe('m3-react/surface-panel', () => {
+  test('renders deterministic static panel contract without implicit landmark role', () => {
+    render(
+      <M3SurfacePanel>
+        Surface body
+      </M3SurfacePanel>
+    )
+
+    const surface = screen.getByText('Surface body').closest('.m3-surface') as HTMLElement
+
+    expect(surface).not.toBeNull()
+    expect(surface.getAttribute('role')).toBeNull()
+    expect(surface.style.width).toBe('100%')
+    expect(surface.style.height).toBe('100%')
+    expect(surface.style.borderTopLeftRadius).toBe('0px')
+    expect(surface.style.borderBottomLeftRadius).toBe('0px')
+  })
+
+  test('supports global and per-corner rounding overrides', () => {
+    render(
+      <M3SurfacePanel
+        rounding={16}
+        roundingTopLeft={4}
+        roundingBottomRight="24px"
+      />
+    )
+
+    const surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.style.borderTopLeftRadius).toBe('4px')
+    expect(surface.style.borderTopRightRadius).toBe('16px')
+    expect(surface.style.borderBottomRightRadius).toBe('24px')
+    expect(surface.style.borderBottomLeftRadius).toBe('16px')
+  })
+
+  test('maps auto variant from elevation and allows explicit variant override', () => {
+    const { rerender } = render(
+      <M3SurfacePanel elevation={3} />
+    )
+
+    let surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
+
+    rerender(
+      <M3SurfacePanel elevation={3} variant="surface-bright" />
+    )
+
+    surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
+  })
+})

From d622c92455775b2e7370f9473181f26f72e28708 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 16:46:04 +0400
Subject: [PATCH 25/37] feat(m3-vue): Refactored surface-based dialogs and side
 sheets

---
 m3-vue/src/components/dialog/M3Dialog.vue     | 195 ++++++---
 .../src/components/side-sheet/M3SideSheet.vue | 216 +++++++---
 m3-vue/src/components/surface/M3Surface.vue   | 314 +++------------
 .../src/components/surface/M3SurfacePanel.vue |  52 +++
 m3-vue/src/components/surface/index.ts        |   1 +
 .../orchestration/useSurfaceCardPageMorph.ts  | 201 ++++++++++
 .../orchestration/useSurfaceSideSheetMorph.ts | 266 ++++++++++++
 m3-vue/src/components/surface/shared.ts       | 163 ++++++++
 m3-vue/src/index.ts                           |   1 +
 m3-vue/storybook/components/M3SideSheet.mdx   |  42 ++
 .../components/M3SideSheet.stories.ts         |  84 ++++
 .../examples/surface/SurfaceCardPageMorph.vue | 268 +++++--------
 .../surface/SurfaceNestedDialogsChain.vue     |  16 +-
 .../surface/SurfaceSideSheetAlwaysModal.vue   |  21 +-
 .../SurfaceSideSheetDismissToRemove.vue       |  21 +-
 .../surface/SurfaceSideSheetModalToWindow.vue |  94 ++---
 .../surface/SurfaceSideSheetMorph.vue         | 377 ++++--------------
 m3-vue/tests/M3Dialog.test.ts                 | 137 ++++++-
 m3-vue/tests/M3SideSheet.test.ts              |  27 +-
 m3-vue/tests/M3SurfacePanel.test.ts           |  64 +++
 m3-vue/tests/M3SurfaceStories.e2e.ts          |  18 +-
 21 files changed, 1647 insertions(+), 931 deletions(-)
 create mode 100644 m3-vue/src/components/surface/M3SurfacePanel.vue
 create mode 100644 m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
 create mode 100644 m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
 create mode 100644 m3-vue/src/components/surface/shared.ts
 create mode 100644 m3-vue/storybook/components/M3SideSheet.mdx
 create mode 100644 m3-vue/storybook/components/M3SideSheet.stories.ts
 create mode 100644 m3-vue/tests/M3SurfacePanel.test.ts

diff --git a/m3-vue/src/components/dialog/M3Dialog.vue b/m3-vue/src/components/dialog/M3Dialog.vue
index 85225a5..91a938f 100644
--- a/m3-vue/src/components/dialog/M3Dialog.vue
+++ b/m3-vue/src/components/dialog/M3Dialog.vue
@@ -1,58 +1,87 @@
 <template>
-    <Teleport to="body">
-        <Transition name="m3-transition-fade">
-            <div
-                v-show="opened"
-                class="m3-dialog-container"
-            >
-                <div
-                    v-if="!fullscreen"
-                    class="m3-scrim"
-                    @click.self="emit('update:opened', false)"
-                />
-
-                <Transition name="m3-dialog-appear">
-                    <section
-                        v-if="opened"
-                        :class="{
-                            'm3-dialog': true,
-                            'm3-dialog_fullscreen': fullscreen,
-                        }"
-                        v-bind="$attrs"
-                    >
-                        <div
-                            v-if="'icon' in $slots"
-                            class="m3-dialog__icon"
-                        >
-                            <slot name="icon" />
-                        </div>
-
-                        <header
-                            v-if="'header' in $slots"
-                            class="m3-dialog__header"
-                        >
-                            <slot name="header" />
-                        </header>
-
-                        <div class="m3-dialog__content">
-                            <slot />
-                        </div>
-
-                        <footer
-                            v-if="'footer' in $slots"
-                            class="m3-dialog__footer"
-                        >
-                            <slot name="footer" />
-                        </footer>
-                    </section>
-                </Transition>
-            </div>
-        </Transition>
-    </Teleport>
+    <M3Surface
+        v-if="dialogMounted"
+        tag="section"
+        mode="modal"
+        :shown="dialogMounted"
+        :scrim-shown="opened"
+        teleport-to="body"
+        :scrim="!fullscreen"
+        :anchor="fullscreen ? 'none' : 'center'"
+        :fill-width="fullscreen"
+        :fill-height="fullscreen"
+        :width="fullscreen ? '100vw' : DIALOG_WIDTH"
+        :height="fullscreen ? '100vh' : null"
+        :min-width="fullscreen ? 0 : DIALOG_MIN_WIDTH"
+        :max-width="fullscreen ? '100vw' : DIALOG_MAX_WIDTH"
+        :max-height="fullscreen ? '100vh' : null"
+        :rounding="fullscreen ? 0 : DIALOG_ROUNDING"
+        variant="surface-container-high"
+        :elevation="DIALOG_ELEVATION"
+        :z-index="DIALOG_Z_INDEX"
+        :transition-ms="DIALOG_TRANSITION_MS"
+        :transition-timing="DIALOG_TRANSITION_TIMING"
+        class="m3-dialog"
+        :style="dialogStyle"
+        v-bind="$attrs"
+        @dismiss="emit('update:opened', false)"
+    >
+        <div
+            v-if="'icon' in $slots"
+            class="m3-dialog__icon"
+        >
+            <slot name="icon" />
+        </div>
+
+        <header
+            v-if="'header' in $slots"
+            class="m3-dialog__header"
+        >
+            <slot name="header" />
+        </header>
+
+        <div class="m3-dialog__content">
+            <slot />
+        </div>
+
+        <footer
+            v-if="'footer' in $slots"
+            class="m3-dialog__footer"
+        >
+            <slot name="footer" />
+        </footer>
+    </M3Surface>
 </template>
 
 <script lang="ts" setup>
-defineProps({
+import { M3Surface } from '@/components/surface'
+import {
+  m3MotionDurations,
+  m3MotionEasings,
+} from '@modulify/m3-foundation/lib/motion'
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  watch,
+} from 'vue'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+const DIALOG_WIDTH = 312
+const DIALOG_MIN_WIDTH = 280
+const DIALOG_MAX_WIDTH = 560
+const DIALOG_ROUNDING = 28
+const DIALOG_ENTRY_OFFSET_PX = 24
+const DIALOG_ELEVATION = 0
+const DIALOG_Z_INDEX = 1000
+const DIALOG_TRANSITION_MS = m3MotionDurations.medium2
+const DIALOG_TRANSITION_TIMING = m3MotionEasings.standard
+
+const props = defineProps({
   opened: {
     type: Boolean,
     default: false,
@@ -67,4 +96,66 @@ defineProps({
 const emit = defineEmits([
   'update:opened',
 ])
-</script>
\ No newline at end of file
+
+const dialogMounted = ref(props.opened)
+const dialogVisible = ref(false)
+let enterFrame: number | null = null
+let leaveTimer: number | null = null
+
+const dialogStyle = computed(() => ({
+  opacity: dialogVisible.value ? 1 : 0,
+  transform: props.fullscreen
+    ? 'translate3d(0, 0, 0)'
+    : (dialogVisible.value
+      ? 'translate(-50%, -50%)'
+      : `translate(-50%, calc(-50% + ${DIALOG_ENTRY_OFFSET_PX}px))`),
+  transition: `opacity ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}, transform ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}`,
+  pointerEvents: dialogVisible.value ? 'auto' : 'none',
+}))
+
+const clearAnimationHandles = () => {
+  if (enterFrame !== null) {
+    window.cancelAnimationFrame(enterFrame)
+    enterFrame = null
+  }
+
+  if (leaveTimer !== null) {
+    window.clearTimeout(leaveTimer)
+    leaveTimer = null
+  }
+}
+
+watch(() => props.opened, async (opened) => {
+  clearAnimationHandles()
+
+  if (opened) {
+    dialogMounted.value = true
+    dialogVisible.value = false
+    await nextTick()
+
+    enterFrame = window.requestAnimationFrame(() => {
+      enterFrame = null
+      dialogVisible.value = true
+    })
+
+    return
+  }
+
+  dialogVisible.value = false
+
+  if (!dialogMounted.value) {
+    return
+  }
+
+  leaveTimer = window.setTimeout(() => {
+    leaveTimer = null
+    dialogMounted.value = false
+  }, DIALOG_TRANSITION_MS)
+}, {
+  immediate: true,
+})
+
+onBeforeUnmount(() => {
+  clearAnimationHandles()
+})
+</script>
diff --git a/m3-vue/src/components/side-sheet/M3SideSheet.vue b/m3-vue/src/components/side-sheet/M3SideSheet.vue
index f90d023..9df30e7 100644
--- a/m3-vue/src/components/side-sheet/M3SideSheet.vue
+++ b/m3-vue/src/components/side-sheet/M3SideSheet.vue
@@ -1,71 +1,75 @@
 <template>
-    <Teleport to="body">
-        <Transition v-if="!docked" name="m3-transition-fade">
-            <div
-                v-show="shown"
-                class="m3-scrim"
-                @click="emit('update:shown', false)"
-            />
-        </Transition>
-
-        <Transition name="m3-transition-slide-right">
-            <div
-                v-show="shown"
-                :id="_id"
-                :class="{
-                    'm3-side-sheet': true,
-                    'm3-side-sheet_docked': docked,
-                }"
-                role="dialog"
-                v-bind="{
-                    ...$attrs,
-                    ...('aria-label' in $attrs || 'aria-labelledby' in $attrs ? {} : {
-                        'aria-labelledby': _id + '-title',
-                    }),
-                }"
-            >
-                <header
-                    :class="{
-                        'm3-side-sheet__header': true,
-                        'm3-side-sheet__header_has-leading-affordance': 'affordance' in $slots,
-                    }"
-                >
-                    <div v-if="'affordance' in $slots" class="m3-side-sheet__affordance">
-                        <slot name="affordance" />
-                    </div>
-
-                    <div :id="_id + '-title'" class="m3-side-sheet__title">
-                        <slot name="title" />
-                    </div>
-
-                    <div class="m3-side-sheet__affordance">
-                        <M3IconButton @click="emit('update:shown', false)">
-                            <slot name="close-icon" />
-                        </M3IconButton>
-                    </div>
-                </header>
-
-                <div class="m3-side-sheet__content">
-                    <M3ScrollRail />
-                    <slot />
-                </div>
-
-                <footer
-                    v-if="'footer' in $slots"
-                    class="m3-side-sheet__footer"
-                >
-                    <slot name="footer" />
-                </footer>
+    <M3Surface
+        v-if="surfaceMounted"
+        :id="_id"
+        tag="div"
+        mode="modal"
+        anchor="end"
+        :shown="true"
+        :scrim-shown="surfaceScrimShown"
+        :fill-width="false"
+        :fill-height="true"
+        :width="docked ? 256 : undefined"
+        :min-width="docked ? 256 : 320"
+        :max-width="docked ? 256 : 400"
+        variant="surface-container-low"
+        :elevation="0"
+        :z-index="DOCKED_Z_INDEX"
+        overflow="hidden"
+        :rounding-top-left="docked ? 0 : 16"
+        :rounding-bottom-left="docked ? 0 : 16"
+        :rounding-top-right="0"
+        :rounding-bottom-right="0"
+        role="dialog"
+        :class="surfaceClass"
+        v-bind="surfaceAttrs"
+        @update:shown="emit('update:shown', $event)"
+    >
+        <header :class="headerClass">
+            <div v-if="'affordance' in $slots" class="m3-side-sheet__affordance">
+                <slot name="affordance" />
             </div>
-        </Transition>
-    </Teleport>
+
+            <div :id="_id + '-title'" class="m3-side-sheet__title">
+                <slot name="title" />
+            </div>
+
+            <div class="m3-side-sheet__affordance">
+                <M3IconButton @click="emit('update:shown', false)">
+                    <slot name="close-icon" />
+                </M3IconButton>
+            </div>
+        </header>
+
+        <div class="m3-side-sheet__content">
+            <M3ScrollRail />
+            <slot />
+        </div>
+
+        <footer
+            v-if="'footer' in $slots"
+            class="m3-side-sheet__footer"
+        >
+            <slot name="footer" />
+        </footer>
+    </M3Surface>
 </template>
 
 <script lang="ts" setup>
 import { M3IconButton } from '@/components/icon-button'
 import { M3ScrollRail } from '@/components/scroll-rail'
+import { M3Surface } from '@/components/surface'
+import { m3MotionDurations } from '@modulify/m3-foundation/lib/motion'
 
-import { computed } from 'vue'
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  useAttrs,
+  useSlots,
+  watch,
+} from 'vue'
 
 import {
   isId,
@@ -75,6 +79,11 @@ import {
 
 import useId from '@/composables/id'
 
+const DOCKED_Z_INDEX = 1000
+const SIDE_SHEET_TRANSITION_MS = m3MotionDurations['extra-long2']
+
+type TransitionState = 'idle' | 'pre-enter' | 'entering' | 'pre-exit' | 'exiting'
+
 const props = defineProps({
   id: {
     type: String,
@@ -94,6 +103,91 @@ const props = defineProps({
 })
 
 const emit = defineEmits(['update:shown'])
+const attrs = useAttrs()
+const slots = useSlots()
 
 const _id = useId('m3-side-sheet', computed(() => props.id))
-</script>
\ No newline at end of file
+const surfaceMounted = ref(props.shown)
+const transitionState = ref<TransitionState>('idle')
+let transitionTimeout: number | null = null
+
+const surfaceClass = computed(() => ({
+  'm3-side-sheet': true,
+  'm3-side-sheet_docked': props.docked,
+  'm3-transition-slide-right-enter': transitionState.value === 'pre-enter' || transitionState.value === 'entering',
+  'm3-transition-slide-right-enter-active': transitionState.value === 'entering',
+  'm3-transition-slide-right-leave-active': transitionState.value === 'pre-exit' || transitionState.value === 'exiting',
+  'm3-transition-slide-right-leave-to': transitionState.value === 'exiting',
+}))
+
+const headerClass = computed(() => ({
+  'm3-side-sheet__header': true,
+  'm3-side-sheet__header_has-leading-affordance': 'affordance' in slots,
+}))
+
+const surfaceScrimShown = computed(() => !props.docked && props.shown && transitionState.value !== 'pre-enter')
+
+const surfaceAttrs = computed(() => ({
+  ...attrs,
+  ...('aria-label' in attrs || 'aria-labelledby' in attrs ? {} : {
+    'aria-labelledby': _id.value + '-title',
+  }),
+  ...('aria-modal' in attrs || !props.docked ? {} : {
+    'aria-modal': 'false',
+  }),
+}))
+
+function clearTransitionTimer() {
+  if (transitionTimeout === null) {
+    return
+  }
+
+  clearTimeout(transitionTimeout)
+  transitionTimeout = null
+}
+
+async function enterSurface() {
+  clearTransitionTimer()
+  surfaceMounted.value = true
+  transitionState.value = 'pre-enter'
+
+  await nextTick()
+  await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+
+  transitionState.value = 'entering'
+  transitionTimeout = window.setTimeout(() => {
+    transitionState.value = 'idle'
+    transitionTimeout = null
+  }, SIDE_SHEET_TRANSITION_MS)
+}
+
+async function leaveSurface() {
+  if (!surfaceMounted.value) {
+    transitionState.value = 'idle'
+    return
+  }
+
+  clearTransitionTimer()
+  transitionState.value = 'pre-exit'
+
+  await nextTick()
+  await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+
+  transitionState.value = 'exiting'
+  transitionTimeout = window.setTimeout(() => {
+    surfaceMounted.value = false
+    transitionState.value = 'idle'
+    transitionTimeout = null
+  }, SIDE_SHEET_TRANSITION_MS)
+}
+
+watch(() => props.shown, (shown) => {
+  void (shown ? enterSurface() : leaveSurface())
+}, {
+  immediate: true,
+})
+
+onBeforeUnmount(() => {
+  clearTransitionTimer()
+})
+</script>
diff --git a/m3-vue/src/components/surface/M3Surface.vue b/m3-vue/src/components/surface/M3Surface.vue
index 02c4ca4..4b3c76b 100644
--- a/m3-vue/src/components/surface/M3Surface.vue
+++ b/m3-vue/src/components/surface/M3Surface.vue
@@ -2,36 +2,70 @@
     <Teleport v-if="isModal" :to="teleportTo">
         <Transition v-if="scrim" name="m3-transition-fade">
             <div
-                v-show="shown"
+                v-show="resolvedScrimShown"
                 :style="{ zIndex: zIndex - 1 }"
                 class="m3-surface__scrim"
                 @click="onScrimClick"
             />
         </Transition>
 
-        <component
-            :is="tag"
-            v-show="shown"
+        <M3SurfacePanel
             :id="_id"
+            :tag="tag"
+            :elevation="elevation"
+            :variant="variant"
+            :fill-width="fillWidth"
+            :fill-height="fillHeight"
+            :width="width"
+            :height="height"
+            :min-width="minWidth"
+            :max-width="maxWidth"
+            :min-height="minHeight"
+            :max-height="maxHeight"
+            :rounding="rounding"
+            :rounding-top-left="roundingTopLeft"
+            :rounding-top-right="roundingTopRight"
+            :rounding-bottom-right="roundingBottomRight"
+            :rounding-bottom-left="roundingBottomLeft"
+            :transition-ms="transitionMs"
+            :transition-timing="transitionTiming"
+            :overflow="overflow"
             :class="surfaceClass"
             :style="surfaceStyle"
             v-bind="surfaceAttrs"
         >
             <slot />
-        </component>
+        </M3SurfacePanel>
     </Teleport>
 
-    <component
-        :is="tag"
+    <M3SurfacePanel
         v-else
-        v-show="shown"
         :id="_id"
+        :tag="tag"
+        :elevation="elevation"
+        :variant="variant"
+        :fill-width="fillWidth"
+        :fill-height="fillHeight"
+        :width="width"
+        :height="height"
+        :min-width="minWidth"
+        :max-width="maxWidth"
+        :min-height="minHeight"
+        :max-height="maxHeight"
+        :rounding="rounding"
+        :rounding-top-left="roundingTopLeft"
+        :rounding-top-right="roundingTopRight"
+        :rounding-bottom-right="roundingBottomRight"
+        :rounding-bottom-left="roundingBottomLeft"
+        :transition-ms="transitionMs"
+        :transition-timing="transitionTiming"
+        :overflow="overflow"
         :class="surfaceClass"
         :style="surfaceStyle"
         v-bind="surfaceAttrs"
     >
         <slot />
-    </component>
+    </M3SurfacePanel>
 </template>
 
 <script lang="ts" setup>
@@ -40,64 +74,28 @@ import type {
   Anchor as SurfaceAnchor,
   Length as SurfaceLength,
   Mode as SurfaceMode,
-  Variant as SurfaceVariant,
 } from '@modulify/m3-foundation/types/components/surface'
 
+import M3SurfacePanel from './M3SurfacePanel.vue'
+
 import {
   computed,
   useAttrs,
 } from 'vue'
 
-import {
-  isId,
-  isUndefined,
-  Or,
-} from '@modulify/m3-foundation/lib/predicates'
-import { m3MotionEasings } from '@modulify/m3-foundation/lib/motion'
-
 import useId from '@/composables/id'
+import {
+  getModalAnchorStyle,
+  surfacePanelProps,
+  toLength,
+} from './shared'
 
 defineOptions({
   inheritAttrs: false,
 })
 
-type AnchorStyleFactory = (inset: {
-  top: string,
-  right: string,
-  bottom: string,
-  left: string,
-}) => Record<string, string>
-
-const MODAL_ANCHOR_STYLE: Record<SurfaceAnchor, AnchorStyleFactory> = {
-  none: ({ top, right, bottom, left }) => ({ top, right, bottom, left }),
-  center: () => ({
-    top: '50%',
-    left: '50%',
-    right: 'auto',
-    bottom: 'auto',
-    transform: 'translate(-50%, -50%)',
-  }),
-  start: ({ top, bottom, left }) => ({ top, bottom, left, right: 'auto' }),
-  end: ({ top, right, bottom }) => ({ top, right, bottom, left: 'auto' }),
-  top: ({ top, left, right }) => ({ top, left, right, bottom: 'auto' }),
-  bottom: ({ bottom, left, right }) => ({ bottom, left, right, top: 'auto' }),
-  'top-start': ({ top, left }) => ({ top, left, right: 'auto', bottom: 'auto' }),
-  'top-end': ({ top, right }) => ({ top, right, left: 'auto', bottom: 'auto' }),
-  'bottom-start': ({ bottom, left }) => ({ bottom, left, right: 'auto', top: 'auto' }),
-  'bottom-end': ({ bottom, right }) => ({ bottom, right, left: 'auto', top: 'auto' }),
-}
-
 const props = defineProps({
-  id: {
-    type: null as unknown as PropType<string | undefined>,
-    validator: Or(isId, isUndefined),
-    default: undefined,
-  },
-
-  tag: {
-    type: String,
-    default: 'section',
-  },
+  ...surfacePanelProps,
 
   shown: {
     type: Boolean,
@@ -119,80 +117,9 @@ const props = defineProps({
     default: true,
   },
 
-  elevation: {
-    type: Number,
-    default: 0,
-    validator: (value: number) => Number.isInteger(value) && value >= 0 && value <= 5,
-  },
-
-  variant: {
-    type: String as PropType<SurfaceVariant>,
-    default: 'auto',
-  },
-
-  fillWidth: {
+  scrimShown: {
     type: Boolean,
-    default: true,
-  },
-
-  fillHeight: {
-    type: Boolean,
-    default: true,
-  },
-
-  width: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  height: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  minWidth: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  maxWidth: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  minHeight: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  maxHeight: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  rounding: {
-    type: null as unknown as PropType<SurfaceLength>,
-    default: 0,
-  },
-
-  roundingTopLeft: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  roundingTopRight: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  roundingBottomRight: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
-  },
-
-  roundingBottomLeft: {
-    type: null as unknown as PropType<SurfaceLength | null>,
-    default: null,
+    default: undefined,
   },
 
   anchor: {
@@ -224,21 +151,6 @@ const props = defineProps({
     type: Number,
     default: 400,
   },
-
-  transitionMs: {
-    type: Number,
-    default: 220,
-  },
-
-  transitionTiming: {
-    type: String,
-    default: m3MotionEasings.standard,
-  },
-
-  overflow: {
-    type: String,
-    default: 'visible',
-  },
 })
 
 const emit = defineEmits([
@@ -248,110 +160,10 @@ const emit = defineEmits([
 
 const attrs = useAttrs()
 
-function toLength(value: SurfaceLength | null | undefined, fallback: string): string {
-  if (value == null) {
-    return fallback
-  }
-
-  return typeof value === 'number'
-    ? `${value}px`
-    : value
-}
-
-function isDefined<T>(value: T | null | undefined): value is T {
-  return value !== null && value !== undefined
-}
-
 const _id = useId('m3-surface', computed(() => props.id))
 
 const isModal = computed(() => props.mode === 'modal')
-
-const resolvedVariant = computed<Exclude<SurfaceVariant, 'auto'>>(() => {
-  if (props.variant !== 'auto') return props.variant
-
-  switch (props.elevation) {
-    case 0: return 'surface'
-    case 1: return 'surface-container-low'
-    case 2: return 'surface-container'
-    case 3: return 'surface-container-high'
-    case 4: return 'surface-container-highest'
-    default: return 'surface-bright'
-  }
-})
-
-const variantClassName = computed(() => {
-  if (resolvedVariant.value === 'surface') {
-    return null
-  }
-
-  return `m3-surface_${resolvedVariant.value.replace(/^surface-/, '')}`
-})
-
-const resolvedSizeStyle = computed(() => {
-  const width = isDefined(props.width)
-    ? toLength(props.width, 'auto')
-    : (props.fillWidth ? '100%' : 'auto')
-
-  const height = isDefined(props.height)
-    ? toLength(props.height, 'auto')
-    : (props.fillHeight ? '100%' : 'auto')
-
-  return {
-    width,
-    height,
-    minWidth: isDefined(props.minWidth) ? toLength(props.minWidth, '0px') : undefined,
-    maxWidth: isDefined(props.maxWidth) ? toLength(props.maxWidth, 'none') : undefined,
-    minHeight: isDefined(props.minHeight) ? toLength(props.minHeight, '0px') : undefined,
-    maxHeight: isDefined(props.maxHeight) ? toLength(props.maxHeight, 'none') : undefined,
-  }
-})
-
-const cornerRadiusStyle = computed(() => {
-  const base = toLength(props.rounding, '0px')
-
-  return {
-    borderTopLeftRadius: isDefined(props.roundingTopLeft) ? toLength(props.roundingTopLeft, base) : base,
-    borderTopRightRadius: isDefined(props.roundingTopRight) ? toLength(props.roundingTopRight, base) : base,
-    borderBottomRightRadius: isDefined(props.roundingBottomRight) ? toLength(props.roundingBottomRight, base) : base,
-    borderBottomLeftRadius: isDefined(props.roundingBottomLeft) ? toLength(props.roundingBottomLeft, base) : base,
-  }
-})
-
-const anchorStyle = computed(() => {
-  if (!isModal.value) {
-    return {}
-  }
-
-  const inset = {
-    top: toLength(props.insetTop, '0px'),
-    right: toLength(props.insetRight, '0px'),
-    bottom: toLength(props.insetBottom, '0px'),
-    left: toLength(props.insetLeft, '0px'),
-  }
-
-  return MODAL_ANCHOR_STYLE[props.anchor](inset)
-})
-
-const transition = computed(() => {
-  const duration = `${props.transitionMs}ms`
-
-  return [
-    `width ${duration} ${props.transitionTiming}`,
-    `height ${duration} ${props.transitionTiming}`,
-    `min-width ${duration} ${props.transitionTiming}`,
-    `max-width ${duration} ${props.transitionTiming}`,
-    `min-height ${duration} ${props.transitionTiming}`,
-    `max-height ${duration} ${props.transitionTiming}`,
-    `top ${duration} ${props.transitionTiming}`,
-    `right ${duration} ${props.transitionTiming}`,
-    `bottom ${duration} ${props.transitionTiming}`,
-    `left ${duration} ${props.transitionTiming}`,
-    `transform ${duration} ${props.transitionTiming}`,
-    `opacity ${duration} ${props.transitionTiming}`,
-    `background-color ${duration} ${props.transitionTiming}`,
-    `box-shadow ${duration} ${props.transitionTiming}`,
-  ].join(', ')
-})
+const resolvedScrimShown = computed(() => props.scrimShown ?? props.shown)
 
 const surfaceAttrs = computed(() => {
   return isModal.value ? {
@@ -365,23 +177,21 @@ const surfaceAttrs = computed(() => {
 })
 
 const surfaceClass = computed(() => ({
-  'm3-surface': true,
-  'm3-surface_modal': isModal.value,
-  [variantClassName.value || '']: Boolean(variantClassName.value),
+  ['m3-surface_modal']: isModal.value,
   [`m3-surface_anchor-${props.anchor}`]: true,
-  [`m3-surface_elevation-${props.elevation}`]: true,
 }))
 
 const surfaceStyle = computed(() => {
   return {
-    ...resolvedSizeStyle.value,
-    ...cornerRadiusStyle.value,
-    ...anchorStyle.value,
-    '--m3-surface-radius-transition-duration': `${props.transitionMs}ms`,
-    overflow: props.overflow,
-    transition: transition.value,
+    ...isModal.value && getModalAnchorStyle(props.anchor, {
+      top: toLength(props.insetTop, '0px'),
+      right: toLength(props.insetRight, '0px'),
+      bottom: toLength(props.insetBottom, '0px'),
+      left: toLength(props.insetLeft, '0px'),
+    }),
     position: isModal.value ? 'fixed' : 'relative',
     zIndex: isModal.value ? props.zIndex : undefined,
+    display: props.shown ? undefined : 'none',
   }
 })
 
diff --git a/m3-vue/src/components/surface/M3SurfacePanel.vue b/m3-vue/src/components/surface/M3SurfacePanel.vue
new file mode 100644
index 0000000..05036e7
--- /dev/null
+++ b/m3-vue/src/components/surface/M3SurfacePanel.vue
@@ -0,0 +1,52 @@
+<template>
+    <component
+        :is="tag"
+        :id="id"
+        :class="surfaceClass"
+        :style="surfaceStyle"
+        v-bind="attrs"
+    >
+        <slot />
+    </component>
+</template>
+
+<script lang="ts" setup>
+import {
+  computed,
+  useAttrs,
+} from 'vue'
+
+import {
+  getSurfacePanelClass,
+  getSurfacePanelStyle,
+  surfacePanelProps,
+} from './shared'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+const props = defineProps(surfacePanelProps)
+
+const attrs = useAttrs()
+
+const surfaceClass = computed(() => getSurfacePanelClass(props.elevation, props.variant))
+const surfaceStyle = computed(() => getSurfacePanelStyle({
+  fillWidth: props.fillWidth,
+  fillHeight: props.fillHeight,
+  width: props.width,
+  height: props.height,
+  minWidth: props.minWidth,
+  maxWidth: props.maxWidth,
+  minHeight: props.minHeight,
+  maxHeight: props.maxHeight,
+  rounding: props.rounding,
+  roundingTopLeft: props.roundingTopLeft,
+  roundingTopRight: props.roundingTopRight,
+  roundingBottomRight: props.roundingBottomRight,
+  roundingBottomLeft: props.roundingBottomLeft,
+  transitionMs: props.transitionMs,
+  transitionTiming: props.transitionTiming,
+  overflow: props.overflow,
+}))
+</script>
diff --git a/m3-vue/src/components/surface/index.ts b/m3-vue/src/components/surface/index.ts
index 6f5e46b..5db01f7 100644
--- a/m3-vue/src/components/surface/index.ts
+++ b/m3-vue/src/components/surface/index.ts
@@ -1 +1,2 @@
+export { default as M3SurfacePanel } from './M3SurfacePanel.vue'
 export { default as M3Surface } from './M3Surface.vue'
diff --git a/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts b/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
new file mode 100644
index 0000000..13a850b
--- /dev/null
+++ b/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
@@ -0,0 +1,201 @@
+/* eslint-disable max-lines-per-function */
+import {
+  computed,
+  onBeforeUnmount,
+  nextTick,
+  onMounted,
+  ref,
+} from 'vue'
+
+import {
+  measureContainerRect,
+  measureRelativeRect,
+  raf,
+  toMotionStyle,
+  type SurfaceMotionRect,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+export function useSurfaceCardPageMorph(transitionMs: number) {
+  const expanded = ref(false)
+  const busy = ref(false)
+  const backgroundCollapsed = ref(false)
+  const originHeight = ref(220)
+  const canvas = ref<HTMLElement | null>(null)
+  const originSlot = ref<HTMLElement | null>(null)
+  let observer: ResizeObserver | null = null
+  const syncFrame = ref<number | null>(null)
+  const motion = ref<SurfaceMotionRect>({
+    top: 16,
+    left: 16,
+    width: 320,
+    height: 220,
+  })
+
+  const overlayStyle = computed(() => toMotionStyle(motion.value))
+
+  function measureOrigin() {
+    return measureRelativeRect(canvas.value, originSlot.value)
+  }
+
+  function measureExpanded() {
+    return measureContainerRect(canvas.value)
+  }
+
+  function syncMotionToLayout() {
+    const origin = measureOrigin()
+
+    if (origin) {
+      originHeight.value = origin.height
+    }
+
+    if (expanded.value) {
+      const full = measureExpanded()
+
+      if (full) {
+        motion.value = full
+      }
+
+      return
+    }
+
+    if (!origin || backgroundCollapsed.value) {
+      return
+    }
+
+    motion.value = origin
+  }
+
+  function scheduleSyncMotion() {
+    if (syncFrame.value !== null) {
+      cancelAnimationFrame(syncFrame.value)
+    }
+
+    syncFrame.value = requestAnimationFrame(() => {
+      syncFrame.value = null
+      syncMotionToLayout()
+    })
+  }
+
+  async function initMotion() {
+    await nextTick()
+    await raf()
+
+    const origin = measureOrigin()
+    if (!origin) {
+      return
+    }
+
+    motion.value = origin
+    originHeight.value = origin.height
+  }
+
+  async function expandCard() {
+    backgroundCollapsed.value = false
+
+    const origin = measureOrigin()
+    if (origin) {
+      motion.value = origin
+      originHeight.value = origin.height
+    }
+
+    expanded.value = true
+    await nextTick()
+    await raf()
+
+    const full = measureExpanded()
+    if (!full) {
+      return
+    }
+
+    motion.value = full
+    await wait(transitionMs)
+    backgroundCollapsed.value = true
+  }
+
+  async function collapseCard() {
+    if (backgroundCollapsed.value) {
+      backgroundCollapsed.value = false
+      await nextTick()
+      await raf()
+    }
+
+    const full = measureExpanded()
+    if (full) {
+      motion.value = full
+    }
+
+    const origin = measureOrigin()
+    if (origin) {
+      originHeight.value = origin.height
+    }
+
+    expanded.value = false
+    await nextTick()
+    await raf()
+
+    if (!origin) {
+      return
+    }
+
+    motion.value = origin
+    await wait(transitionMs)
+  }
+
+  async function toggleCardMode() {
+    if (busy.value) {
+      return
+    }
+
+    busy.value = true
+
+    if (expanded.value) {
+      await collapseCard()
+      busy.value = false
+      return
+    }
+
+    await expandCard()
+    busy.value = false
+  }
+
+  onMounted(() => {
+    initMotion()
+
+    if (typeof ResizeObserver === 'undefined') {
+      return
+    }
+
+    observer = new ResizeObserver(() => {
+      scheduleSyncMotion()
+    })
+
+    if (canvas.value && observer) {
+      observer.observe(canvas.value)
+    }
+
+    if (originSlot.value && observer) {
+      observer.observe(originSlot.value)
+    }
+  })
+
+  onBeforeUnmount(() => {
+    observer?.disconnect()
+
+    if (syncFrame.value !== null) {
+      cancelAnimationFrame(syncFrame.value)
+      syncFrame.value = null
+    }
+  })
+
+  return {
+    expanded,
+    busy,
+    backgroundCollapsed,
+    originHeight,
+    overlayStyle,
+    canvas,
+    originSlot,
+    toggleCardMode,
+  }
+}
diff --git a/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
new file mode 100644
index 0000000..e4f72cb
--- /dev/null
+++ b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
@@ -0,0 +1,266 @@
+/* eslint-disable max-lines-per-function */
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+} from 'vue'
+
+import { getSurfaceStateDescriptor } from '@modulify/m3-foundation/lib/surface/descriptor'
+import { m3MotionDurations } from '@modulify/m3-foundation/lib/motion'
+
+import {
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 32
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const DOCKED_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('docked_side_sheet')
+const MODAL_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('modal_side_sheet')
+const DOCKED_HOST_WIDTH = `clamp(${SIDE_SHEET_WIDTH_MIN}px, ${SIDE_SHEET_WIDTH_RATIO}%, ${SIDE_SHEET_WIDTH_MAX}px)`
+
+export function useSurfaceSideSheetMorph() {
+  type SurfaceGeometry = {
+    width: number;
+    insetTop: number;
+    insetRight: number;
+    insetBottom: number;
+  }
+
+  const sideSheetModal = ref(false)
+  const sideSheetWidth = ref(SIDE_SHEET_WIDTH_MIN)
+  const dockedHostExpanded = ref(true)
+  const dockedPanelShown = ref(true)
+  const dockedPanelHidden = ref(false)
+  const modalShown = ref(false)
+  const modalScrimShown = ref(false)
+  const modalWidth = ref(sideSheetWidth.value)
+  const modalInsetTop = ref(MODAL_INSET_TOP)
+  const modalInsetRight = ref(MODAL_INSET_END)
+  const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
+  const modalRadiusLeft = ref<number>(DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+  const modalElevation = ref<number>(DOCKED_SIDE_SHEET_DESCRIPTOR.elevation)
+  const modalRole = ref<'surface-container-low' | 'surface-container-high'>(DOCKED_SIDE_SHEET_DESCRIPTOR.variant)
+  const modalTransitionMs = ref<number>(PANEL_TRANSITION_MS)
+  const transitioning = ref(false)
+  const lastDockedGeometry = ref<SurfaceGeometry | null>(null)
+  const dockedHost = ref<HTMLElement | null>(null)
+  const layoutRoot = ref<HTMLElement | null>(null)
+
+  function measureDockedGeometry() {
+    const host = dockedHost.value
+    if (!host) {
+      return null
+    }
+
+    const rect = host.getBoundingClientRect()
+    const width = Math.round(rect.width)
+
+    if (width > 0) {
+      sideSheetWidth.value = width
+    }
+
+    return {
+      width: width > 0 ? width : sideSheetWidth.value,
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+  }
+
+  function measureDockedPanelGeometry(): SurfaceGeometry | null {
+    const panel = dockedHost.value?.querySelector('[data-panel-mode="docked"]') as HTMLElement | null
+    if (!panel) {
+      return null
+    }
+
+    const rect = panel.getBoundingClientRect()
+    const geometry = {
+      width: Math.round(rect.width),
+      insetTop: Math.round(rect.top),
+      insetRight: Math.round(window.innerWidth - rect.right),
+      insetBottom: Math.round(window.innerHeight - rect.bottom),
+    }
+
+    sideSheetWidth.value = geometry.width
+    lastDockedGeometry.value = geometry
+
+    return geometry
+  }
+
+  async function syncDockedGeometry() {
+    await nextTick()
+    await raf()
+
+    const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+    if (!docked || sideSheetModal.value) {
+      return
+    }
+
+    modalWidth.value = docked.width
+    modalInsetTop.value = docked.insetTop
+    modalInsetRight.value = docked.insetRight
+    modalInsetBottom.value = docked.insetBottom
+  }
+
+  async function switchDockedToModal() {
+    const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+    if (!docked) {
+      return
+    }
+
+    modalTransitionMs.value = PANEL_TRANSITION_MS
+    modalWidth.value = docked.width
+    modalInsetTop.value = docked.insetTop
+    modalInsetRight.value = docked.insetRight
+    modalInsetBottom.value = docked.insetBottom
+    modalRadiusLeft.value = DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+    modalElevation.value = DOCKED_SIDE_SHEET_DESCRIPTOR.elevation
+    modalRole.value = DOCKED_SIDE_SHEET_DESCRIPTOR.variant
+    dockedPanelShown.value = true
+    dockedPanelHidden.value = true
+    modalShown.value = true
+
+    await nextTick()
+    await raf()
+
+    modalScrimShown.value = MODAL_SIDE_SHEET_DESCRIPTOR.scrim
+    dockedHostExpanded.value = false
+    sideSheetModal.value = true
+    modalWidth.value = docked.width
+    modalInsetTop.value = MODAL_INSET_TOP
+    modalInsetRight.value = MODAL_INSET_END
+    modalInsetBottom.value = MODAL_INSET_BOTTOM
+    modalRadiusLeft.value = MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+    modalElevation.value = MODAL_SIDE_SHEET_DESCRIPTOR.elevation
+    modalRole.value = MODAL_SIDE_SHEET_DESCRIPTOR.variant
+
+    await wait(PANEL_TRANSITION_MS)
+
+    dockedPanelShown.value = false
+  }
+
+  async function switchModalToDocked() {
+    dockedHostExpanded.value = true
+    dockedPanelShown.value = true
+    dockedPanelHidden.value = true
+
+    await nextTick()
+    await raf()
+
+    const dockedTarget = lastDockedGeometry.value ?? measureDockedPanelGeometry() ?? measureDockedGeometry()
+    if (!dockedTarget) {
+      return
+    }
+
+    modalTransitionMs.value = PANEL_TRANSITION_MS
+    modalScrimShown.value = false
+    modalElevation.value = DOCKED_SIDE_SHEET_DESCRIPTOR.elevation
+    modalRole.value = DOCKED_SIDE_SHEET_DESCRIPTOR.variant
+    modalRadiusLeft.value = DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+    modalWidth.value = dockedTarget.width
+    modalInsetTop.value = dockedTarget.insetTop
+    modalInsetRight.value = dockedTarget.insetRight
+    modalInsetBottom.value = dockedTarget.insetBottom
+
+    await wait(PANEL_TRANSITION_MS)
+
+    sideSheetModal.value = false
+    modalShown.value = false
+    dockedPanelHidden.value = false
+  }
+
+  async function toggleSideSheetMode() {
+    if (transitioning.value) {
+      return
+    }
+
+    transitioning.value = true
+
+    if (!sideSheetModal.value) {
+      await switchDockedToModal()
+      transitioning.value = false
+      return
+    }
+
+    await switchModalToDocked()
+    transitioning.value = false
+  }
+
+  async function closeModalFromPanel() {
+    if (!sideSheetModal.value || transitioning.value) {
+      return
+    }
+
+    transitioning.value = true
+    await switchModalToDocked()
+    transitioning.value = false
+  }
+
+  async function onResize() {
+    if (dockedHostExpanded.value) {
+      await syncDockedGeometry()
+    }
+  }
+
+  onMounted(async () => {
+    await syncDockedGeometry()
+    window.addEventListener('resize', onResize, { passive: true })
+  })
+
+  onBeforeUnmount(() => {
+    window.removeEventListener('resize', onResize)
+  })
+
+  const dockedHostStyle = computed(() => ({
+    width: dockedHostExpanded.value ? DOCKED_HOST_WIDTH : '0px',
+  }))
+
+  const dockedPanelStyle = computed(() => ({
+    visibility: dockedPanelHidden.value ? 'hidden' : 'visible',
+  }))
+
+  const modalPanelProps = computed(() => ({
+    shown: true as const,
+    scrimShown: modalScrimShown.value,
+    anchor: MODAL_SIDE_SHEET_DESCRIPTOR.anchor,
+    fillWidth: MODAL_SIDE_SHEET_DESCRIPTOR.fillWidth,
+    fillHeight: MODAL_SIDE_SHEET_DESCRIPTOR.fillHeight,
+    width: modalWidth.value,
+    insetTop: modalInsetTop.value,
+    insetRight: modalInsetRight.value,
+    insetBottom: modalInsetBottom.value,
+    roundingTopLeft: modalRadiusLeft.value,
+    roundingBottomLeft: modalRadiusLeft.value,
+    roundingTopRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight,
+    roundingBottomRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight,
+    transitionMs: modalTransitionMs.value,
+    zIndex: 520,
+    variant: modalRole.value,
+    elevation: modalElevation.value,
+    overflow: MODAL_SIDE_SHEET_DESCRIPTOR.overflow,
+  }))
+
+  return {
+    sideSheetModal,
+    sideSheetWidth,
+    transitioning,
+    modalShown,
+    dockedPanelShown,
+    dockedHost,
+    layoutRoot,
+    dockedHostStyle,
+    dockedPanelStyle,
+    modalPanelProps,
+    toggleSideSheetMode,
+    closeModalFromPanel,
+  }
+}
diff --git a/m3-vue/src/components/surface/shared.ts b/m3-vue/src/components/surface/shared.ts
new file mode 100644
index 0000000..60919fd
--- /dev/null
+++ b/m3-vue/src/components/surface/shared.ts
@@ -0,0 +1,163 @@
+import type {
+  CSSProperties,
+  PropType,
+} from 'vue'
+import type {
+  Length as SurfaceLength,
+  Variant as SurfaceVariant,
+} from '@modulify/m3-foundation/types/components/surface'
+
+import {
+  DEFAULT_SURFACE_TRANSITION_TIMING,
+  getSurfacePanelClassRecord,
+  getSurfacePanelStyle as getFoundationSurfacePanelStyle,
+} from '@modulify/m3-foundation/lib/surface/style'
+
+export {
+  getModalAnchorStyle,
+  getResolvedVariant,
+  getSurfaceTransition,
+  getVariantClassName,
+  isDefined,
+  toLength,
+} from '@modulify/m3-foundation/lib/surface/style'
+import {
+  isId,
+  isUndefined,
+  Or,
+} from '@modulify/m3-foundation/lib/predicates'
+
+export const surfacePanelProps = {
+  id: {
+    type: null as unknown as PropType<string | undefined>,
+    validator: Or(isId, isUndefined),
+    default: undefined,
+  },
+
+  tag: {
+    type: String,
+    default: 'section',
+  },
+
+  elevation: {
+    type: Number,
+    default: 0,
+    validator: (value: number) => Number.isInteger(value) && value >= 0 && value <= 5,
+  },
+
+  variant: {
+    type: String as PropType<SurfaceVariant>,
+    default: 'auto',
+  },
+
+  fillWidth: {
+    type: Boolean,
+    default: true,
+  },
+
+  fillHeight: {
+    type: Boolean,
+    default: true,
+  },
+
+  width: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  height: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  minWidth: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  maxWidth: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  minHeight: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  maxHeight: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  rounding: {
+    type: null as unknown as PropType<SurfaceLength>,
+    default: 0,
+  },
+
+  roundingTopLeft: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  roundingTopRight: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  roundingBottomRight: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  roundingBottomLeft: {
+    type: null as unknown as PropType<SurfaceLength | null>,
+    default: null,
+  },
+
+  transitionMs: {
+    type: Number,
+    default: 220,
+  },
+
+  transitionTiming: {
+    type: String,
+    default: DEFAULT_SURFACE_TRANSITION_TIMING,
+  },
+
+  overflow: {
+    type: String,
+    default: 'visible',
+  },
+} as const
+
+export function getSurfacePanelClass(elevation: number, variant: SurfaceVariant) {
+  return getSurfacePanelClassRecord(elevation, variant)
+}
+
+type SurfacePanelStyleInput = {
+  fillWidth: boolean,
+  fillHeight: boolean,
+  width: SurfaceLength | null,
+  height: SurfaceLength | null,
+  minWidth: SurfaceLength | null,
+  maxWidth: SurfaceLength | null,
+  minHeight: SurfaceLength | null,
+  maxHeight: SurfaceLength | null,
+  rounding: SurfaceLength,
+  roundingTopLeft: SurfaceLength | null,
+  roundingTopRight: SurfaceLength | null,
+  roundingBottomRight: SurfaceLength | null,
+  roundingBottomLeft: SurfaceLength | null,
+  transitionMs: number,
+  transitionTiming: string,
+  overflow: CSSProperties['overflow'],
+  style?: CSSProperties,
+}
+
+export const getSurfacePanelStyle = (
+  options: SurfacePanelStyleInput
+): CSSProperties => getFoundationSurfacePanelStyle({
+  ...options,
+  style: options.style as object | undefined,
+}) as CSSProperties
diff --git a/m3-vue/src/index.ts b/m3-vue/src/index.ts
index 542a779..b8ad7e4 100644
--- a/m3-vue/src/index.ts
+++ b/m3-vue/src/index.ts
@@ -80,6 +80,7 @@ export {
 
 export {
   M3Surface,
+  M3SurfacePanel,
 } from '@/components/surface'
 
 export {
diff --git a/m3-vue/storybook/components/M3SideSheet.mdx b/m3-vue/storybook/components/M3SideSheet.mdx
new file mode 100644
index 0000000..1e33892
--- /dev/null
+++ b/m3-vue/storybook/components/M3SideSheet.mdx
@@ -0,0 +1,42 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SideSheetStories from './M3SideSheet.stories'
+
+<Meta of={M3SideSheetStories} />
+
+# Side Sheets
+
+Side sheets extend `M3Surface` into a right-edge panel with dedicated header, scrollable content area, and optional footer actions.
+
+## Accessibility semantics
+
+- Use a clear title so the sheet can expose `aria-labelledby`.
+- Keep close affordances discoverable through the close button and, in modal mode, the scrim.
+- Reserve footer actions for final or high-signal decisions.
+
+## Stories
+
+- [Standard](?path=/story/components-m3sidesheet--standard)
+- [Docked](?path=/story/components-m3sidesheet--docked)
+
+## Code example
+
+```html
+<M3SideSheet :shown="opened" @update:shown="opened = $event">
+    <template #title>Filters</template>
+    <template #close-icon>
+        <M3Icon name="close" />
+    </template>
+
+    <p class="m-4">Choose filters and apply changes.</p>
+
+    <template #footer>
+        <div class="p-4">Footer actions</div>
+    </template>
+</M3SideSheet>
+```
+
+## Resources
+
+- [M3 Side sheets overview](https://m3.material.io/components/navigation-drawer/overview)
+- [M3 Side sheets guidelines](https://m3.material.io/components/navigation-drawer/guidelines)
+- [WAI-ARIA APG: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
diff --git a/m3-vue/storybook/components/M3SideSheet.stories.ts b/m3-vue/storybook/components/M3SideSheet.stories.ts
new file mode 100644
index 0000000..347f32f
--- /dev/null
+++ b/m3-vue/storybook/components/M3SideSheet.stories.ts
@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3SideSheet } from '@/components/side-sheet'
+
+import { ref } from 'vue'
+
+const sideSheetStoryTemplate = `
+    <M3Button @click="shown = true">
+        Open side sheet
+    </M3Button>
+
+    <M3SideSheet
+        v-bind="args"
+        :shown="shown"
+        @update:shown="shown = $event"
+    >
+        <template #title>
+            Filters
+        </template>
+
+        <template #close-icon>
+            <M3Icon name="close" />
+        </template>
+
+        <p class="m-4">Choose filters and apply changes.</p>
+
+        <template #footer>
+            <div class="p-4">Footer actions</div>
+        </template>
+    </M3SideSheet>
+`
+
+const meta = {
+  title: 'Components/M3SideSheet',
+
+  component: M3SideSheet,
+
+  argTypes: {
+    shown: {
+      control: false,
+    },
+  },
+
+  args: {
+    docked: false,
+  },
+
+  render: (args: unknown) => ({
+    components: {
+      M3Button,
+      M3Icon,
+      M3SideSheet,
+    },
+
+    setup () {
+      const shown = ref(false)
+
+      return {
+        args,
+        shown,
+      }
+    },
+
+    template: sideSheetStoryTemplate,
+  }),
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3SideSheet>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {}
+
+export const Docked: Story = {
+  args: {
+    docked: true,
+  },
+}
diff --git a/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
index 48b5e8b..8872c28 100644
--- a/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceCardPageMorph.vue
@@ -4,7 +4,7 @@
         :data-card-expanded="expanded ? 'true' : 'false'"
         data-testid="surface-card-page-root"
     >
-        <M3Surface
+        <M3SurfacePanel
             class="surface-card-page__topbar"
             :fill-height="false"
             :height="72"
@@ -26,7 +26,7 @@
                     {{ expanded ? 'Return to card state' : 'Expand card to page state' }}
                 </M3Button>
             </div>
-        </M3Surface>
+        </M3SurfacePanel>
 
         <M3Navigation
             v-model:expanded="navExpanded"
@@ -78,7 +78,7 @@
 
         <div class="surface-card-page__body">
             <div class="surface-card-page__workspace">
-                <M3Surface
+                <M3SurfacePanel
                     class="surface-card-page__header-card"
                     :fill-height="false"
                     :height="120"
@@ -88,7 +88,7 @@
                 >
                     <h3>Card-to-page transition playground</h3>
                     <p>Original slot remains reserved while the morphing surface overlays the page area.</p>
-                </M3Surface>
+                </M3SurfacePanel>
 
                 <div
                     ref="canvas"
@@ -103,11 +103,54 @@
                         <div
                             ref="originSlot"
                             class="surface-card-page__origin-slot"
-                            :style="{ minHeight: `${originHeight}px` }"
+                            :class="{ 'surface-card-page__origin-slot_filled': !overlayActive }"
+                            :style="overlayActive ? { minHeight: `${originHeight}px` } : undefined"
                             data-testid="surface-card-origin"
-                        />
+                        >
+                            <div
+                                v-if="!overlayActive"
+                                class="surface-card-page__overlay-wrap surface-card-page__overlay-wrap_inline"
+                                :style="compactWrapStyle"
+                                data-testid="surface-card-overlay-wrap"
+                            >
+                                <M3SurfacePanel
+                                    :class="[
+                                        'surface-card-page__morph-surface',
+                                        expanded
+                                            ? 'surface-card-page__morph-surface_expanded'
+                                            : 'surface-card-page__morph-surface_compact',
+                                    ]"
+                                    :fill-width="true"
+                                    :fill-height="overlayActive"
+                                    :rounding="expanded ? 0 : 24"
+                                    :transition-ms="TRANSITION_MS"
+                                    :transition-timing="TRANSITION_EASING"
+                                    :variant="expanded ? 'surface' : 'surface-container-low'"
+                                    :elevation="expanded ? 0 : 1"
+                                    overflow="auto"
+                                    data-testid="surface-card-morph"
+                                >
+                                    <h3>Morph target surface</h3>
+                                    <p>
+                                        In compact mode this surface behaves like a card. In expanded mode it replaces the
+                                        page work area while keeping top bar and rail reserved.
+                                    </p>
+
+                                    <M3SurfacePanel
+                                        class="surface-card-page__morph-nested"
+                                        :fill-height="false"
+                                        :height="120"
+                                        :rounding="14"
+                                        :variant="expanded ? 'surface-container-low' : 'surface-container-high'"
+                                        :elevation="expanded ? 1 : 3"
+                                    >
+                                        Nested surface demonstrates composability in both states.
+                                    </M3SurfacePanel>
+                                </M3SurfacePanel>
+                            </div>
+                        </div>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-card-page__grid-card"
                             :fill-height="false"
                             :height="184"
@@ -117,9 +160,9 @@
                         >
                             <strong>Static card A</strong>
                             <p>Background content remains in flow.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-card-page__grid-card"
                             :fill-height="false"
                             :height="184"
@@ -129,16 +172,19 @@
                         >
                             <strong>Static card B</strong>
                             <p>Independent surface in the same scene.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
                     </div>
 
-                    <div class="surface-card-page__overlay">
+                    <div
+                        v-if="overlayActive"
+                        class="surface-card-page__overlay"
+                    >
                         <div
                             class="surface-card-page__overlay-wrap"
                             :style="overlayStyle"
                             data-testid="surface-card-overlay-wrap"
                         >
-                            <M3Surface
+                            <M3SurfacePanel
                                 :class="[
                                     'surface-card-page__morph-surface',
                                     expanded
@@ -146,7 +192,7 @@
                                         : 'surface-card-page__morph-surface_compact',
                                 ]"
                                 :fill-width="true"
-                                :fill-height="true"
+                                :fill-height="overlayActive"
                                 :rounding="expanded ? 0 : 24"
                                 :transition-ms="TRANSITION_MS"
                                 :transition-timing="TRANSITION_EASING"
@@ -161,7 +207,7 @@
                                     page work area while keeping top bar and rail reserved.
                                 </p>
 
-                                <M3Surface
+                                <M3SurfacePanel
                                     class="surface-card-page__morph-nested"
                                     :fill-height="false"
                                     :height="120"
@@ -170,8 +216,8 @@
                                     :elevation="expanded ? 1 : 3"
                                 >
                                     Nested surface demonstrates composability in both states.
-                                </M3Surface>
-                            </M3Surface>
+                                </M3SurfacePanel>
+                            </M3SurfacePanel>
                         </div>
                     </div>
                 </div>
@@ -188,173 +234,39 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/components/surface/M3Surface.vue'
-
 import {
-  computed,
-  nextTick,
-  onMounted,
-  ref,
-} from 'vue'
+  M3SurfacePanel,
+} from '@/components/surface'
+import { useSurfaceCardPageMorph } from '@/components/surface/orchestration/useSurfaceCardPageMorph'
+
 import {
   m3MotionDurations,
   m3MotionEasings,
 } from '@modulify/m3-foundation/lib/motion'
+import {
+  computed,
+  ref,
+} from 'vue'
 
-const expanded = ref(false)
-const busy = ref(false)
 const navExpanded = ref(false)
-const backgroundCollapsed = ref(false)
 const activeNavTab = ref<'files' | 'timeline' | 'tasks' | 'analytics'>('files')
 const TRANSITION_MS = m3MotionDurations.medium3
 const TRANSITION_EASING = m3MotionEasings.standard
 
-const canvas = ref<HTMLElement | null>(null)
-const originSlot = ref<HTMLElement | null>(null)
-const originHeight = ref(220)
-
-const motion = ref({
-  top: 16,
-  left: 16,
-  width: 320,
-  height: 220,
-})
-
-const overlayStyle = computed(() => ({
-  top: `${motion.value.top}px`,
-  left: `${motion.value.left}px`,
-  width: `${motion.value.width}px`,
-  height: `${motion.value.height}px`,
+const {
+  expanded,
+  busy,
+  backgroundCollapsed,
+  originHeight,
+  overlayStyle,
+  canvas,
+  originSlot,
+  toggleCardMode,
+} = useSurfaceCardPageMorph(TRANSITION_MS)
+const overlayActive = computed(() => busy.value || expanded.value)
+const compactWrapStyle = computed(() => ({
+  width: '100%',
 }))
-
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-function measureOrigin() {
-  if (!canvas.value || !originSlot.value) {
-    return null
-  }
-
-  const canvasRect = canvas.value.getBoundingClientRect()
-  const originRect = originSlot.value.getBoundingClientRect()
-
-  return {
-    top: originRect.top - canvasRect.top,
-    left: originRect.left - canvasRect.left,
-    width: originRect.width,
-    height: originRect.height,
-  }
-}
-
-function measureExpanded() {
-  if (!canvas.value) {
-    return null
-  }
-
-  const canvasRect = canvas.value.getBoundingClientRect()
-
-  return {
-    top: 0,
-    left: 0,
-    width: canvasRect.width,
-    height: canvasRect.height,
-  }
-}
-
-async function initMotion() {
-  await nextTick()
-  await raf()
-
-  const origin = measureOrigin()
-  if (!origin) {
-    return
-  }
-
-  motion.value = origin
-  originHeight.value = origin.height
-}
-
-async function expandCard() {
-  backgroundCollapsed.value = false
-
-  const origin = measureOrigin()
-  if (origin) {
-    motion.value = origin
-    originHeight.value = origin.height
-  }
-
-  expanded.value = true
-  await nextTick()
-  await raf()
-
-  const full = measureExpanded()
-  if (!full) {
-    return
-  }
-
-  motion.value = full
-  await wait(TRANSITION_MS)
-  backgroundCollapsed.value = true
-}
-
-async function collapseCard() {
-  if (backgroundCollapsed.value) {
-    backgroundCollapsed.value = false
-    await nextTick()
-    await raf()
-  }
-
-  const full = measureExpanded()
-  if (full) {
-    motion.value = full
-  }
-
-  const origin = measureOrigin()
-  if (origin) {
-    originHeight.value = origin.height
-  }
-
-  expanded.value = false
-  await nextTick()
-  await raf()
-
-  if (!origin) {
-    return
-  }
-
-  motion.value = origin
-  await wait(TRANSITION_MS)
-}
-
-async function toggleCardMode() {
-  if (busy.value) {
-    return
-  }
-
-  busy.value = true
-
-  if (expanded.value) {
-    await collapseCard()
-    busy.value = false
-    return
-  }
-
-  await expandCard()
-  busy.value = false
-}
-
-onMounted(() => {
-  initMotion()
-})
 </script>
 
 <style lang="scss" scoped>
@@ -477,6 +389,11 @@ onMounted(() => {
     background: var(--surface-origin-slot);
 }
 
+.surface-card-page__origin-slot_filled {
+    border-color: transparent;
+    background: transparent;
+}
+
 .surface-card-page__overlay {
     position: absolute;
     inset: 0;
@@ -492,6 +409,15 @@ onMounted(() => {
         height #{m3-motion.duration('medium3')} #{m3-motion.easing('standard')};
 }
 
+.surface-card-page__overlay-wrap_inline {
+    position: relative;
+    transition: none;
+}
+
+.surface-card-page__overlay-wrap_inline > .surface-card-page__morph-surface {
+    box-sizing: border-box;
+}
+
 .surface-card-page__morph-surface {
     pointer-events: auto;
 }
diff --git a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
index 8d2039e..5845946 100644
--- a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
@@ -162,6 +162,10 @@
 import { M3Button } from '@/components/button'
 import { M3Icon } from '@/components/icon'
 import { M3IconButton } from '@/components/icon-button'
+import {
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   M3Navigation,
   M3NavigationTab,
@@ -229,18 +233,6 @@ const topDialogLevel = computed(() => {
   return -1
 })
 
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
 function hasNextDialog(level: number) {
   return level < dialogChain.length - 1
 }
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
index e84a027..5469694 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetAlwaysModal.vue
@@ -204,6 +204,11 @@
 import { M3Button } from '@/components/button'
 import { M3Icon } from '@/components/icon'
 import { M3IconButton } from '@/components/icon-button'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   M3Navigation,
   M3NavigationTab,
@@ -244,22 +249,6 @@ const modalVisible = ref(false)
 const transitioning = ref(false)
 const layoutRoot = ref<HTMLElement | null>(null)
 
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value))
-}
-
 function hiddenInsetRight() {
   return -(sideSheetWidth.value + 12)
 }
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
index 199ca6c..19e7f0b 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetDismissToRemove.vue
@@ -224,6 +224,11 @@
 import { M3Button } from '@/components/button'
 import { M3Icon } from '@/components/icon'
 import { M3IconButton } from '@/components/icon-button'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 import {
   M3Navigation,
   M3NavigationTab,
@@ -272,22 +277,6 @@ const transitioning = ref(false)
 const dockedHost = ref<HTMLElement | null>(null)
 const layoutRoot = ref<HTMLElement | null>(null)
 
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value))
-}
-
 function hiddenInsetRight() {
   return -(modalWidth.value + 12)
 }
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
index a554bf4..53f1fb7 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetModalToWindow.vue
@@ -5,7 +5,7 @@
         :data-panel-mounted="modalMounted ? 'true' : 'false'"
         data-testid="surface-window-root"
     >
-        <M3Surface
+        <M3SurfacePanel
             class="surface-side-sheet-window__topbar"
             :fill-height="false"
             :height="72"
@@ -27,7 +27,7 @@
                     {{ modalMounted ? 'Modal panel is open' : 'Show modal side sheet' }}
                 </M3Button>
             </div>
-        </M3Surface>
+        </M3SurfacePanel>
 
         <M3Navigation
             v-model:expanded="navExpanded"
@@ -79,7 +79,7 @@
 
         <div class="surface-side-sheet-window__body">
             <div class="surface-side-sheet-window__workspace">
-                <M3Surface
+                <M3SurfacePanel
                     class="surface-side-sheet-window__header-card"
                     :fill-height="false"
                     :height="120"
@@ -89,7 +89,7 @@
                 >
                     <h3>Workspace surfaces</h3>
                     <p>Background layout stays in flow while the modal panel morphs between side-sheet and window geometries.</p>
-                </M3Surface>
+                </M3SurfacePanel>
 
                 <div
                     ref="layoutRoot"
@@ -100,7 +100,7 @@
                         class="surface-side-sheet-window__content-grid"
                         data-testid="surface-window-content-grid"
                     >
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet-window__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -110,9 +110,9 @@
                         >
                             <strong>surface-container-lowest</strong>
                             <p>Read-heavy content block in the page flow.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet-window__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -122,9 +122,9 @@
                         >
                             <strong>surface-container-low</strong>
                             <p>Secondary block with mild emphasis.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet-window__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -134,9 +134,9 @@
                         >
                             <strong>surface-container-high</strong>
                             <p>Contextual utility content.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet-window__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -146,7 +146,7 @@
                         >
                             <strong>surface-dim</strong>
                             <p>Low-brightness complementary content.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
                     </main>
 
                     <M3Surface
@@ -303,7 +303,15 @@ import {
 } from '@/components/navigation'
 import { M3Select } from '@/components/select'
 import { M3TextField } from '@/components/text-field'
-import M3Surface from '@/components/surface/M3Surface.vue'
+import {
+  M3Surface,
+  M3SurfacePanel,
+} from '@/components/surface'
+import {
+  clamp,
+  raf,
+  wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
 
 import {
   computed,
@@ -313,6 +321,7 @@ import {
   reactive,
   ref,
 } from 'vue'
+import { getSurfaceStateDescriptor } from '@modulify/m3-foundation/lib/surface/descriptor'
 import {
   m3MotionDurations,
   m3MotionEasings,
@@ -335,6 +344,9 @@ const PANEL_TRANSITION_MS = m3MotionDurations.medium4
 const PANEL_TRANSITION_EASING = m3MotionEasings.standard
 const SCRIM_FADE_MS = m3MotionDurations.long2
 const DIALOG_HIDE_MS = m3MotionDurations.long2
+const HIDDEN_SURFACE_DESCRIPTOR = getSurfaceStateDescriptor('hidden')
+const MODAL_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('modal_side_sheet')
+const MODAL_DIALOG_DESCRIPTOR = getSurfaceStateDescriptor('modal_dialog_window')
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
@@ -342,8 +354,8 @@ const sideSheetWidth = ref(320)
 const windowWidth = ref(720)
 
 const modalInsetRight = ref(-(sideSheetWidth.value + 12))
-const modalRadiusLeft = ref(0)
-const modalElevationBase = ref(0)
+const modalRadiusLeft = ref(HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft)
+const modalElevationBase = ref(HIDDEN_SURFACE_DESCRIPTOR.elevation)
 
 const modalMounted = ref(false)
 const modalVisible = ref(false)
@@ -383,15 +395,21 @@ const priorityOptions = [{
   value: 'high',
 }]
 
-const panelAnchor = computed(() => panelAsWindow.value ? 'center' : 'end')
+const panelAnchor = computed(() => panelAsWindow.value ? MODAL_DIALOG_DESCRIPTOR.anchor : MODAL_SIDE_SHEET_DESCRIPTOR.anchor)
 const panelWidth = computed(() => panelAsWindow.value ? windowWidth.value : sideSheetWidth.value)
 const panelInsetRight = computed(() => panelAsWindow.value ? 0 : modalInsetRight.value)
-const panelRoundingTopLeft = computed(() => panelAsWindow.value ? 28 : modalRadiusLeft.value)
-const panelRoundingBottomLeft = computed(() => panelAsWindow.value ? 28 : modalRadiusLeft.value)
-const panelRoundingTopRight = computed(() => panelAsWindow.value ? 28 : 0)
-const panelRoundingBottomRight = computed(() => panelAsWindow.value ? 28 : 0)
-const panelSurfaceRole = computed(() => panelAsWindow.value ? 'surface-container-highest' : 'surface-container-high')
-const panelElevation = computed(() => panelAsWindow.value ? Math.max(2, modalElevationBase.value) : modalElevationBase.value)
+const panelRoundingTopLeft = computed(() => panelAsWindow.value ? MODAL_DIALOG_DESCRIPTOR.rounding.topLeft : modalRadiusLeft.value)
+const panelRoundingBottomLeft = computed(() => panelAsWindow.value ? MODAL_DIALOG_DESCRIPTOR.rounding.bottomLeft : modalRadiusLeft.value)
+const panelRoundingTopRight = computed(() => panelAsWindow.value
+  ? MODAL_DIALOG_DESCRIPTOR.rounding.topRight
+  : MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight)
+const panelRoundingBottomRight = computed(() => panelAsWindow.value
+  ? MODAL_DIALOG_DESCRIPTOR.rounding.bottomRight
+  : MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight)
+const panelSurfaceRole = computed(() => panelAsWindow.value ? MODAL_DIALOG_DESCRIPTOR.variant : MODAL_SIDE_SHEET_DESCRIPTOR.variant)
+const panelElevation = computed(() => panelAsWindow.value
+  ? Math.max(MODAL_DIALOG_DESCRIPTOR.elevation, modalElevationBase.value)
+  : modalElevationBase.value)
 const panelTransitionMs = computed(() => {
   if (panelAsWindow.value && windowClosing.value) {
     return DIALOG_HIDE_MS
@@ -411,22 +429,6 @@ const panelInlineStyle = computed(() => {
   }
 })
 
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value))
-}
-
 function hiddenInsetRight() {
   return -(sideSheetWidth.value + 12)
 }
@@ -463,8 +465,8 @@ async function openModal() {
   windowClosing.value = false
   syncDimensions()
 
-  modalRadiusLeft.value = 0
-  modalElevationBase.value = 0
+  modalRadiusLeft.value = HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft
+  modalElevationBase.value = HIDDEN_SURFACE_DESCRIPTOR.elevation
   modalInsetRight.value = hiddenInsetRight()
   modalMounted.value = true
 
@@ -477,8 +479,8 @@ async function openModal() {
   await raf()
 
   modalInsetRight.value = MODAL_INSET_END
-  modalRadiusLeft.value = 28
-  modalElevationBase.value = 1
+  modalRadiusLeft.value = MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+  modalElevationBase.value = MODAL_SIDE_SHEET_DESCRIPTOR.elevation
   await wait(PANEL_TRANSITION_MS)
   transitioning.value = false
 }
@@ -532,16 +534,16 @@ async function closeWindowModal() {
   modalMounted.value = false
 
   modalInsetRight.value = hiddenInsetRight()
-  modalRadiusLeft.value = 0
-  modalElevationBase.value = 0
+  modalRadiusLeft.value = HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft
+  modalElevationBase.value = HIDDEN_SURFACE_DESCRIPTOR.elevation
   windowClosing.value = false
   panelAsWindow.value = false
 }
 
 async function closeSideSheetModal() {
   modalInsetRight.value = hiddenInsetRight()
-  modalRadiusLeft.value = 0
-  modalElevationBase.value = 0
+  modalRadiusLeft.value = HIDDEN_SURFACE_DESCRIPTOR.rounding.topLeft
+  modalElevationBase.value = HIDDEN_SURFACE_DESCRIPTOR.elevation
   await wait(PANEL_TRANSITION_MS)
 
   modalVisible.value = false
diff --git a/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
index 787b53d..8d78174 100644
--- a/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceSideSheetMorph.vue
@@ -4,7 +4,7 @@
         :data-sheet-modal="sideSheetModal ? 'true' : 'false'"
         data-testid="surface-morph-root"
     >
-        <M3Surface
+        <M3SurfacePanel
             class="surface-side-sheet__topbar"
             :fill-height="false"
             :height="72"
@@ -26,7 +26,7 @@
                     {{ sideSheetModal ? 'Switch to docked sheet' : 'Switch to modal sheet' }}
                 </M3Button>
             </div>
-        </M3Surface>
+        </M3SurfacePanel>
 
         <M3Navigation
             v-model:expanded="navExpanded"
@@ -78,7 +78,7 @@
 
         <div class="surface-side-sheet__body">
             <div class="surface-side-sheet__workspace">
-                <M3Surface
+                <M3SurfacePanel
                     class="surface-side-sheet__header-card"
                     :fill-height="false"
                     :height="120"
@@ -88,7 +88,7 @@
                 >
                     <h3>Workspace surfaces</h3>
                     <p>Static blocks keep flow while side-sheet changes modality.</p>
-                </M3Surface>
+                </M3SurfacePanel>
 
                 <div
                     ref="layoutRoot"
@@ -99,7 +99,7 @@
                         class="surface-side-sheet__content-grid"
                         data-testid="surface-morph-content-grid"
                     >
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -109,9 +109,9 @@
                         >
                             <strong>surface-container-lowest</strong>
                             <p>Read-heavy content block in the page flow.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -121,9 +121,9 @@
                         >
                             <strong>surface-container-low</strong>
                             <p>Secondary block with mild emphasis.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -133,9 +133,9 @@
                         >
                             <strong>surface-container-high</strong>
                             <p>Contextual utility content.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
 
-                        <M3Surface
+                        <M3SurfacePanel
                             class="surface-side-sheet__grid-surface"
                             :fill-height="false"
                             :height="136"
@@ -145,81 +145,68 @@
                         >
                             <strong>surface-dim</strong>
                             <p>Low-brightness complementary content.</p>
-                        </M3Surface>
+                        </M3SurfacePanel>
                     </main>
 
                     <div
                         ref="dockedHost"
                         class="surface-side-sheet__docked-host"
-                        :style="{ width: `${sideSheetDockedWidth}px` }"
+                        :style="dockedHostStyle"
                         data-testid="surface-morph-docked-host"
                     >
-                        <M3Surface
-                            v-if="!sideSheetModal"
-                            class="surface-side-sheet__sheet"
+                        <M3SurfacePanel
+                            v-if="dockedPanelShown"
+                            class="surface-side-sheet__sheet surface-side-sheet__sheet_docked"
                             :fill-width="true"
                             :fill-height="true"
-                            :rounding="0"
+                            overflow="auto"
                             variant="surface-container-low"
                             :elevation="0"
-                            overflow="auto"
-                            data-testid="surface-morph-docked-sheet"
+                            :style="dockedPanelStyle"
+                            data-testid="surface-morph-sheet"
+                            data-panel-mode="docked"
                         >
                             <h3>Docked side sheet</h3>
-                            <p>Coplanar layout participant with fixed width per layout region.</p>
+                            <p>Coplanar layout participant with adaptive CSS width inside the layout host.</p>
                             <p>Main content remains interactive.</p>
                             <p class="surface-side-sheet__meta">
-                                Fixed width: {{ sideSheetWidth }}px
+                                Adaptive width: {{ sideSheetWidth }}px
                             </p>
-                        </M3Surface>
+                        </M3SurfacePanel>
                     </div>
 
                     <M3Surface
                         v-if="modalShown"
                         class="surface-side-sheet__sheet surface-side-sheet__sheet_modal"
                         mode="modal"
-                        :shown="modalVisible"
-                        anchor="end"
-                        :fill-width="false"
-                        :fill-height="false"
-                        :width="modalWidth"
-                        :inset-top="modalInsetTop"
-                        :inset-right="modalInsetRight"
-                        :inset-bottom="modalInsetBottom"
-                        :rounding-top-left="modalRadiusLeft"
-                        :rounding-bottom-left="modalRadiusLeft"
-                        :rounding-top-right="0"
-                        :rounding-bottom-right="0"
-                        :transition-ms="modalTransitionMs"
+                        v-bind="modalPanelProps"
                         :transition-timing="PANEL_TRANSITION_EASING"
-                        :z-index="520"
-                        :variant="modalRole"
-                        :elevation="modalElevation"
-                        overflow="auto"
-                        data-testid="surface-morph-modal-sheet"
+                        data-testid="surface-morph-sheet"
+                        data-panel-mode="modal"
                         @dismiss="closeModalFromPanel"
                     >
-                        <div class="surface-side-sheet__modal-header">
-                            <h3>Modal side sheet</h3>
-
-                            <M3IconButton
-                                v-if="sideSheetModal"
-                                class="surface-side-sheet__modal-close"
-                                appearance="standard"
-                                aria-label="Close modal side sheet"
-                                :disabled="transitioning"
-                                data-testid="surface-morph-close"
-                                @click="closeModalFromPanel"
-                            >
-                                <M3Icon name="close" />
-                            </M3IconButton>
-                        </div>
-
-                        <p>Layer rebind: docked layer to modal layer.</p>
-                        <p>Anchored to end/right edge with full-height modal surface.</p>
-                        <p class="surface-side-sheet__meta">
-                            Fixed width: {{ modalWidth }}px
-                        </p>
+                        <template v-if="sideSheetModal">
+                            <div class="surface-side-sheet__modal-header">
+                                <h3>Modal side sheet</h3>
+
+                                <M3IconButton
+                                    class="surface-side-sheet__modal-close"
+                                    appearance="standard"
+                                    aria-label="Close modal side sheet"
+                                    :disabled="transitioning"
+                                    data-testid="surface-morph-close"
+                                    @click="closeModalFromPanel"
+                                >
+                                    <M3Icon name="close" />
+                                </M3IconButton>
+                            </div>
+
+                            <p>Layer rebind: docked layer to modal layer.</p>
+                            <p>Stable modal state stays in overlay, while docked state remains layout-driven.</p>
+                            <p class="surface-side-sheet__meta">
+                                Measured transition width: {{ modalPanelProps.width }}px
+                            </p>
+                        </template>
                     </M3Surface>
                 </div>
             </div>
@@ -235,247 +222,33 @@ import {
   M3Navigation,
   M3NavigationTab,
 } from '@/components/navigation'
-import M3Surface from '@/components/surface/M3Surface.vue'
-
-import {
-  onBeforeUnmount,
-  onMounted,
-  nextTick,
-  ref,
-} from 'vue'
 import {
-  m3MotionDurations,
-  m3MotionEasings,
-} from '@modulify/m3-foundation/lib/motion'
-
-const SIDE_SHEET_WIDTH_MIN = 280
-const SIDE_SHEET_WIDTH_MAX = 360
-const SIDE_SHEET_WIDTH_RATIO = 0.32
-const SIDE_SHEET_WIDTH_STEP = 4
-
-const MODAL_INSET_TOP = 0
-const MODAL_INSET_BOTTOM = 0
-const MODAL_INSET_END = 0
-const PANEL_TRANSITION_MS = m3MotionDurations.medium2
-const PANEL_VERTICAL_EXPAND_MS = 120
+  M3Surface,
+  M3SurfacePanel,
+} from '@/components/surface'
+import { useSurfaceSideSheetMorph } from '@/components/surface/orchestration/useSurfaceSideSheetMorph'
+
+import { m3MotionEasings } from '@modulify/m3-foundation/lib/motion'
+import { ref } from 'vue'
+
 const PANEL_TRANSITION_EASING = m3MotionEasings.standard
 
 const navExpanded = ref(false)
 const activeNavTab = ref<'inbox' | 'boards' | 'archive' | 'lab'>('inbox')
-const sideSheetModal = ref(false)
-const sideSheetWidth = ref(320)
-const sideSheetDockedWidth = ref(sideSheetWidth.value)
-const modalShown = ref(false)
-const modalVisible = ref(false)
-const modalWidth = ref(sideSheetWidth.value)
-const modalInsetTop = ref(MODAL_INSET_TOP)
-const modalInsetRight = ref(-(sideSheetWidth.value + 12))
-const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
-const modalRadiusLeft = ref(0)
-const modalElevation = ref(0)
-const modalRole = ref<'surface-container-low' | 'surface-container-high'>('surface-container-low')
-const modalTransitionMs = ref(PANEL_TRANSITION_MS)
-const transitioning = ref(false)
-const dockedHost = ref<HTMLElement | null>(null)
-const layoutRoot = ref<HTMLElement | null>(null)
-
-function wait(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(() => resolve(), ms)
-  })
-}
-
-function raf() {
-  return new Promise<void>((resolve) => {
-    requestAnimationFrame(() => resolve())
-  })
-}
-
-function clamp(value: number, min: number, max: number) {
-  return Math.min(max, Math.max(min, value))
-}
-
-function hiddenInsetRight() {
-  return -(modalWidth.value + 12)
-}
-
-function resolveSheetWidthFromLayout() {
-  const layoutWidth = Math.round(layoutRoot.value?.getBoundingClientRect().width ?? window.innerWidth)
-  const estimated = Math.round((layoutWidth * SIDE_SHEET_WIDTH_RATIO) / SIDE_SHEET_WIDTH_STEP) * SIDE_SHEET_WIDTH_STEP
-
-  return clamp(estimated, SIDE_SHEET_WIDTH_MIN, SIDE_SHEET_WIDTH_MAX)
-}
-
-function syncFixedWidth() {
-  const nextWidth = resolveSheetWidthFromLayout()
-
-  sideSheetWidth.value = nextWidth
-  modalWidth.value = nextWidth
-
-  if (!sideSheetModal.value) {
-    sideSheetDockedWidth.value = nextWidth
-    modalInsetRight.value = hiddenInsetRight()
-  }
-}
-
-function measureDockedGeometry() {
-  const host = dockedHost.value
-  if (!host) {
-    return null
-  }
-
-  const rect = host.getBoundingClientRect()
-
-  return {
-    width: Math.round(rect.width),
-    insetTop: Math.round(rect.top),
-    insetRight: Math.round(window.innerWidth - rect.right),
-    insetBottom: Math.round(window.innerHeight - rect.bottom),
-  }
-}
-
-function setModalGeometryFromDocked() {
-  const docked = measureDockedGeometry()
-
-  modalWidth.value = docked?.width ?? sideSheetWidth.value
-  modalInsetTop.value = docked?.insetTop ?? MODAL_INSET_TOP
-  modalInsetRight.value = docked?.insetRight ?? MODAL_INSET_END
-  modalInsetBottom.value = docked?.insetBottom ?? MODAL_INSET_BOTTOM
-}
-
-function setModalGeometryTarget() {
-  modalWidth.value = sideSheetWidth.value
-  modalInsetTop.value = MODAL_INSET_TOP
-  modalInsetRight.value = MODAL_INSET_END
-  modalInsetBottom.value = MODAL_INSET_BOTTOM
-}
-
-async function expandModalToViewportHeight() {
-  // Delay vertical expansion so the morph starts with an X-axis transition.
-  modalTransitionMs.value = PANEL_VERTICAL_EXPAND_MS
-  await nextTick()
-  await raf()
-  setModalGeometryTarget()
-  await wait(PANEL_VERTICAL_EXPAND_MS)
-  modalTransitionMs.value = PANEL_TRANSITION_MS
-}
-
-function resolveDockedTargetGeometry() {
-  const layout = layoutRoot.value?.getBoundingClientRect()
-  if (!layout) {
-    return {
-      width: sideSheetWidth.value,
-      insetTop: MODAL_INSET_TOP,
-      insetRight: MODAL_INSET_END,
-      insetBottom: MODAL_INSET_BOTTOM,
-    }
-  }
-
-  return {
-    width: sideSheetWidth.value,
-    insetTop: Math.round(layout.top),
-    insetRight: Math.round(window.innerWidth - layout.right),
-    insetBottom: Math.round(window.innerHeight - layout.bottom),
-  }
-}
-
-async function switchDockedToModal() {
-  syncFixedWidth()
-  setModalGeometryFromDocked()
-
-  modalTransitionMs.value = PANEL_TRANSITION_MS
-  modalRadiusLeft.value = 0
-  modalElevation.value = 0
-  modalRole.value = 'surface-container-low'
-  modalVisible.value = false
-  modalShown.value = true
-
-  await nextTick()
-  await raf()
-
-  modalVisible.value = true
-  await nextTick()
-  await raf()
-
-  sideSheetModal.value = true
-  sideSheetDockedWidth.value = 0
-  modalWidth.value = sideSheetWidth.value
-  modalInsetRight.value = MODAL_INSET_END
-  modalRadiusLeft.value = 28
-  modalElevation.value = 1
-  modalRole.value = 'surface-container-high'
-  await wait(PANEL_TRANSITION_MS)
-
-  await expandModalToViewportHeight()
-}
-
-async function switchModalToDocked() {
-  syncFixedWidth()
-  const dockedTarget = resolveDockedTargetGeometry()
-
-  modalTransitionMs.value = PANEL_TRANSITION_MS
-  modalElevation.value = 0
-  modalRole.value = 'surface-container-low'
-  modalRadiusLeft.value = 0
-
-  // Start returning flow slot first, then morph modal panel into that geometry.
-  sideSheetDockedWidth.value = sideSheetWidth.value
-  modalWidth.value = dockedTarget.width
-  modalInsetTop.value = dockedTarget.insetTop
-  modalInsetRight.value = dockedTarget.insetRight
-  modalInsetBottom.value = dockedTarget.insetBottom
-
-  await wait(PANEL_TRANSITION_MS)
-
-  // Swap to docked instance at the end position without extra hide animation.
-  sideSheetModal.value = false
-  modalVisible.value = false
-  modalShown.value = false
-
-  modalInsetTop.value = MODAL_INSET_TOP
-  modalInsetRight.value = hiddenInsetRight()
-  modalInsetBottom.value = MODAL_INSET_BOTTOM
-}
-
-async function toggleSideSheetMode() {
-  if (transitioning.value) {
-    return
-  }
-
-  transitioning.value = true
-
-  if (!sideSheetModal.value) {
-    await switchDockedToModal()
-    transitioning.value = false
-    return
-  }
-
-  await switchModalToDocked()
-  transitioning.value = false
-}
-
-async function closeModalFromPanel() {
-  if (!sideSheetModal.value || transitioning.value) {
-    return
-  }
-
-  transitioning.value = true
-  await switchModalToDocked()
-  transitioning.value = false
-}
-
-function onResize() {
-  syncFixedWidth()
-}
-
-onMounted(() => {
-  syncFixedWidth()
-  window.addEventListener('resize', onResize, { passive: true })
-})
-
-onBeforeUnmount(() => {
-  window.removeEventListener('resize', onResize)
-})
+const {
+  sideSheetModal,
+  sideSheetWidth,
+  modalShown,
+  dockedPanelShown,
+  transitioning,
+  dockedHost,
+  layoutRoot,
+  dockedHostStyle,
+  dockedPanelStyle,
+  modalPanelProps,
+  toggleSideSheetMode,
+  closeModalFromPanel,
+} = useSurfaceSideSheetMorph()
 </script>
 
 <style lang="scss" scoped>
@@ -596,16 +369,24 @@ onBeforeUnmount(() => {
 .surface-side-sheet__docked-host {
     flex: 0 0 auto;
     min-width: 0;
+    display: flex;
     overflow: hidden;
     border-left: 1px solid var(--surface-border);
     transition: width var(--surface-panel-transition-ms) var(--surface-panel-transition-easing);
 }
 
+.surface-side-sheet__sheet_docked {
+    flex: 1 1 auto;
+    min-width: 0;
+}
+
+.surface-side-sheet__sheet h3,
 :global(.surface-side-sheet__sheet h3) {
     margin: 0 0 8px;
     font: 700 17px/1.3 'Trebuchet MS', 'Segoe UI', sans-serif;
 }
 
+.surface-side-sheet__sheet,
 :global(.surface-side-sheet__sheet) {
     padding: 20px;
 }
@@ -625,11 +406,13 @@ onBeforeUnmount(() => {
     flex: 0 0 auto;
 }
 
+.surface-side-sheet__sheet p,
 :global(.surface-side-sheet__sheet p) {
     margin: 0 0 8px;
     font: 400 13px/1.4 'Trebuchet MS', 'Segoe UI', sans-serif;
 }
 
+.surface-side-sheet__sheet .surface-side-sheet__meta,
 :global(.surface-side-sheet__sheet .surface-side-sheet__meta) {
     margin-top: 14px;
     font: 600 11px/1.2 'Trebuchet MS', 'Segoe UI', sans-serif;
diff --git a/m3-vue/tests/M3Dialog.test.ts b/m3-vue/tests/M3Dialog.test.ts
index a101eed..a7ef5b7 100644
--- a/m3-vue/tests/M3Dialog.test.ts
+++ b/m3-vue/tests/M3Dialog.test.ts
@@ -9,6 +9,11 @@ import { nextTick } from 'vue'
 import { M3Dialog } from '@/components/dialog'
 
 describe('m3-vue/dialog', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+    document.body.innerHTML = ''
+  })
+
   test('opens by prop and emits close request on scrim click', async () => {
     const view = render(M3Dialog, {
       props: {
@@ -26,10 +31,140 @@ describe('m3-vue/dialog', () => {
 
     expect(screen.getByText('Dialog body')).not.toBeNull()
 
-    const scrim = document.body.querySelector('.m3-scrim') as HTMLElement
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
 
     await fireEvent.click(scrim)
 
     expect(view.emitted()['update:opened']?.[0]).toEqual([false])
   })
+
+  test('renders modal surface root instead of legacy container', async () => {
+    render(M3Dialog, {
+      props: {
+        opened: true,
+      },
+      slots: {
+        default: 'Dialog body',
+      },
+    })
+
+    await nextTick()
+
+    expect(document.body.querySelector('.m3-surface[role="dialog"]')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog-container')).toBeNull()
+  })
+
+  test('does not render scrim or legacy fullscreen class in fullscreen mode', async () => {
+    render(M3Dialog, {
+      props: {
+        opened: true,
+        fullscreen: true,
+      },
+      slots: {
+        default: 'Fullscreen body',
+      },
+    })
+
+    await nextTick()
+
+    expect(screen.getByText('Fullscreen body')).not.toBeNull()
+    expect(document.body.querySelector('.m3-surface__scrim')).toBeNull()
+    expect(document.body.querySelector('.m3-dialog_fullscreen')).toBeNull()
+  })
+
+  test('renders icon, header, footer and content wrappers', async () => {
+    render(M3Dialog, {
+      props: {
+        opened: true,
+      },
+      slots: {
+        icon: '<span data-testid="icon-node">ICON</span>',
+        header: '<h2 data-testid="header-node">Header</h2>',
+        footer: '<button data-testid="footer-node">Close</button>',
+        default: '<div data-testid="content-node">Dialog body</div>',
+      },
+    })
+
+    await nextTick()
+
+    expect(document.body.querySelector('.m3-dialog__icon')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__header')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__footer')).not.toBeNull()
+    expect(document.body.querySelector('.m3-dialog__content')).not.toBeNull()
+    expect(screen.getByTestId('icon-node')).not.toBeNull()
+    expect(screen.getByTestId('header-node')).not.toBeNull()
+    expect(screen.getByTestId('footer-node')).not.toBeNull()
+    expect(screen.getByTestId('content-node')).not.toBeNull()
+  })
+
+  test('forwards dialog attributes and keeps default modal role', async () => {
+    render(M3Dialog, {
+      props: {
+        opened: true,
+        'data-testid': 'dialog-root',
+        'aria-label': 'Settings dialog',
+      } as {
+        opened: boolean,
+        'data-testid': string,
+        'aria-label': string,
+      },
+      slots: {
+        default: 'Dialog body',
+      },
+    })
+
+    await nextTick()
+
+    const dialog = document.body.querySelector('.m3-surface[role="dialog"]') as HTMLElement | null
+
+    expect(screen.getByTestId('dialog-root')).not.toBeNull()
+    expect(dialog?.getAttribute('aria-label')).toBe('Settings dialog')
+    expect(dialog?.getAttribute('role')).toBe('dialog')
+  })
+
+  test('keeps dialog mounted during close animation before unmounting', async () => {
+    vi.useFakeTimers()
+
+    const view = render(M3Dialog, {
+      props: {
+        opened: true,
+      },
+      slots: {
+        default: 'Dialog body',
+      },
+    })
+
+    await nextTick()
+    expect(screen.getByText('Dialog body')).not.toBeNull()
+
+    await view.rerender({ opened: false })
+    await nextTick()
+
+    expect(screen.getByText('Dialog body')).not.toBeNull()
+
+    vi.advanceTimersByTime(300)
+    await nextTick()
+
+    expect(screen.queryByText('Dialog body')).toBeNull()
+  })
+
+  test('toggles scrim visibility when fullscreen changes', async () => {
+    const view = render(M3Dialog, {
+      props: {
+        opened: true,
+        fullscreen: false,
+      },
+      slots: {
+        default: 'Dialog body',
+      },
+    })
+
+    await nextTick()
+    expect(document.body.querySelector('.m3-surface__scrim')).not.toBeNull()
+
+    await view.rerender({ opened: true, fullscreen: true })
+    await nextTick()
+
+    expect(document.body.querySelector('.m3-surface__scrim')).toBeNull()
+  })
 })
diff --git a/m3-vue/tests/M3SideSheet.test.ts b/m3-vue/tests/M3SideSheet.test.ts
index 15dd1b4..003b8c6 100644
--- a/m3-vue/tests/M3SideSheet.test.ts
+++ b/m3-vue/tests/M3SideSheet.test.ts
@@ -40,6 +40,31 @@ describe('m3-vue/side-sheet', () => {
     expect(document.getElementById(labelId)?.textContent?.trim()).toBe('Panel title')
   })
 
+  test('keeps title in header and footer outside scroll content', async () => {
+    render(M3SideSheet, {
+      props: {
+        shown: true,
+      },
+      slots: {
+        title: 'Panel title',
+        default: 'Panel content',
+        footer: 'Footer actions',
+      },
+    })
+
+    await nextTick()
+
+    const title = screen.getByText('Panel title')
+    const content = screen.getByText('Panel content')
+    const footer = screen.getByText('Footer actions')
+
+    expect(title.closest('.m3-side-sheet__header')).not.toBeNull()
+    expect(title.closest('.m3-side-sheet__content')).toBeNull()
+    expect(content.closest('.m3-side-sheet__content')).not.toBeNull()
+    expect(footer.closest('.m3-side-sheet__footer')).not.toBeNull()
+    expect(footer.closest('.m3-side-sheet__content')).toBeNull()
+  })
+
   test('emits close request on scrim click when not docked', async () => {
     const view = render(M3SideSheet, {
       props: {
@@ -53,7 +78,7 @@ describe('m3-vue/side-sheet', () => {
 
     await nextTick()
 
-    const scrim = document.body.querySelector('.m3-scrim') as HTMLElement
+    const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
 
     await fireEvent.click(scrim)
 
diff --git a/m3-vue/tests/M3SurfacePanel.test.ts b/m3-vue/tests/M3SurfacePanel.test.ts
new file mode 100644
index 0000000..3fe3d1e
--- /dev/null
+++ b/m3-vue/tests/M3SurfacePanel.test.ts
@@ -0,0 +1,64 @@
+import {
+  render,
+  screen,
+} from '@testing-library/vue'
+
+import { M3SurfacePanel } from '@/components/surface'
+
+describe('m3-vue/surface-panel', () => {
+  test('renders deterministic static panel contract without implicit landmark role', () => {
+    render(M3SurfacePanel, {
+      slots: {
+        default: 'Surface body',
+      },
+    })
+
+    const surface = screen.getByText('Surface body').closest('.m3-surface') as HTMLElement
+
+    expect(surface).not.toBeNull()
+    expect(surface.getAttribute('role')).toBeNull()
+    expect(surface.style.width).toBe('100%')
+    expect(surface.style.height).toBe('100%')
+    expect(surface.style.borderTopLeftRadius).toBe('0px')
+    expect(surface.style.borderBottomLeftRadius).toBe('0px')
+  })
+
+  test('supports global and per-corner rounding overrides', () => {
+    render(M3SurfacePanel, {
+      props: {
+        rounding: 16,
+        roundingTopLeft: 4,
+        roundingBottomRight: '24px',
+      },
+    })
+
+    const surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.style.borderTopLeftRadius).toBe('4px')
+    expect(surface.style.borderTopRightRadius).toBe('16px')
+    expect(surface.style.borderBottomRightRadius).toBe('24px')
+    expect(surface.style.borderBottomLeftRadius).toBe('16px')
+  })
+
+  test('maps auto variant from elevation and allows explicit variant override', async () => {
+    const view = render(M3SurfacePanel, {
+      props: {
+        elevation: 3,
+      },
+    })
+
+    let surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
+
+    await view.rerender({
+      elevation: 3,
+      variant: 'surface-bright',
+    })
+
+    surface = document.querySelector('.m3-surface') as HTMLElement
+
+    expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+    expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
+  })
+})
diff --git a/m3-vue/tests/M3SurfaceStories.e2e.ts b/m3-vue/tests/M3SurfaceStories.e2e.ts
index c823bba..62418c2 100644
--- a/m3-vue/tests/M3SurfaceStories.e2e.ts
+++ b/m3-vue/tests/M3SurfaceStories.e2e.ts
@@ -149,7 +149,7 @@ describe('m3-vue/surface stories e2e', () => {
     mounted = mountStory(SurfaceSideSheetMorph)
 
     await waitFor(() => {
-      expect(document.querySelector('[data-testid="surface-morph-docked-sheet"]')).not.toBeNull()
+      expect(document.querySelector('[data-testid="surface-morph-sheet"][data-panel-mode="docked"]')).not.toBeNull()
     })
 
     const root = query<HTMLElement>('[data-testid="surface-morph-root"]')
@@ -164,7 +164,7 @@ describe('m3-vue/surface stories e2e', () => {
 
     await waitFor(() => {
       expect(root.getAttribute('data-sheet-modal')).toBe('true')
-      expect(document.querySelector('[data-testid="surface-morph-modal-sheet"]')).not.toBeNull()
+      expect(document.querySelector('[data-testid="surface-morph-sheet"][data-panel-mode="modal"]')).not.toBeNull()
       expect(document.querySelector('.m3-surface__scrim')).not.toBeNull()
     })
 
@@ -181,8 +181,8 @@ describe('m3-vue/surface stories e2e', () => {
 
     await waitFor(() => {
       expect(root.getAttribute('data-sheet-modal')).toBe('false')
-      expect(document.querySelector('[data-testid="surface-morph-docked-sheet"]')).not.toBeNull()
-      expect(document.querySelector('[data-testid="surface-morph-modal-sheet"]')).toBeNull()
+      expect(document.querySelector('[data-testid="surface-morph-sheet"][data-panel-mode="docked"]')).not.toBeNull()
+      expect(document.querySelector('[data-testid="surface-morph-sheet"][data-panel-mode="modal"]')).toBeNull()
     }, 2200)
 
     await delay(340)
@@ -227,7 +227,8 @@ describe('m3-vue/surface stories e2e', () => {
       expect(document.querySelector('[data-testid="surface-card-grid"]')).toBeNull()
     }, 2200)
 
-    const expandedRect = overlayWrap.getBoundingClientRect()
+    const expandedOverlayWrap = query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]')
+    const expandedRect = expandedOverlayWrap.getBoundingClientRect()
     const canvasRect = canvas.getBoundingClientRect()
     expect(expandedRect.width).toBeGreaterThan(canvasRect.width - 6)
     expect(expandedRect.height).toBeGreaterThan(canvasRect.height - 6)
@@ -254,7 +255,8 @@ describe('m3-vue/surface stories e2e', () => {
     }, 2200)
 
     const originAfter = query<HTMLElement>('[data-testid="surface-card-origin"]').getBoundingClientRect()
-    const collapsedRect = overlayWrap.getBoundingClientRect()
+    const collapsedOverlayWrap = query<HTMLElement>('[data-testid="surface-card-overlay-wrap"]')
+    const collapsedRect = collapsedOverlayWrap.getBoundingClientRect()
 
     expect(Math.abs(collapsedRect.width - originAfter.width)).toBeLessThan(12)
     expect(Math.abs(collapsedRect.height - originAfter.height)).toBeLessThan(12)
@@ -330,6 +332,10 @@ describe('m3-vue/surface stories e2e', () => {
 
       expect(amplitude).toBeGreaterThan(40)
       expect(rightDeltas.some(delta => delta > 0.2)).toBe(true)
+
+      await waitFor(() => {
+        expect(query<HTMLButtonElement>('[data-testid="surface-window-toggle-mode"]').disabled).toBe(false)
+      }, 1200)
     }
 
     await openAndSampleSheetEntry()

From bc831531dc88699d359d7457ac7c3fca10629e17 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 17:01:19 +0400
Subject: [PATCH 26/37] docs: Storybook surface docs were expanded

---
 m3-react/storybook/components/M3Dialog.mdx    | 80 ++++++++++++++++++
 m3-react/storybook/components/M3SideSheet.mdx | 84 +++++++++++++++++++
 m3-react/storybook/components/M3Surface.mdx   | 55 ++++++++++++
 m3-vue/storybook/components/M3Dialog.mdx      | 77 +++++++++++++++++
 m3-vue/storybook/components/M3SideSheet.mdx   | 62 +++++++++++---
 m3-vue/storybook/components/M3Surface.mdx     | 57 +++++++++++++
 6 files changed, 405 insertions(+), 10 deletions(-)
 create mode 100644 m3-react/storybook/components/M3SideSheet.mdx

diff --git a/m3-react/storybook/components/M3Dialog.mdx b/m3-react/storybook/components/M3Dialog.mdx
index ce7d43c..46aa65e 100644
--- a/m3-react/storybook/components/M3Dialog.mdx
+++ b/m3-react/storybook/components/M3Dialog.mdx
@@ -1,16 +1,42 @@
 import { Unstyled } from '@storybook/addon-docs/blocks'
+
 import DialogConfirmation from '../examples/dialog/DialogConfirmation'
 
 # Dialogs
 
 Dialogs communicate important information and block the underlying interface until the user responds.
 
+## API
+
+### When to use
+
+Use `M3Dialog` for short, interruptive decisions that need an explicit user choice before the page can continue. In Material 3 terms this maps best to confirmation, acknowledgement, and blocking task flows rather than to long-form editing or navigation.
+
+### Structure
+
+`M3Dialog` keeps the same content anatomy across React and Vue:
+
+- `M3Dialog.Icon` for a leading visual cue
+- `M3Dialog.Header` for the title area
+- default content for supporting text or compact form controls
+- `M3Dialog.Footer` for high-signal actions
+
+The component now renders on top of `M3Surface`, so dialog presentation and motion are aligned with the same modal surface vocabulary used by side sheets and orchestration stories.
+
+### Behavior in this implementation
+
+- Non-fullscreen dialogs open as centered modal surfaces with a scrim.
+- Fullscreen dialogs remove the scrim and expand to the viewport.
+- The surface enters with a short fade plus a slight upward settle, matching the modal choreography used in the nested-surface stories.
+- Dialog content stays mounted briefly during exit so the leave animation can finish before unmount.
+
 ## Accessibility semantics
 
 - Set `role="dialog"` (or `alertdialog` for urgent confirmations).
 - Provide `aria-modal="true"` for modal flows.
 - Connect title and description with `aria-labelledby` and `aria-describedby`.
 - Keep focus inside the dialog while it is opened.
+- Keep action labels explicit and outcome-oriented.
 
 <Unstyled>
   <div className="mb-3">
@@ -18,6 +44,60 @@ Dialogs communicate important information and block the underlying interface unt
   </div>
 </Unstyled>
 
+## Usage guidance
+
+### Content density
+
+Prefer one short title, one supporting message, and one clear primary action. If the flow starts needing dense forms, multiple scrolling regions, or navigation-like exploration, a side sheet or dedicated page usually communicates the state change more clearly.
+
+### Actions
+
+- Use the footer for the final decision point.
+- Keep destructive actions explicit in both label and placement.
+- Prefer a dismissive secondary action such as `Cancel` over relying on scrim click alone.
+
+### Fullscreen mode
+
+Use `fullscreen` only when the task needs the full viewport or when compact dialog proportions would constrain readability. This mode still keeps dialog semantics, but visually behaves closer to a temporary task surface than to a small confirmation window.
+
+## Code example
+
+```tsx
+const dialogTitleId = 'dialog-confirmation-title'
+const dialogDescriptionId = 'dialog-confirmation-description'
+
+<M3Dialog
+  opened={opened}
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby={dialogTitleId}
+  aria-describedby={dialogDescriptionId}
+  onToggle={setOpened}
+>
+  <M3Dialog.Icon>
+    <M3Icon name="delete" appearance="outlined" />
+  </M3Dialog.Icon>
+
+  <M3Dialog.Header>
+    <h3 id={dialogTitleId}>Permanently delete?</h3>
+  </M3Dialog.Header>
+
+  <p id={dialogDescriptionId}>
+    Deleting the selected messages will also remove them from all synced devices.
+  </p>
+
+  <M3Dialog.Footer>
+    <M3Button appearance="text" onClick={() => setOpened(false)}>
+      Cancel
+    </M3Button>
+
+    <M3Button appearance="tonal" onClick={() => setOpened(false)}>
+      Delete
+    </M3Button>
+  </M3Dialog.Footer>
+</M3Dialog>
+```
+
 ## Resources
 
 - [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
diff --git a/m3-react/storybook/components/M3SideSheet.mdx b/m3-react/storybook/components/M3SideSheet.mdx
new file mode 100644
index 0000000..00c14d2
--- /dev/null
+++ b/m3-react/storybook/components/M3SideSheet.mdx
@@ -0,0 +1,84 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import * as M3SideSheetStories from './M3SideSheet.stories'
+
+<Meta of={M3SideSheetStories} />
+
+# Side Sheets
+
+Side sheets extend `M3Surface` into a right-edge panel with dedicated header, scrollable content area, and optional footer actions.
+
+## API
+
+### When to use
+
+Use `M3SideSheet` when the user needs supplemental context, filters, or secondary editing controls while keeping the main task visible. Compared with dialogs, side sheets are better for medium-density supporting content that still belongs to the current page.
+
+### Modes in this implementation
+
+- Standard mode opens as a modal sheet over the page.
+- Docked mode keeps the sheet in layout as a persistent companion region.
+
+This follows the Material 3 distinction between temporary supporting surfaces and page-participating companion surfaces.
+
+### Content anatomy
+
+`M3SideSheet` gives you dedicated composition slots:
+
+- `M3SideSheet.Title`
+- `M3SideSheet.CloseIcon`
+- default body content
+- `M3SideSheet.Footer`
+
+The header and footer stay structurally distinct from the scrollable content region, so actions and dismiss affordances remain discoverable while the body changes.
+
+## Accessibility semantics
+
+- Use a clear title so the sheet can expose `aria-labelledby`.
+- Keep close affordances discoverable through the close button and, in modal mode, the scrim.
+- Reserve footer actions for final or high-signal decisions.
+- Treat modal side sheets as interruptive overlays and docked sheets as companion layout regions.
+
+## Stories
+
+- [Standard](?path=/story/components-m3sidesheet--standard)
+- [Docked](?path=/story/components-m3sidesheet--docked)
+
+## Usage guidance
+
+### Standard vs docked
+
+Choose `docked` when the page should continuously reserve space for the sheet and the surface is part of the working layout. Choose modal mode when the same content should feel temporary, dismissible, and layered above the page.
+
+### Footer usage
+
+Use the footer for apply, save, or clear actions that summarize the sheet's purpose. Avoid turning the footer into a second content area; supporting explanation belongs in the body.
+
+### Dismissal
+
+In modal mode, users should be able to close the sheet from the close icon and by leaving the sheet context. In docked mode, think of hide/show as a layout state change rather than as a modal dismissal.
+
+## Code example
+
+```tsx
+<M3SideSheet shown={shown} onToggle={setShown}>
+  <M3SideSheet.Title>
+    Filters
+  </M3SideSheet.Title>
+
+  <M3SideSheet.CloseIcon>
+    <M3Icon name="close" />
+  </M3SideSheet.CloseIcon>
+
+  <p className="m-4">Choose filters and apply changes.</p>
+
+  <M3SideSheet.Footer>
+    <div className="p-4">Footer actions</div>
+  </M3SideSheet.Footer>
+</M3SideSheet>
+```
+
+## Resources
+
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)
+- [M3 Side sheets guidelines](https://m3.material.io/components/side-sheets/guidelines)
+- [WAI-ARIA APG: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
index b4221ec..ec1e5ca 100644
--- a/m3-react/storybook/components/M3Surface.mdx
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -7,9 +7,64 @@ import * as M3SurfaceStories from './M3Surface.stories'
 
 Use `M3SurfacePanel` for static decorative surfaces such as cards, docs wrappers, and nested surface blocks. Reserve `M3Surface` for modal behavior and richer container orchestration.
 
+## API
+
+### Surface roles
+
+This workspace separates two responsibilities that are often mixed in product code:
+
+- `M3SurfacePanel` for local, in-flow containers
+- `M3Surface` for modal positioning, scrim management, anchoring, and richer surface choreography
+
+This mirrors Material 3 guidance, where the same visual surface language is reused across cards, dialogs, side sheets, and other temporary containers, but the interaction model changes by context.
+
+### Variant and elevation model
+
+Use `variant` when the surface role is explicit. Use `auto` only when you intentionally want elevation to resolve the surface tone automatically. The orchestration stories in this package mostly choose explicit variants, because transitions between states should keep semantics stable while only geometry and modality change.
+
+### Modal behavior
+
+`M3Surface` handles:
+
+- modal teleporting
+- scrim fade
+- anchor positioning
+- rounded-corner transitions
+- size and inset transitions for morph scenarios
+
+The component does not prescribe content anatomy. Dialogs, side sheets, and custom orchestrated surfaces build that structure on top.
+
+## Story guide
+
 - [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
+  Shows how a docked layout participant becomes a modal overlay and returns to the reserved host without snapping.
 - [Card Replacing Page](?path=/story/components-m3surface--card-replacing-page)
+  Demonstrates a compact card expanding into a page-like work area while preserving reserved layout zones.
 - [Side Sheet Modal Dismiss Removes Surface](?path=/story/components-m3surface--side-sheet-modal-dismiss-removes-surface)
+  Covers the branch where modal dismissal removes the feature surface instead of restoring a docked state.
 - [Side Sheet Always Modal Toggle](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
+  Keeps the same surface always modal and focuses only on repeated entry and dismissal.
 - [Side Sheet Modal To Window](?path=/story/components-m3surface--side-sheet-modal-to-window)
+  Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
+  Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+
+## Usage guidance
+
+### Prefer the narrowest abstraction
+
+Reach for `M3SurfacePanel` when the surface only needs tone, radius, elevation, and local sizing. Move to `M3Surface` only when the container becomes modal, anchored, or transition-driven.
+
+### Keep state names explicit
+
+The orchestration examples work best when you model stable states such as `docked`, `modal-sheet`, or `window`, and then derive geometry and motion from those states rather than from ad hoc booleans.
+
+### Match motion to target geometry
+
+When morphing between surfaces, animate toward a measured target rectangle or target inset set. This prevents the “overlay shrinks somewhere else, then snaps” failure mode that surface transitions are especially sensitive to.
+
+## Resources
+
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)
diff --git a/m3-vue/storybook/components/M3Dialog.mdx b/m3-vue/storybook/components/M3Dialog.mdx
index 26731a0..8601237 100644
--- a/m3-vue/storybook/components/M3Dialog.mdx
+++ b/m3-vue/storybook/components/M3Dialog.mdx
@@ -7,12 +7,37 @@ import DialogConfirmation from '../examples/dialog/DialogConfirmation.vue'
 
 Dialogs communicate important information and block the underlying interface until the user responds.
 
+## API
+
+### When to use
+
+Use `M3Dialog` for short, interruptive decisions that need an explicit user choice before the page can continue. In Material 3 terms this maps best to confirmation, acknowledgement, and blocking task flows rather than to long-form editing or navigation.
+
+### Structure
+
+`M3Dialog` keeps the same content anatomy across React and Vue:
+
+- `icon` slot for a leading visual cue
+- `header` slot for the title area
+- default slot for supporting text or compact form controls
+- `footer` slot for high-signal actions
+
+The component now renders on top of `M3Surface`, so dialog presentation and motion are aligned with the same modal surface vocabulary used by side sheets and orchestration stories.
+
+### Behavior in this implementation
+
+- Non-fullscreen dialogs open as centered modal surfaces with a scrim.
+- Fullscreen dialogs remove the scrim and expand to the viewport.
+- The surface enters with a short fade plus a slight upward settle, matching the modal choreography used in the nested-surface stories.
+- Dialog content stays mounted briefly during exit so the leave animation can finish before unmount.
+
 ## Accessibility semantics
 
 - Set `role="dialog"` (or `alertdialog` for urgent confirmations).
 - Provide `aria-modal="true"` for modal flows.
 - Connect title and description with `aria-labelledby` and `aria-describedby`.
 - Keep focus inside the dialog while it is opened.
+- Keep action labels explicit and outcome-oriented.
 
 <Unstyled>
   <div className="mb-3">
@@ -20,6 +45,58 @@ Dialogs communicate important information and block the underlying interface unt
   </div>
 </Unstyled>
 
+## Usage guidance
+
+### Content density
+
+Prefer one short title, one supporting message, and one clear primary action. If the flow starts needing dense forms, multiple scrolling regions, or navigation-like exploration, a side sheet or dedicated page usually communicates the state change more clearly.
+
+### Actions
+
+- Use the footer for the final decision point.
+- Keep destructive actions explicit in both label and placement.
+- Prefer a dismissive secondary action such as `Cancel` over relying on scrim click alone.
+
+### Fullscreen mode
+
+Use `fullscreen` only when the task needs the full viewport or when compact dialog proportions would constrain readability. This mode still keeps dialog semantics, but visually behaves closer to a temporary task surface than to a small confirmation window.
+
+## Code example
+
+```html
+<M3Dialog
+  v-model:opened="opened"
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-confirmation-title"
+  aria-describedby="dialog-confirmation-description"
+>
+  <template #icon>
+    <M3Icon name="delete" appearance="outlined" />
+  </template>
+
+  <template #header>
+    <h3 id="dialog-confirmation-title">
+      Permanently delete?
+    </h3>
+  </template>
+
+  <p id="dialog-confirmation-description">
+    Deleting the selected messages will also remove them from all synced devices.
+  </p>
+
+  <template #footer>
+    <M3Button appearance="text" @click="opened = false">
+      Cancel
+    </M3Button>
+
+    <M3Button appearance="tonal" @click="opened = false">
+      Delete
+    </M3Button>
+  </template>
+</M3Dialog>
+```
+
 ## Resources
 
 - [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
diff --git a/m3-vue/storybook/components/M3SideSheet.mdx b/m3-vue/storybook/components/M3SideSheet.mdx
index 1e33892..101dff7 100644
--- a/m3-vue/storybook/components/M3SideSheet.mdx
+++ b/m3-vue/storybook/components/M3SideSheet.mdx
@@ -7,36 +7,78 @@ import * as M3SideSheetStories from './M3SideSheet.stories'
 
 Side sheets extend `M3Surface` into a right-edge panel with dedicated header, scrollable content area, and optional footer actions.
 
+## API
+
+### When to use
+
+Use `M3SideSheet` when the user needs supplemental context, filters, or secondary editing controls while keeping the main task visible. Compared with dialogs, side sheets are better for medium-density supporting content that still belongs to the current page.
+
+### Modes in this implementation
+
+- Standard mode opens as a modal sheet over the page.
+- Docked mode keeps the sheet in layout as a persistent companion region.
+
+This follows the Material 3 distinction between temporary supporting surfaces and page-participating companion surfaces.
+
+### Content anatomy
+
+`M3SideSheet` gives you dedicated slots for:
+
+- `title`
+- `close-icon`
+- default body content
+- `footer`
+
+The header and footer stay structurally distinct from the scrollable content region, so actions and dismiss affordances remain discoverable while the body changes.
+
 ## Accessibility semantics
 
 - Use a clear title so the sheet can expose `aria-labelledby`.
 - Keep close affordances discoverable through the close button and, in modal mode, the scrim.
 - Reserve footer actions for final or high-signal decisions.
+- Treat modal side sheets as interruptive overlays and docked sheets as companion layout regions.
 
 ## Stories
 
 - [Standard](?path=/story/components-m3sidesheet--standard)
 - [Docked](?path=/story/components-m3sidesheet--docked)
 
+## Usage guidance
+
+### Standard vs docked
+
+Choose `docked` when the page should continuously reserve space for the sheet and the surface is part of the working layout. Choose modal mode when the same content should feel temporary, dismissible, and layered above the page.
+
+### Footer usage
+
+Use the footer for apply, save, or clear actions that summarize the sheet's purpose. Avoid turning the footer into a second content area; supporting explanation belongs in the body.
+
+### Dismissal
+
+In modal mode, users should be able to close the sheet from the close icon and by leaving the sheet context. In docked mode, think of hide/show as a layout state change rather than as a modal dismissal.
+
 ## Code example
 
 ```html
 <M3SideSheet :shown="opened" @update:shown="opened = $event">
-    <template #title>Filters</template>
-    <template #close-icon>
-        <M3Icon name="close" />
-    </template>
+  <template #title>
+    Filters
+  </template>
+
+  <template #close-icon>
+    <M3Icon name="close" />
+  </template>
 
-    <p class="m-4">Choose filters and apply changes.</p>
+  <p class="m-4">Choose filters and apply changes.</p>
 
-    <template #footer>
-        <div class="p-4">Footer actions</div>
-    </template>
+  <template #footer>
+    <div class="p-4">Footer actions</div>
+  </template>
 </M3SideSheet>
 ```
 
 ## Resources
 
-- [M3 Side sheets overview](https://m3.material.io/components/navigation-drawer/overview)
-- [M3 Side sheets guidelines](https://m3.material.io/components/navigation-drawer/guidelines)
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)
+- [M3 Side sheets guidelines](https://m3.material.io/components/side-sheets/guidelines)
 - [WAI-ARIA APG: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
diff --git a/m3-vue/storybook/components/M3Surface.mdx b/m3-vue/storybook/components/M3Surface.mdx
index 5650ce0..ec1e5ca 100644
--- a/m3-vue/storybook/components/M3Surface.mdx
+++ b/m3-vue/storybook/components/M3Surface.mdx
@@ -5,9 +5,66 @@ import * as M3SurfaceStories from './M3Surface.stories'
 
 # Surfaces
 
+Use `M3SurfacePanel` for static decorative surfaces such as cards, docs wrappers, and nested surface blocks. Reserve `M3Surface` for modal behavior and richer container orchestration.
+
+## API
+
+### Surface roles
+
+This workspace separates two responsibilities that are often mixed in product code:
+
+- `M3SurfacePanel` for local, in-flow containers
+- `M3Surface` for modal positioning, scrim management, anchoring, and richer surface choreography
+
+This mirrors Material 3 guidance, where the same visual surface language is reused across cards, dialogs, side sheets, and other temporary containers, but the interaction model changes by context.
+
+### Variant and elevation model
+
+Use `variant` when the surface role is explicit. Use `auto` only when you intentionally want elevation to resolve the surface tone automatically. The orchestration stories in this package mostly choose explicit variants, because transitions between states should keep semantics stable while only geometry and modality change.
+
+### Modal behavior
+
+`M3Surface` handles:
+
+- modal teleporting
+- scrim fade
+- anchor positioning
+- rounded-corner transitions
+- size and inset transitions for morph scenarios
+
+The component does not prescribe content anatomy. Dialogs, side sheets, and custom orchestrated surfaces build that structure on top.
+
+## Story guide
+
 - [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
+  Shows how a docked layout participant becomes a modal overlay and returns to the reserved host without snapping.
 - [Card Replacing Page](?path=/story/components-m3surface--card-replacing-page)
+  Demonstrates a compact card expanding into a page-like work area while preserving reserved layout zones.
 - [Side Sheet Modal Dismiss Removes Surface](?path=/story/components-m3surface--side-sheet-modal-dismiss-removes-surface)
+  Covers the branch where modal dismissal removes the feature surface instead of restoring a docked state.
 - [Side Sheet Always Modal Toggle](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
+  Keeps the same surface always modal and focuses only on repeated entry and dismissal.
 - [Side Sheet Modal To Window](?path=/story/components-m3surface--side-sheet-modal-to-window)
+  Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
+  Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+
+## Usage guidance
+
+### Prefer the narrowest abstraction
+
+Reach for `M3SurfacePanel` when the surface only needs tone, radius, elevation, and local sizing. Move to `M3Surface` only when the container becomes modal, anchored, or transition-driven.
+
+### Keep state names explicit
+
+The orchestration examples work best when you model stable states such as `docked`, `modal-sheet`, or `window`, and then derive geometry and motion from those states rather than from ad hoc booleans.
+
+### Match motion to target geometry
+
+When morphing between surfaces, animate toward a measured target rectangle or target inset set. This prevents the “overlay shrinks somewhere else, then snaps” failure mode that surface transitions are especially sensitive to.
+
+## Resources
+
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Dialogs overview](https://m3.material.io/components/dialogs/overview)
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)

From 9b653f2c8300a80c6f98a93cfc37927efaf064a9 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 18:11:09 +0400
Subject: [PATCH 27/37] docs: Storybook component docs were expanded

---
 m3-react/storybook/components/M3Button.mdx    | 39 ++++++++++++-
 m3-react/storybook/components/M3Card.mdx      | 53 ++++++++++++++++-
 m3-react/storybook/components/M3Checkbox.mdx  | 35 ++++++++++-
 m3-react/storybook/components/M3FabButton.mdx | 43 +++++++++++++-
 .../storybook/components/M3IconButton.mdx     | 48 ++++++++++++++-
 m3-react/storybook/components/M3Link.mdx      | 56 ++++++++++++++++++
 m3-react/storybook/components/M3Menu.mdx      | 52 +++++++++++++++++
 .../storybook/components/M3Navigation.mdx     | 33 ++++++++++-
 .../storybook/components/M3RichTooltip.mdx    | 30 +++++++++-
 .../storybook/components/M3ScrollRail.mdx     | 52 +++++++++++++++++
 m3-react/storybook/components/M3Select.mdx    | 52 ++++++++++++++++-
 m3-react/storybook/components/M3Slider.mdx    | 34 ++++++++++-
 m3-react/storybook/components/M3Switch.mdx    | 49 ++++++++++------
 m3-react/storybook/components/M3TextField.mdx | 56 ++++++++++++++++--
 m3-vue/storybook/components/M3Button.mdx      | 37 +++++++++++-
 m3-vue/storybook/components/M3Card.mdx        | 58 ++++++++++++++++++-
 m3-vue/storybook/components/M3Checkbox.mdx    | 35 ++++++++++-
 m3-vue/storybook/components/M3FabButton.mdx   | 43 +++++++++++++-
 m3-vue/storybook/components/M3IconButton.mdx  | 50 ++++++++++++++--
 m3-vue/storybook/components/M3Navigation.mdx  | 33 ++++++++++-
 m3-vue/storybook/components/M3RichTooltip.mdx | 30 +++++++++-
 m3-vue/storybook/components/M3ScrollRail.mdx  | 52 +++++++++++++++++
 m3-vue/storybook/components/M3Select.mdx      | 51 +++++++++++++++-
 m3-vue/storybook/components/M3Slider.mdx      | 34 ++++++++++-
 m3-vue/storybook/components/M3Switch.mdx      | 47 +++++++++------
 m3-vue/storybook/components/M3TextField.mdx   | 51 ++++++++++++++--
 26 files changed, 1068 insertions(+), 85 deletions(-)
 create mode 100644 m3-react/storybook/components/M3Link.mdx
 create mode 100644 m3-react/storybook/components/M3Menu.mdx
 create mode 100644 m3-react/storybook/components/M3ScrollRail.mdx
 create mode 100644 m3-vue/storybook/components/M3ScrollRail.mdx

diff --git a/m3-react/storybook/components/M3Button.mdx b/m3-react/storybook/components/M3Button.mdx
index 5374a45..7685673 100644
--- a/m3-react/storybook/components/M3Button.mdx
+++ b/m3-react/storybook/components/M3Button.mdx
@@ -8,7 +8,25 @@ import * as M3ButtonStories from './M3Button.stories'
 
 # Buttons
 
-Common buttons prompt most actions in a UI
+Buttons communicate available actions and establish hierarchy on a surface. Material 3 distinguishes buttons primarily by emphasis, not by feature set.
+
+## API
+
+### When to use
+
+Use `M3Button` for explicit actions such as save, submit, share, or continue. Prefer buttons over links when the result changes UI state or triggers an in-app operation.
+
+### Appearances
+
+- `filled` for the primary action in a region
+- `elevated` when the action should stand out on low-emphasis surfaces
+- `tonal` for prominent but secondary emphasis
+- `outlined` for lower-emphasis alternatives
+- `text` for lightweight supporting actions
+
+### Icons and labels
+
+Leading icons help scanning when the metaphor is widely understood. Keep the text label explicit even when an icon is present, so the action remains readable without relying on symbol recognition alone.
 
 ## Accessibility semantics
 
@@ -34,12 +52,27 @@ Common buttons prompt most actions in a UI
   </p>
 </Unstyled>
 
+## Story guide
+
+- [With Text Only](?path=/story/components-m3button--with-text-only)
+- [With Leading Icon](?path=/story/components-m3button--with-leading-icon)
+
+## Usage guidance
+
+### Keep hierarchy local
+
+Each region should usually have one highest-emphasis action. If everything is filled, users lose the sense of priority that Material 3 buttons are designed to communicate.
+
+### Disable carefully
+
+Use `disabled` only when the action is genuinely unavailable. If the action is available but risky, keep it enabled and explain the consequence instead of hiding the path forward.
+
 ## Code example
 
 ```tsx
 export const EditButton = () => (
-  <M3Button appearance={'tonal'}>
-    <M3Icon name={'edit'} /> Edit
+  <M3Button appearance="tonal">
+    <M3Icon name="edit" /> Edit
   </M3Button>
 )
 ```
diff --git a/m3-react/storybook/components/M3Card.mdx b/m3-react/storybook/components/M3Card.mdx
index eefef04..da3c4fb 100644
--- a/m3-react/storybook/components/M3Card.mdx
+++ b/m3-react/storybook/components/M3Card.mdx
@@ -8,7 +8,26 @@ import * as M3CardStories from './M3Card.stories'
 
 # Cards
 
-Cards display content and actions about a single subject
+Cards group related content and actions into a single container. In Material 3 they work best when they stay focused on one subject, one decision, or one compact summary.
+
+## API
+
+### When to use
+
+Use `M3Card` when content should feel grouped but still remain embedded in the page flow. If the interaction becomes blocking or needs a scrim, move to `M3Dialog` or `M3Surface`.
+
+### Anatomy
+
+Typical card structure in this workspace includes:
+
+- media or leading visual
+- heading and optional subheading
+- supporting content
+- optional trailing or footer actions
+
+### Appearances
+
+Material 3 cards rely on tone and outline treatment to signal emphasis. This implementation exposes `filled`, `elevated`, and `outlined`, which cover the main hierarchy levels from the official card guidance.
 
 ## Accessibility semantics
 
@@ -21,9 +40,39 @@ Cards display content and actions about a single subject
   <LiveMusic2 interactive={true} />
 </Unstyled>
 
+## Story guide
+
+- [Landscape](?path=/story/components-m3card--landscape)
+- [Landscape Without Media](?path=/story/components-m3card--landscape-without-media)
+- [Portrait](?path=/story/components-m3card--portrait)
+
+## Usage guidance
+
+### Keep cards focused
+
+Avoid turning a card into a mini page. Once it needs long forms, deep navigation, or persistent editing controls, a larger surface usually communicates the task more clearly.
+
+### Separate container click from inner actions
+
+If the whole card is interactive, nested actions should remain semantically distinct and visually predictable. Competing click targets inside one card quickly become ambiguous.
+
+## Code example
+
+```tsx
+<M3Card appearance="filled">
+  <M3Card.Media>
+    <img alt="" src="/assets/image-720x376.png" />
+  </M3Card.Media>
+
+  <M3Card.Heading>Title</M3Card.Heading>
+  <M3Card.Subheading>Subhead</M3Card.Subheading>
+
+  Supporting text
+</M3Card>
+```
+
 ## Resources
 
 - [M3 Cards overview](https://m3.material.io/components/cards/overview)
 - [M3 Cards guidelines](https://m3.material.io/components/cards/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Checkbox.mdx b/m3-react/storybook/components/M3Checkbox.mdx
index 3746709..221e093 100644
--- a/m3-react/storybook/components/M3Checkbox.mdx
+++ b/m3-react/storybook/components/M3Checkbox.mdx
@@ -7,7 +7,25 @@ import * as M3CheckboxStories from './M3Checkbox.stories'
 
 # Checkboxes
 
-Checkboxes let users select one or more items from a list, or turn an item on or off
+Checkboxes let users select one or more options independently. They also support parent-child selection patterns where a parent reflects the aggregate state of subordinate items.
+
+## API
+
+### When to use
+
+Use `M3Checkbox` when multiple items can be selected at the same time, or when a single option behaves like a boolean choice inside a form. If the user must pick exactly one option, prefer radios instead.
+
+### Selection model
+
+This implementation supports both simple boolean selection and array-backed multi-select models. It also supports `indeterminate` for aggregate parent rows, which matches the Material 3 guidance for nested selection patterns.
+
+### Nested selection
+
+In nested lists, the parent checkbox should summarize descendant state:
+
+- checked when all descendants are selected
+- indeterminate when some descendants are selected
+- unchecked when none are selected
 
 ## Accessibility semantics
 
@@ -53,9 +71,22 @@ Checkboxes let users select one or more items from a list, or turn an item on or
   />
 </Unstyled>
 
+## Story guide
+
+- [Standard](?path=/story/components-m3checkbox--standard)
+
+## Usage guidance
+
+### Keep labels explicit
+
+Checkbox labels should describe the resulting state, not the control itself. "Email receipts" is clearer than "Enable."
+
+### Use indeterminate only as summary state
+
+Do not present `indeterminate` as a user-selectable third state. It should only communicate partial selection across descendants.
+
 ## Resources
 
 - [M3 Checkbox overview](https://m3.material.io/components/checkbox/overview)
 - [M3 Checkbox guidelines](https://m3.material.io/components/checkbox/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
diff --git a/m3-react/storybook/components/M3FabButton.mdx b/m3-react/storybook/components/M3FabButton.mdx
index 8862943..720d5a2 100644
--- a/m3-react/storybook/components/M3FabButton.mdx
+++ b/m3-react/storybook/components/M3FabButton.mdx
@@ -8,7 +8,24 @@ import * as M3FabButtonStories from './M3FabButton.stories'
 
 # Floating action buttons
 
-Floating action buttons (FABs) help people take primary actions
+Floating action buttons emphasize the highest-priority action on a surface. Material 3 treats FABs as strong directional cues, so they work best when the page has one clear "next thing to do."
+
+## API
+
+### When to use
+
+Use `M3FabButton` for the primary action of a screen or large section, especially when that action should remain easy to reach while content scrolls.
+
+### Standard vs extended
+
+- standard FAB for compact icon-first actions
+- extended FAB when the action benefits from a visible label
+
+The extended form is usually easier to scan when the action is not universally obvious from the icon alone.
+
+### Variants
+
+This implementation exposes Material 3 tonal variants such as `surface`, `primary`, `secondary`, and `tertiary`, which let the FAB stay prominent without always defaulting to the same tone.
 
 ## Accessibility semantics
 
@@ -38,11 +55,33 @@ Floating action buttons (FABs) help people take primary actions
   </p>
 </Unstyled>
 
+## Story guide
+
+- [Standard](?path=/story/components-m3fabbutton--standard)
+- [Extended](?path=/story/components-m3fabbutton--extended)
+
+## Usage guidance
+
+### One FAB per context
+
+Most surfaces should have at most one FAB. Multiple competing FABs dilute the main-action pattern that Material 3 is trying to reinforce.
+
+### Prefer extended when the icon is ambiguous
+
+If users need to stop and decode the icon, show the label. The slight increase in width is usually worth the clarity.
+
+## Code example
+
+```tsx
+<M3FabButton>
+  <M3Icon name="add" /> New task
+</M3FabButton>
+```
+
 ## Resources
 
 - [M3 FAB overview](https://m3.material.io/components/floating-action-button/overview)
 - [M3 FAB guidelines](https://m3.material.io/components/floating-action-button/guidelines)
 - [M3 Extended FAB overview](https://m3.material.io/components/extended-fab/overview)
 - [M3 Extended FAB guidelines](https://m3.material.io/components/extended-fab/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3IconButton.mdx b/m3-react/storybook/components/M3IconButton.mdx
index 824d5ba..0ff8677 100644
--- a/m3-react/storybook/components/M3IconButton.mdx
+++ b/m3-react/storybook/components/M3IconButton.mdx
@@ -6,9 +6,23 @@ import * as M3IconButtonStories from './M3IconButton.stories'
 
 <Meta of={M3IconButtonStories} />
 
-# M3IconButton
+# Icon buttons
 
-Icon buttons help people take minor actions with one tap
+Icon buttons surface compact, frequent actions without introducing the visual weight of a full text button. They work best for toolbar actions, trailing row actions, and repeated local controls.
+
+## API
+
+### When to use
+
+Use `M3IconButton` for secondary or utility actions where the icon metaphor is well established. If the action is high-stakes or not obvious from the icon alone, a text button is usually clearer.
+
+### Appearances
+
+Material 3 distinguishes icon buttons by fill and emphasis. This implementation covers `standard`, `filled`, `tonal`, and `outlined`, which map well to common local-action hierarchies.
+
+### Toggleable state
+
+When `toggleable` is enabled, the button should represent an on/off state such as favorite, pin, mute, or bookmark. In that mode, use selection styling together with `aria-pressed`.
 
 ## Accessibility semantics
 
@@ -31,9 +45,37 @@ Icon buttons help people take minor actions with one tap
   </p>
 </Unstyled>
 
+## Story guide
+
+- [Standard](?path=/story/components-m3iconbutton--standard)
+- [Toggleable](?path=/story/components-m3iconbutton--toggleable)
+
+## Usage guidance
+
+### Keep hit targets generous
+
+Even when the visual icon is small, the interactive target should remain comfortable for pointer and touch use. Material 3 icon buttons depend on this spacing to feel intentional rather than fiddly.
+
+### Use toggles only for persistent state
+
+If the action simply opens a menu or triggers a one-off command, do not model it as selected. Reserve toggle state for something the user can inspect later.
+
+## Code example
+
+```tsx
+<M3IconButton
+  appearance="tonal"
+  toggleable={true}
+  selected={selected}
+  aria-label="Toggle favorite"
+  aria-pressed={selected}
+>
+  <M3Icon name="favorite" />
+</M3IconButton>
+```
+
 ## Resources
 
 - [M3 Icon Buttons overview](https://m3.material.io/components/icon-buttons/overview)
 - [M3 Icon Buttons guidelines](https://m3.material.io/components/icon-buttons/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Link.mdx b/m3-react/storybook/components/M3Link.mdx
new file mode 100644
index 0000000..cce45da
--- /dev/null
+++ b/m3-react/storybook/components/M3Link.mdx
@@ -0,0 +1,56 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3LinkStories from './M3Link.stories'
+
+<Meta of={M3LinkStories} />
+
+# Link
+
+`M3Link` is a semantic primitive that renders either a button-like control or an anchor, depending on whether navigation is involved. In this workspace it is intentionally low-level and acts as a base for richer controls.
+
+## API
+
+### When to use
+
+Use `M3Link` when you need a semantic clickable primitive that may resolve to `<button>` or `<a>` without rewriting the surrounding presentation logic. It is especially useful for custom controls that share styling but differ in navigation semantics.
+
+### Primitive role
+
+Material 3 does not define a dedicated standalone "link primitive" page. Instead, links appear inside buttons, cards, navigation items, and other patterns. This component fills that implementation-level gap while still following Material 3 guidance for the patterns built on top of it.
+
+### Rendering model
+
+- renders as `<button>` when the action is in-app and no `href` is provided
+- renders as `<a>` when navigation is the intended behavior
+
+## Accessibility semantics
+
+- Use button semantics for state-changing actions.
+- Use anchor semantics for navigation to another resource or location.
+- Keep visible labels descriptive enough to make sense out of context.
+
+## Story guide
+
+- [Primitive Shape](?path=/story/components-m3link--primitive-shape)
+- [As Base For Custom Controls](?path=/story/components-m3link--as-base-for-custom-controls)
+
+## Demo
+
+<Canvas of={M3LinkStories.PrimitiveShape} />
+<Canvas of={M3LinkStories.AsBaseForCustomControls} />
+
+## Usage guidance
+
+### Choose semantics first
+
+Do not decide between anchor and button based only on visual appearance. Choose based on whether the result is navigation or an action.
+
+### Build presentation on top
+
+Because `M3Link` is intentionally primitive, treat it as a foundation for custom controls rather than as a full visual component by itself.
+
+## Resources
+
+- [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
+- [MDN: Links vs. buttons](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Links_and_navigation)
diff --git a/m3-react/storybook/components/M3Menu.mdx b/m3-react/storybook/components/M3Menu.mdx
new file mode 100644
index 0000000..da2581b
--- /dev/null
+++ b/m3-react/storybook/components/M3Menu.mdx
@@ -0,0 +1,52 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3MenuStories from './M3Menu.stories'
+
+<Meta of={M3MenuStories} />
+
+# Menus
+
+Menus present a short list of actions or choices anchored to a trigger. Material 3 menus are lightweight, contextual, and best for options that belong to the current place in the interface.
+
+## API
+
+### When to use
+
+Use `M3Menu` for contextual actions, quick choices, and anchored command lists. If the content becomes long, descriptive, or form-like, prefer a side sheet or dialog.
+
+### Anchoring
+
+Menus should open from a clearly related trigger and preserve that relationship visually. The current implementation uses an explicit `target` element to keep positioning tied to the invoking control.
+
+### Selection
+
+Selected rows can communicate the current choice inside the menu, but the menu itself should still remain compact and easy to scan.
+
+## Accessibility semantics
+
+- Connect the trigger and popup with menu-button semantics.
+- Keep item labels concise and action-oriented.
+- Return focus to the trigger when the menu closes.
+
+## Story guide
+
+- [Standard](?path=/story/components-m3menu--standard)
+
+## Demo
+
+<Canvas of={M3MenuStories.Standard} />
+
+## Usage guidance
+
+### Keep menus short
+
+If users need to scroll, compare dense descriptions, or understand complex consequences, the control has probably outgrown the menu pattern.
+
+### Prefer clear verbs
+
+Menu items work best when each row starts with a distinct action or state label. Repetitive prefixes make scanning slower.
+
+## Resources
+
+- [M3 Menus overview](https://m3.material.io/components/menus/overview)
+- [M3 Menus guidelines](https://m3.material.io/components/menus/guidelines)
+- [WAI-ARIA APG: Menu Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
diff --git a/m3-react/storybook/components/M3Navigation.mdx b/m3-react/storybook/components/M3Navigation.mdx
index d6f4660..b1676f4 100644
--- a/m3-react/storybook/components/M3Navigation.mdx
+++ b/m3-react/storybook/components/M3Navigation.mdx
@@ -5,7 +5,21 @@ import * as M3NavigationStories from './M3Navigation.stories'
 
 # Navigation
 
-Navigation components help users move between top-level destinations.
+Navigation components help users move between top-level destinations. Material 3 splits navigation patterns by available space and permanence, not only by visual style.
+
+## API
+
+### When to use
+
+Use `M3Navigation` for app-level destinations that users may revisit repeatedly during the session. Keep these destinations stable and semantically distinct from local page tabs or in-content filters.
+
+### Navigation forms
+
+- navigation drawer for broad destination sets and more descriptive labels
+- navigation rail for medium and large layouts where a vertical persistent control fits the shell
+- navigation bar for compact layouts and a small number of top-level destinations
+
+The current stories focus on drawer and rail, which are the forms implemented in this workspace today.
 
 ## Accessibility semantics
 
@@ -13,11 +27,24 @@ Navigation components help users move between top-level destinations.
 - Keep destination labels concise and unique.
 - Expose active destination state consistently in routed integrations.
 
+## Story guide
+
+- [Navigation Drawer](?path=/story/components-m3navigation--navigation-drawer)
+- [Navigation Rail](?path=/story/components-m3navigation--navigation-rail)
+
+## Usage guidance
+
+### Keep destination sets small and stable
+
+Top-level navigation should not behave like a task-specific filter group. If items appear and disappear unpredictably, users lose the mental map that navigation is supposed to provide.
+
+### Match pattern to layout
+
+Use drawer or rail based on screen width, information density, and shell persistence. Do not switch patterns arbitrarily if the content model itself has not changed.
+
 ## Resources
 
 - [M3 Navigation bar overview](https://m3.material.io/components/navigation-bar/overview)
 - [M3 Navigation rail overview](https://m3.material.io/components/navigation-rail/overview)
 - [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
-- [Storybook: NavigationDrawer](?path=/story/components-m3navigation--navigation-drawer)
-- [Storybook: NavigationRail](?path=/story/components-m3navigation--navigation-rail)
 - [WAI-ARIA APG: Landmark Regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)
diff --git a/m3-react/storybook/components/M3RichTooltip.mdx b/m3-react/storybook/components/M3RichTooltip.mdx
index 8ff5b73..2726e54 100644
--- a/m3-react/storybook/components/M3RichTooltip.mdx
+++ b/m3-react/storybook/components/M3RichTooltip.mdx
@@ -4,7 +4,25 @@ import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip'
 
 # Rich tooltip
 
-Rich tooltips provide contextual, supplementary information near a trigger element.
+Rich tooltips provide contextual, supplementary information near a trigger element. Compared with plain tooltips, they support a slightly denser content payload while still staying lightweight and non-blocking.
+
+## API
+
+### When to use
+
+Use a rich tooltip for brief supporting information, shortcuts, or action consequences that help the user decide without forcing them into a dialog. If the content becomes critical or requires interaction-heavy confirmation, move to a larger surface.
+
+### Content limits
+
+Rich tooltips should stay short, contextual, and secondary:
+
+- one clear heading or intent
+- one compact supporting explanation
+- optional lightweight action or shortcut hint
+
+### Behavior
+
+The tooltip should remain attached to its trigger context and disappear when the user leaves that context. It should not become the only place where essential task information lives.
 
 ## Accessibility semantics
 
@@ -18,6 +36,16 @@ Rich tooltips provide contextual, supplementary information near a trigger eleme
   </div>
 </Unstyled>
 
+## Usage guidance
+
+### Avoid hidden requirements
+
+If the user must know the message to complete the task safely, do not hide it behind a tooltip. Surface it directly in the layout.
+
+### Keep interaction lightweight
+
+Rich tooltips can contain more than plain text, but they should still feel like supplementary context, not a mini dialog.
+
 ## Resources
 
 - [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
diff --git a/m3-react/storybook/components/M3ScrollRail.mdx b/m3-react/storybook/components/M3ScrollRail.mdx
new file mode 100644
index 0000000..0748656
--- /dev/null
+++ b/m3-react/storybook/components/M3ScrollRail.mdx
@@ -0,0 +1,52 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3ScrollRailStories from './M3ScrollRail.stories'
+
+<Meta of={M3ScrollRailStories} />
+
+# Scroll rails
+
+`M3ScrollRail` is a supporting primitive for scrollable surfaces. It exposes the available scroll axis more clearly than relying on default browser chrome alone, especially inside custom containers.
+
+## API
+
+### When to use
+
+Use `M3ScrollRail` inside bounded regions such as drawers, side sheets, data panels, or media trays when the interface needs a clearer scroll affordance than the platform default provides.
+
+### Orientation
+
+The component can render vertical and horizontal rails. The combined story demonstrates both axes in one container, which is useful for wide content inside a constrained viewport.
+
+### Scope
+
+Material 3 does not publish a dedicated scroll-rail component page. In this workspace, the primitive supports scrollable M3 surfaces such as side sheets, drawers, and long content panes.
+
+## Accessibility semantics
+
+- Keep the scrollable region itself labelled when its purpose is not obvious from nearby context.
+- Avoid trapping keyboard users in custom scroll containers.
+- Preserve readable focus order inside the scrolling content.
+
+## Story guide
+
+- [Both](?path=/story/components-m3scrollrail--both)
+
+## Demo
+
+<Canvas of={M3ScrollRailStories.Both} />
+
+## Usage guidance
+
+### Use rails to reinforce, not replace, structure
+
+The scroll container still needs clear dimensions and hierarchy. A rail cannot compensate for a surface whose content model is already confusing.
+
+### Avoid nested scroll regions unless necessary
+
+Nested scrolling is hard to discover and harder to control with keyboard or touch input. Prefer one dominant scroll region when possible.
+
+## Resources
+
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)
+- [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
+- [M3 Menus overview](https://m3.material.io/components/menus/overview)
diff --git a/m3-react/storybook/components/M3Select.mdx b/m3-react/storybook/components/M3Select.mdx
index b16b8f6..363958c 100644
--- a/m3-react/storybook/components/M3Select.mdx
+++ b/m3-react/storybook/components/M3Select.mdx
@@ -3,9 +3,27 @@ import * as M3SelectStories from './M3Select.stories'
 
 <Meta of={M3SelectStories} />
 
-# M3Select
+# Select
 
-Text field augmented with dropdown menu
+`M3Select` combines text-field presentation with a menu-backed option picker. It fits cases where the current value should stay visible in the form while the available choices open in an anchored list.
+
+## API
+
+### When to use
+
+Use `M3Select` when users must choose one option from a structured list and the current choice should remain visible as field content. If freeform input is allowed, use a text field or autocomplete pattern instead.
+
+### Composition
+
+This implementation follows a hybrid pattern:
+
+- field-like trigger for label, outline, support text, and current value
+- listbox-style option popup for selection
+- optional leading content for selected value and option rows
+
+### Leading visuals
+
+The `WithIcons` story demonstrates a useful Material 3 pattern for country, account, or category pickers where a compact visual cue speeds up recognition without replacing the text label.
 
 ## Accessibility semantics
 
@@ -13,13 +31,43 @@ Text field augmented with dropdown menu
 - Provide a visible label through `label` or an explicit aria-label/aria-labelledby strategy.
 - Keep option labels unique and meaningful for screen readers.
 
+## Story guide
+
+- [Standard](?path=/story/components-m3select--standard)
+- [With Icons](?path=/story/components-m3select--with-icons)
+
 ## Demo
 
 <Canvas of={M3SelectStories.Standard} />
 <Canvas of={M3SelectStories.WithIcons} />
 
+## Usage guidance
+
+### Prefer stable option labels
+
+Because the chosen option is mirrored back into the field, label wording should stay concise and unambiguous. Long, repetitive labels make the closed state harder to scan.
+
+### Keep menus manageable
+
+If the option set becomes very large, consider search or autocomplete instead of a pure select interaction.
+
+## Code example
+
+```tsx
+<M3Select<number>
+  value={value}
+  label="Choose"
+  options={[
+    { label: 'Option 1', value: 1 },
+    { label: 'Option 2', value: 2 },
+  ]}
+  onUpdate={setValue}
+/>
+```
+
 ## Resources
 
+- [M3 Text fields overview](https://m3.material.io/components/text-fields/overview)
 - [M3 Menus overview](https://m3.material.io/components/menus/overview)
 - [M3 Menus guidelines](https://m3.material.io/components/menus/guidelines)
 - [WAI-ARIA APG: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
diff --git a/m3-react/storybook/components/M3Slider.mdx b/m3-react/storybook/components/M3Slider.mdx
index f055726..4cd1d3f 100644
--- a/m3-react/storybook/components/M3Slider.mdx
+++ b/m3-react/storybook/components/M3Slider.mdx
@@ -3,9 +3,24 @@ import * as M3SliderStories from './M3Slider.stories'
 
 <Meta of={M3SliderStories} />
 
-# M3Slider
+# Sliders
 
-Sliders let users make selections from a range of values
+Sliders let users select a value or bounded range with direct manipulation. Material 3 treats them as a good fit for continuous or near-continuous scales where people benefit from seeing relative position.
+
+## API
+
+### When to use
+
+Use `M3Slider` for ranges such as volume, intensity, zoom, or budget bounds. If users need precise text entry or long discrete lists, a text field or select is often clearer.
+
+### Single vs range
+
+- single slider for one value
+- range slider when users define lower and upper bounds together
+
+### Range communication
+
+Range sliders work best when both handles affect the same conceptual value space and when users can understand the minimum and maximum without extra explanation.
 
 ## Accessibility semantics
 
@@ -13,11 +28,26 @@ Sliders let users make selections from a range of values
 - Keep numeric ranges and steps predictable and documented for users.
 - Support keyboard adjustments (Arrow, Home, End) for all handles.
 
+## Story guide
+
+- [Single](?path=/story/components-m3slider--single)
+- [Range](?path=/story/components-m3slider--range)
+
 ## Demo
 
 <Canvas of={M3SliderStories.Single} />
 <Canvas of={M3SliderStories.Range} />
 
+## Usage guidance
+
+### Make scale meaning explicit
+
+Users should understand what the endpoints represent before they drag. Labels, units, or support text usually matter more than the slider control itself.
+
+### Avoid sliders for exact data entry
+
+If the task depends on precise numeric values, provide an exact-input companion or use a different control entirely.
+
 ## Resources
 
 - [M3 Sliders overview](https://m3.material.io/components/sliders/overview)
diff --git a/m3-react/storybook/components/M3Switch.mdx b/m3-react/storybook/components/M3Switch.mdx
index e878f4e..e9870f9 100644
--- a/m3-react/storybook/components/M3Switch.mdx
+++ b/m3-react/storybook/components/M3Switch.mdx
@@ -7,36 +7,49 @@ import * as M3SwitchStories from './M3Switch.stories'
 
 # Switch
 
-<Unstyled>
-  Switches toggle the selection of an item on or off
+Switches communicate an immediate on/off state. They are best for settings and independent toggles where users expect the state to change as soon as they interact.
 
-  * Use switches (not radio buttons) if the items in a list can be independently controlled
-  * Switches are the best way to let users adjust settings
-  * Make sure the switch’s selection (on or off) is visible at a glance
-</Unstyled>
+## API
+
+### When to use
+
+Use `M3Switch` for binary system or preference settings such as Wi-Fi, notifications, or sync. If the choice needs confirmation or belongs to a form submitted later, a checkbox may communicate intent more clearly.
+
+### Immediate behavior
+
+Material 3 switches imply direct state change. The control should reflect the new state right away and the surrounding UI should treat it as active unless the flow explicitly communicates pending sync or save.
 
 ## Accessibility semantics
 
-<Unstyled>
-  * Keep a visible label next to each switch control.
-  * Expose checked state via `role="switch"` and `aria-checked`.
-  * Use switches for immediate on/off state changes, not for multi-choice selections.
-</Unstyled>
+- Keep a visible label next to each switch control.
+- Expose checked state via `role="switch"` and `aria-checked`.
+- Use switches for immediate on/off state changes, not for multi-choice selections.
 
 ### Demo
 
 <Unstyled>
-  <div className="m3-panel m3-panel_elevated-1 my-4" style={{maxWidth: '360px'}}>
+  <div className="m3-panel m3-panel_elevated-1 my-4" style={{ maxWidth: '360px' }}>
     <SwitchExample label="Wi-Fi" className="mb-4" />
     <SwitchExample label="Bluetooth" />
   </div>
 </Unstyled>
 
+## Story guide
+
+- [Standard Switch](?path=/story/components-m3switch--standard-switch)
+
+## Usage guidance
+
+### Write labels as current setting names
+
+Prefer labels like "Wi-Fi" or "Auto-update" over imperative wording like "Enable Wi-Fi." The state of the switch already communicates on/off.
+
+### Avoid switches for irreversible or risky actions
+
+If toggling the control can delete data or trigger destructive side effects, use a safer pattern with clearer confirmation.
+
 ## Resources
 
-<Unstyled>
-  * [Guidelines](https://m3.material.io/components/switch/guidelines)
-  * [M3 Switch overview](https://m3.material.io/components/switch/overview)
-  * [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
-  * [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
-</Unstyled>
+- [M3 Switch overview](https://m3.material.io/components/switch/overview)
+- [M3 Switch guidelines](https://m3.material.io/components/switch/guidelines)
+- [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
diff --git a/m3-react/storybook/components/M3TextField.mdx b/m3-react/storybook/components/M3TextField.mdx
index be61cc9..64b8469 100644
--- a/m3-react/storybook/components/M3TextField.mdx
+++ b/m3-react/storybook/components/M3TextField.mdx
@@ -5,10 +5,28 @@ import * as M3TextFieldStories from './M3TextField.stories'
 
 <Meta of={M3TextFieldStories} />
 
-<Unstyled>
 # Text fields
 
-Text fields let users enter text into a UI.
+Text fields capture short or medium-length textual input. Material 3 uses them as a flexible foundation for plain entry, assisted entry, password input, and multiline editing.
+
+## API
+
+### When to use
+
+Use `M3TextField` for direct text entry, searchable fields, passwords, and compact multiline notes. If the value must come from a predefined list, prefer `M3Select` or autocomplete patterns instead of asking users to type and validate manually.
+
+### Common forms
+
+This workspace supports several Material 3 text-field patterns:
+
+- filled and outlined presentation
+- leading icons
+- password fields
+- multiline input
+
+### Support text and validation
+
+Labels, support text, and validation messages should work together. The field alone rarely communicates enough context for successful data entry.
 
 ## Accessibility semantics
 
@@ -16,12 +34,38 @@ Text fields let users enter text into a UI.
 - Use `aria-invalid` together with helper/support text for validation feedback.
 - For long-form input, prefer multiline mode (`textarea`) with the same labeling strategy.
 
-<TextFieldExamples />
+<Unstyled>
+  <TextFieldExamples />
 </Unstyled>
 
+## Story guide
+
+- [Text Field](?path=/story/components-m3textfield--text-field)
+- [Password Field](?path=/story/components-m3textfield--password-field)
+
+## Usage guidance
+
+### Keep labels persistent
+
+A placeholder is not a replacement for a label. Users need the field purpose to stay visible while typing and when returning to the form later.
+
+### Match type to expected content
+
+Use semantic input types like `email`, `tel`, or `password` whenever possible so browsers and assistive technologies can help users enter data correctly.
+
+## Code example
+
+```tsx
+<M3TextField
+  value={value}
+  label="Email"
+  type="email"
+  onUpdate={setValue}
+/>
+```
+
 ## Resources
 
-- [M3 Text Fields overview](https://m3.material.io/components/text-fields/overview)
-- [M3 Text Fields guidelines](https://m3.material.io/components/text-fields/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [M3 Text fields overview](https://m3.material.io/components/text-fields/overview)
+- [M3 Text fields guidelines](https://m3.material.io/components/text-fields/guidelines)
 - [WAI Tutorials: Form Labels](https://www.w3.org/WAI/tutorials/forms/labels/)
diff --git a/m3-vue/storybook/components/M3Button.mdx b/m3-vue/storybook/components/M3Button.mdx
index f838aa3..5126987 100644
--- a/m3-vue/storybook/components/M3Button.mdx
+++ b/m3-vue/storybook/components/M3Button.mdx
@@ -7,7 +7,25 @@ import * as M3ButtonStories from './M3Button.stories'
 
 # Buttons
 
-Common buttons prompt most actions in a UI
+Buttons communicate available actions and establish hierarchy on a surface. Material 3 distinguishes buttons primarily by emphasis, not by feature set.
+
+## API
+
+### When to use
+
+Use `M3Button` for explicit actions such as save, submit, share, or continue. Prefer buttons over links when the result changes UI state or triggers an in-app operation.
+
+### Appearances
+
+- `filled` for the primary action in a region
+- `elevated` when the action should stand out on low-emphasis surfaces
+- `tonal` for prominent but secondary emphasis
+- `outlined` for lower-emphasis alternatives
+- `text` for lightweight supporting actions
+
+### Icons and labels
+
+Leading icons help scanning when the metaphor is widely understood. Keep the text label explicit even when an icon is present, so the action remains readable without relying on symbol recognition alone.
 
 ## Accessibility semantics
 
@@ -31,11 +49,26 @@ Common buttons prompt most actions in a UI
   <Inline tag={'span'} is={M3Button} icon={'edit'} label={'Edit'} appearance={'tonal'} />
 </p>
 
+## Story guide
+
+- [With Text Only](?path=/story/components-m3button--with-text-only)
+- [With Leading Icon](?path=/story/components-m3button--with-leading-icon)
+
+## Usage guidance
+
+### Keep hierarchy local
+
+Each region should usually have one highest-emphasis action. If everything is filled, users lose the sense of priority that Material 3 buttons are designed to communicate.
+
+### Disable carefully
+
+Use `disabled` only when the action is genuinely unavailable. If the action is available but risky, keep it enabled and explain the consequence instead of hiding the path forward.
+
 ## Code example
 
 ```html
 <M3Button appearance="tonal">
-    <M3Icon name="edit" /> Edit
+  <M3Icon name="edit" /> Edit
 </M3Button>
 ```
 
diff --git a/m3-vue/storybook/components/M3Card.mdx b/m3-vue/storybook/components/M3Card.mdx
index 51b4af4..3d656f0 100644
--- a/m3-vue/storybook/components/M3Card.mdx
+++ b/m3-vue/storybook/components/M3Card.mdx
@@ -10,7 +10,26 @@ import { defineComponent, h } from 'vue'
 
 # Cards
 
-Cards display content and actions about a single subject
+Cards group related content and actions into a single container. In Material 3 they work best when they stay focused on one subject, one decision, or one compact summary.
+
+## API
+
+### When to use
+
+Use `M3Card` when content should feel grouped but still remain embedded in the page flow. If the interaction becomes blocking or needs a scrim, move to `M3Dialog` or `M3Surface`.
+
+### Anatomy
+
+Typical card structure in this workspace includes:
+
+- media or leading visual
+- heading and optional subheading
+- supporting content
+- optional trailing or footer actions
+
+### Appearances
+
+Material 3 cards rely on tone and outline treatment to signal emphasis. This implementation exposes `filled`, `elevated`, and `outlined`, which cover the main hierarchy levels from the official card guidance.
 
 ## Accessibility semantics
 
@@ -25,9 +44,44 @@ Cards display content and actions about a single subject
   ]),
 })} />
 
+## Story guide
+
+- [Landscape](?path=/story/components-m3card--landscape)
+- [Landscape Without Media](?path=/story/components-m3card--landscape-without-media)
+- [Portrait](?path=/story/components-m3card--portrait)
+
+## Usage guidance
+
+### Keep cards focused
+
+Avoid turning a card into a mini page. Once it needs long forms, deep navigation, or persistent editing controls, a larger surface usually communicates the task more clearly.
+
+### Separate container click from inner actions
+
+If the whole card is interactive, nested actions should remain semantically distinct and visually predictable. Competing click targets inside one card quickly become ambiguous.
+
+## Code example
+
+```html
+<M3Card appearance="filled">
+  <template #media>
+    <img alt="" src="/assets/image-720x376.png">
+  </template>
+
+  <template #heading>
+    Title
+  </template>
+
+  <template #subheading>
+    Subhead
+  </template>
+
+  Supporting text
+</M3Card>
+```
+
 ## Resources
 
 - [M3 Cards overview](https://m3.material.io/components/cards/overview)
 - [M3 Cards guidelines](https://m3.material.io/components/cards/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Checkbox.mdx b/m3-vue/storybook/components/M3Checkbox.mdx
index 59c08f1..5c19bb6 100644
--- a/m3-vue/storybook/components/M3Checkbox.mdx
+++ b/m3-vue/storybook/components/M3Checkbox.mdx
@@ -7,7 +7,25 @@ import * as M3CheckboxStories from './M3Checkbox.stories'
 
 # Checkboxes
 
-Checkboxes let users select one or more items from a list, or turn an item on or off
+Checkboxes let users select one or more options independently. They also support parent-child selection patterns where a parent reflects the aggregate state of subordinate items.
+
+## API
+
+### When to use
+
+Use `M3Checkbox` when multiple items can be selected at the same time, or when a single option behaves like a boolean choice inside a form. If the user must pick exactly one option, prefer radios instead.
+
+### Selection model
+
+This implementation supports both simple boolean selection and array-backed multi-select models. It also supports `indeterminate` for aggregate parent rows, which matches the Material 3 guidance for nested selection patterns.
+
+### Nested selection
+
+In nested lists, the parent checkbox should summarize descendant state:
+
+- checked when all descendants are selected
+- indeterminate when some descendants are selected
+- unchecked when none are selected
 
 ## Accessibility semantics
 
@@ -45,9 +63,22 @@ Checkboxes let users select one or more items from a list, or turn an item on or
   }],
 }]} />
 
+## Story guide
+
+- [Standard](?path=/story/components-m3checkbox--standard)
+
+## Usage guidance
+
+### Keep labels explicit
+
+Checkbox labels should describe the resulting state, not the control itself. "Email receipts" is clearer than "Enable."
+
+### Use indeterminate only as summary state
+
+Do not present `indeterminate` as a user-selectable third state. It should only communicate partial selection across descendants.
+
 ## Resources
 
 - [M3 Checkbox overview](https://m3.material.io/components/checkbox/overview)
 - [M3 Checkbox guidelines](https://m3.material.io/components/checkbox/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
diff --git a/m3-vue/storybook/components/M3FabButton.mdx b/m3-vue/storybook/components/M3FabButton.mdx
index aa2a8a6..e735ca0 100644
--- a/m3-vue/storybook/components/M3FabButton.mdx
+++ b/m3-vue/storybook/components/M3FabButton.mdx
@@ -7,7 +7,24 @@ import * as M3FabButtonStories from './M3FabButton.stories'
 
 # Floating action buttons
 
-Floating action buttons (FABs) help people take primary actions
+Floating action buttons emphasize the highest-priority action on a surface. Material 3 treats FABs as strong directional cues, so they work best when the page has one clear "next thing to do."
+
+## API
+
+### When to use
+
+Use `M3FabButton` for the primary action of a screen or large section, especially when that action should remain easy to reach while content scrolls.
+
+### Standard vs extended
+
+- standard FAB for compact icon-first actions
+- extended FAB when the action benefits from a visible label
+
+The extended form is usually easier to scan when the action is not universally obvious from the icon alone.
+
+### Variants
+
+This implementation exposes Material 3 tonal variants such as `surface`, `primary`, `secondary`, and `tertiary`, which let the FAB stay prominent without always defaulting to the same tone.
 
 ## Accessibility semantics
 
@@ -33,11 +50,33 @@ Floating action buttons (FABs) help people take primary actions
   <Inline tag={'span'} is={ButtonExample} icon={'add'} label={'New task'} variant={'tertiary'} />
 </p>
 
+## Story guide
+
+- [Standard](?path=/story/components-m3fabbutton--standard)
+- [Extended](?path=/story/components-m3fabbutton--extended)
+
+## Usage guidance
+
+### One FAB per context
+
+Most surfaces should have at most one FAB. Multiple competing FABs dilute the main-action pattern that Material 3 is trying to reinforce.
+
+### Prefer extended when the icon is ambiguous
+
+If users need to stop and decode the icon, show the label. The slight increase in width is usually worth the clarity.
+
+## Code example
+
+```html
+<M3FabButton>
+  <M3Icon name="add" /> New task
+</M3FabButton>
+```
+
 ## Resources
 
 - [M3 FAB overview](https://m3.material.io/components/floating-action-button/overview)
 - [M3 FAB guidelines](https://m3.material.io/components/floating-action-button/guidelines)
 - [M3 Extended FAB overview](https://m3.material.io/components/extended-fab/overview)
 - [M3 Extended FAB guidelines](https://m3.material.io/components/extended-fab/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3IconButton.mdx b/m3-vue/storybook/components/M3IconButton.mdx
index 17b8c71..581d715 100644
--- a/m3-vue/storybook/components/M3IconButton.mdx
+++ b/m3-vue/storybook/components/M3IconButton.mdx
@@ -8,9 +8,23 @@ import { M3IconButton } from '@/components/icon-button'
 
 <Meta of={M3IconButtonStories} />
 
-# M3IconButton
+# Icon buttons
 
-Icon buttons help people take minor actions with one tap
+Icon buttons surface compact, frequent actions without introducing the visual weight of a full text button. They work best for toolbar actions, trailing row actions, and repeated local controls.
+
+## API
+
+### When to use
+
+Use `M3IconButton` for secondary or utility actions where the icon metaphor is well established. If the action is high-stakes or not obvious from the icon alone, a text button is usually clearer.
+
+### Appearances
+
+Material 3 distinguishes icon buttons by fill and emphasis. This implementation covers `standard`, `filled`, `tonal`, and `outlined`, which map well to common local-action hierarchies.
+
+### Toggleable state
+
+When `toggleable` is enabled, the button should represent an on/off state such as favorite, pin, mute, or bookmark. In that mode, use selection styling together with `aria-pressed`.
 
 ## Accessibility semantics
 
@@ -37,14 +51,42 @@ Icon buttons help people take minor actions with one tap
         'aria-label': 'Toggle favorite',
         'aria-pressed': selected.value ? 'true' : 'false',
         onClick: () => selected.value = !selected.value,
-      }, icon)
+      }, icon),
     ]
   },
 })} />
 
+## Story guide
+
+- [Standard](?path=/story/components-m3iconbutton--standard)
+- [Toggleable](?path=/story/components-m3iconbutton--toggleable)
+
+## Usage guidance
+
+### Keep hit targets generous
+
+Even when the visual icon is small, the interactive target should remain comfortable for pointer and touch use. Material 3 icon buttons depend on this spacing to feel intentional rather than fiddly.
+
+### Use toggles only for persistent state
+
+If the action simply opens a menu or triggers a one-off command, do not model it as selected. Reserve toggle state for something the user can inspect later.
+
+## Code example
+
+```html
+<M3IconButton
+  appearance="tonal"
+  :toggleable="true"
+  :selected="selected"
+  aria-label="Toggle favorite"
+  :aria-pressed="selected"
+>
+  <M3Icon name="favorite" />
+</M3IconButton>
+```
+
 ## Resources
 
 - [M3 Icon Buttons overview](https://m3.material.io/components/icon-buttons/overview)
 - [M3 Icon Buttons guidelines](https://m3.material.io/components/icon-buttons/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
 - [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Navigation.mdx b/m3-vue/storybook/components/M3Navigation.mdx
index d6f4660..b1676f4 100644
--- a/m3-vue/storybook/components/M3Navigation.mdx
+++ b/m3-vue/storybook/components/M3Navigation.mdx
@@ -5,7 +5,21 @@ import * as M3NavigationStories from './M3Navigation.stories'
 
 # Navigation
 
-Navigation components help users move between top-level destinations.
+Navigation components help users move between top-level destinations. Material 3 splits navigation patterns by available space and permanence, not only by visual style.
+
+## API
+
+### When to use
+
+Use `M3Navigation` for app-level destinations that users may revisit repeatedly during the session. Keep these destinations stable and semantically distinct from local page tabs or in-content filters.
+
+### Navigation forms
+
+- navigation drawer for broad destination sets and more descriptive labels
+- navigation rail for medium and large layouts where a vertical persistent control fits the shell
+- navigation bar for compact layouts and a small number of top-level destinations
+
+The current stories focus on drawer and rail, which are the forms implemented in this workspace today.
 
 ## Accessibility semantics
 
@@ -13,11 +27,24 @@ Navigation components help users move between top-level destinations.
 - Keep destination labels concise and unique.
 - Expose active destination state consistently in routed integrations.
 
+## Story guide
+
+- [Navigation Drawer](?path=/story/components-m3navigation--navigation-drawer)
+- [Navigation Rail](?path=/story/components-m3navigation--navigation-rail)
+
+## Usage guidance
+
+### Keep destination sets small and stable
+
+Top-level navigation should not behave like a task-specific filter group. If items appear and disappear unpredictably, users lose the mental map that navigation is supposed to provide.
+
+### Match pattern to layout
+
+Use drawer or rail based on screen width, information density, and shell persistence. Do not switch patterns arbitrarily if the content model itself has not changed.
+
 ## Resources
 
 - [M3 Navigation bar overview](https://m3.material.io/components/navigation-bar/overview)
 - [M3 Navigation rail overview](https://m3.material.io/components/navigation-rail/overview)
 - [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
-- [Storybook: NavigationDrawer](?path=/story/components-m3navigation--navigation-drawer)
-- [Storybook: NavigationRail](?path=/story/components-m3navigation--navigation-rail)
 - [WAI-ARIA APG: Landmark Regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)
diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index 4873fe4..13f16e6 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -5,7 +5,25 @@ import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip.vue'
 
 # Rich tooltip
 
-Rich tooltips provide contextual, supplementary information near a trigger element.
+Rich tooltips provide contextual, supplementary information near a trigger element. Compared with plain tooltips, they support a slightly denser content payload while still staying lightweight and non-blocking.
+
+## API
+
+### When to use
+
+Use a rich tooltip for brief supporting information, shortcuts, or action consequences that help the user decide without forcing them into a dialog. If the content becomes critical or requires interaction-heavy confirmation, move to a larger surface.
+
+### Content limits
+
+Rich tooltips should stay short, contextual, and secondary:
+
+- one clear heading or intent
+- one compact supporting explanation
+- optional lightweight action or shortcut hint
+
+### Behavior
+
+The tooltip should remain attached to its trigger context and disappear when the user leaves that context. It should not become the only place where essential task information lives.
 
 ## Accessibility semantics
 
@@ -22,6 +40,16 @@ Rich tooltips provide contextual, supplementary information near a trigger eleme
   </div>
 </Unstyled>
 
+## Usage guidance
+
+### Avoid hidden requirements
+
+If the user must know the message to complete the task safely, do not hide it behind a tooltip. Surface it directly in the layout.
+
+### Keep interaction lightweight
+
+Rich tooltips can contain more than plain text, but they should still feel like supplementary context, not a mini dialog.
+
 ## Resources
 
 - [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
diff --git a/m3-vue/storybook/components/M3ScrollRail.mdx b/m3-vue/storybook/components/M3ScrollRail.mdx
new file mode 100644
index 0000000..0748656
--- /dev/null
+++ b/m3-vue/storybook/components/M3ScrollRail.mdx
@@ -0,0 +1,52 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3ScrollRailStories from './M3ScrollRail.stories'
+
+<Meta of={M3ScrollRailStories} />
+
+# Scroll rails
+
+`M3ScrollRail` is a supporting primitive for scrollable surfaces. It exposes the available scroll axis more clearly than relying on default browser chrome alone, especially inside custom containers.
+
+## API
+
+### When to use
+
+Use `M3ScrollRail` inside bounded regions such as drawers, side sheets, data panels, or media trays when the interface needs a clearer scroll affordance than the platform default provides.
+
+### Orientation
+
+The component can render vertical and horizontal rails. The combined story demonstrates both axes in one container, which is useful for wide content inside a constrained viewport.
+
+### Scope
+
+Material 3 does not publish a dedicated scroll-rail component page. In this workspace, the primitive supports scrollable M3 surfaces such as side sheets, drawers, and long content panes.
+
+## Accessibility semantics
+
+- Keep the scrollable region itself labelled when its purpose is not obvious from nearby context.
+- Avoid trapping keyboard users in custom scroll containers.
+- Preserve readable focus order inside the scrolling content.
+
+## Story guide
+
+- [Both](?path=/story/components-m3scrollrail--both)
+
+## Demo
+
+<Canvas of={M3ScrollRailStories.Both} />
+
+## Usage guidance
+
+### Use rails to reinforce, not replace, structure
+
+The scroll container still needs clear dimensions and hierarchy. A rail cannot compensate for a surface whose content model is already confusing.
+
+### Avoid nested scroll regions unless necessary
+
+Nested scrolling is hard to discover and harder to control with keyboard or touch input. Prefer one dominant scroll region when possible.
+
+## Resources
+
+- [M3 Side sheets overview](https://m3.material.io/components/side-sheets/overview)
+- [M3 Navigation drawer overview](https://m3.material.io/components/navigation-drawer/overview)
+- [M3 Menus overview](https://m3.material.io/components/menus/overview)
diff --git a/m3-vue/storybook/components/M3Select.mdx b/m3-vue/storybook/components/M3Select.mdx
index b16b8f6..ce604b9 100644
--- a/m3-vue/storybook/components/M3Select.mdx
+++ b/m3-vue/storybook/components/M3Select.mdx
@@ -3,9 +3,27 @@ import * as M3SelectStories from './M3Select.stories'
 
 <Meta of={M3SelectStories} />
 
-# M3Select
+# Select
 
-Text field augmented with dropdown menu
+`M3Select` combines text-field presentation with a menu-backed option picker. It fits cases where the current value should stay visible in the form while the available choices open in an anchored list.
+
+## API
+
+### When to use
+
+Use `M3Select` when users must choose one option from a structured list and the current choice should remain visible as field content. If freeform input is allowed, use a text field or autocomplete pattern instead.
+
+### Composition
+
+This implementation follows a hybrid pattern:
+
+- field-like trigger for label, outline, support text, and current value
+- listbox-style option popup for selection
+- optional leading content for selected value and option rows
+
+### Leading visuals
+
+The `WithIcons` story demonstrates a useful Material 3 pattern for country, account, or category pickers where a compact visual cue speeds up recognition without replacing the text label.
 
 ## Accessibility semantics
 
@@ -13,13 +31,42 @@ Text field augmented with dropdown menu
 - Provide a visible label through `label` or an explicit aria-label/aria-labelledby strategy.
 - Keep option labels unique and meaningful for screen readers.
 
+## Story guide
+
+- [Standard](?path=/story/components-m3select--standard)
+- [With Icons](?path=/story/components-m3select--with-icons)
+
 ## Demo
 
 <Canvas of={M3SelectStories.Standard} />
 <Canvas of={M3SelectStories.WithIcons} />
 
+## Usage guidance
+
+### Prefer stable option labels
+
+Because the chosen option is mirrored back into the field, label wording should stay concise and unambiguous. Long, repetitive labels make the closed state harder to scan.
+
+### Keep menus manageable
+
+If the option set becomes very large, consider search or autocomplete instead of a pure select interaction.
+
+## Code example
+
+```html
+<M3Select
+  v-model:value="value"
+  label="Choose"
+  :options="[
+    { label: 'Option 1', value: 1 },
+    { label: 'Option 2', value: 2 },
+  ]"
+/>
+```
+
 ## Resources
 
+- [M3 Text fields overview](https://m3.material.io/components/text-fields/overview)
 - [M3 Menus overview](https://m3.material.io/components/menus/overview)
 - [M3 Menus guidelines](https://m3.material.io/components/menus/guidelines)
 - [WAI-ARIA APG: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
diff --git a/m3-vue/storybook/components/M3Slider.mdx b/m3-vue/storybook/components/M3Slider.mdx
index f055726..4cd1d3f 100644
--- a/m3-vue/storybook/components/M3Slider.mdx
+++ b/m3-vue/storybook/components/M3Slider.mdx
@@ -3,9 +3,24 @@ import * as M3SliderStories from './M3Slider.stories'
 
 <Meta of={M3SliderStories} />
 
-# M3Slider
+# Sliders
 
-Sliders let users make selections from a range of values
+Sliders let users select a value or bounded range with direct manipulation. Material 3 treats them as a good fit for continuous or near-continuous scales where people benefit from seeing relative position.
+
+## API
+
+### When to use
+
+Use `M3Slider` for ranges such as volume, intensity, zoom, or budget bounds. If users need precise text entry or long discrete lists, a text field or select is often clearer.
+
+### Single vs range
+
+- single slider for one value
+- range slider when users define lower and upper bounds together
+
+### Range communication
+
+Range sliders work best when both handles affect the same conceptual value space and when users can understand the minimum and maximum without extra explanation.
 
 ## Accessibility semantics
 
@@ -13,11 +28,26 @@ Sliders let users make selections from a range of values
 - Keep numeric ranges and steps predictable and documented for users.
 - Support keyboard adjustments (Arrow, Home, End) for all handles.
 
+## Story guide
+
+- [Single](?path=/story/components-m3slider--single)
+- [Range](?path=/story/components-m3slider--range)
+
 ## Demo
 
 <Canvas of={M3SliderStories.Single} />
 <Canvas of={M3SliderStories.Range} />
 
+## Usage guidance
+
+### Make scale meaning explicit
+
+Users should understand what the endpoints represent before they drag. Labels, units, or support text usually matter more than the slider control itself.
+
+### Avoid sliders for exact data entry
+
+If the task depends on precise numeric values, provide an exact-input companion or use a different control entirely.
+
 ## Resources
 
 - [M3 Sliders overview](https://m3.material.io/components/sliders/overview)
diff --git a/m3-vue/storybook/components/M3Switch.mdx b/m3-vue/storybook/components/M3Switch.mdx
index f19d706..4f5e389 100644
--- a/m3-vue/storybook/components/M3Switch.mdx
+++ b/m3-vue/storybook/components/M3Switch.mdx
@@ -8,21 +8,23 @@ import * as M3SwitchStories from './M3Switch.stories'
 
 # Switch
 
-<Unstyled>
-  Switches toggle the selection of an item on or off
+Switches communicate an immediate on/off state. They are best for settings and independent toggles where users expect the state to change as soon as they interact.
 
-  * Use switches (not radio buttons) if the items in a list can be independently controlled
-  * Switches are the best way to let users adjust settings
-  * Make sure the switch’s selection (on or off) is visible at a glance
-</Unstyled>
+## API
+
+### When to use
+
+Use `M3Switch` for binary system or preference settings such as Wi-Fi, notifications, or sync. If the choice needs confirmation or belongs to a form submitted later, a checkbox may communicate intent more clearly.
+
+### Immediate behavior
+
+Material 3 switches imply direct state change. The control should reflect the new state right away and the surrounding UI should treat it as active unless the flow explicitly communicates pending sync or save.
 
 ## Accessibility semantics
 
-<Unstyled>
-  * Keep a visible label next to each switch control.
-  * Expose checked state via `role="switch"` and `aria-checked`.
-  * Use switches for immediate on/off state changes, not for multi-choice selections.
-</Unstyled>
+- Keep a visible label next to each switch control.
+- Expose checked state via `role="switch"` and `aria-checked`.
+- Use switches for immediate on/off state changes, not for multi-choice selections.
 
 ### Demo
 
@@ -36,11 +38,22 @@ import * as M3SwitchStories from './M3Switch.stories'
   </div>
 </Unstyled>
 
+## Story guide
+
+- [Standard Switch](?path=/story/components-m3switch--standard-switch)
+
+## Usage guidance
+
+### Write labels as current setting names
+
+Prefer labels like "Wi-Fi" or "Auto-update" over imperative wording like "Enable Wi-Fi." The state of the switch already communicates on/off.
+
+### Avoid switches for irreversible or risky actions
+
+If toggling the control can delete data or trigger destructive side effects, use a safer pattern with clearer confirmation.
+
 ## Resources
 
-<Unstyled>
-  * [Guidelines](https://m3.material.io/components/switch/guidelines)
-  * [M3 Switch overview](https://m3.material.io/components/switch/overview)
-  * [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
-  * [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
-</Unstyled>
+- [M3 Switch overview](https://m3.material.io/components/switch/overview)
+- [M3 Switch guidelines](https://m3.material.io/components/switch/guidelines)
+- [WAI-ARIA APG: Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
diff --git a/m3-vue/storybook/components/M3TextField.mdx b/m3-vue/storybook/components/M3TextField.mdx
index 900260b..05153ae 100644
--- a/m3-vue/storybook/components/M3TextField.mdx
+++ b/m3-vue/storybook/components/M3TextField.mdx
@@ -12,7 +12,26 @@ import { M3TextField } from '@/components/text-field'
 <Unstyled>
 # Text fields
 
-Text fields let users enter text into a UI
+Text fields capture short or medium-length textual input. Material 3 uses them as a flexible foundation for plain entry, assisted entry, password input, and multiline editing.
+
+## API
+
+### When to use
+
+Use `M3TextField` for direct text entry, searchable fields, passwords, and compact multiline notes. If the value must come from a predefined list, prefer `M3Select` or autocomplete patterns instead of asking users to type and validate manually.
+
+### Common forms
+
+This workspace supports several Material 3 text-field patterns:
+
+- filled and outlined presentation
+- leading icons
+- password fields
+- multiline input
+
+### Support text and validation
+
+Labels, support text, and validation messages should work together. The field alone rarely communicates enough context for successful data entry.
 
 ## Accessibility semantics
 
@@ -79,11 +98,35 @@ Outlined text field:
     })
   },
 })} />
+
+## Story guide
+
+- [Text Field](?path=/story/components-m3textfield--text-field)
+- [Password Field](?path=/story/components-m3textfield--password-field)
+
+## Usage guidance
+
+### Keep labels persistent
+
+A placeholder is not a replacement for a label. Users need the field purpose to stay visible while typing and when returning to the form later.
+
+### Match type to expected content
+
+Use semantic input types like `email`, `tel`, or `password` whenever possible so browsers and assistive technologies can help users enter data correctly.
+
+## Code example
+
+```html
+<M3TextField
+  v-model:value="value"
+  label="Email"
+  type="email"
+/>
+```
 </Unstyled>
 
 ## Resources
 
-- [M3 Text Fields overview](https://m3.material.io/components/text-fields/overview)
-- [M3 Text Fields guidelines](https://m3.material.io/components/text-fields/guidelines)
-- [Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+- [M3 Text fields overview](https://m3.material.io/components/text-fields/overview)
+- [M3 Text fields guidelines](https://m3.material.io/components/text-fields/guidelines)
 - [WAI Tutorials: Form Labels](https://www.w3.org/WAI/tutorials/forms/labels/)

From 137fb3e5e8810e8f55935f773e547170f9a7a124 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 18:18:43 +0400
Subject: [PATCH 28/37] feat: Storybook examples were expanded for Material 3

---
 m3-react/storybook/components/M3Button.mdx    |  2 +
 .../storybook/components/M3Button.stories.tsx | 57 ++++++++++++++++
 m3-react/storybook/components/M3Checkbox.mdx  |  1 +
 .../components/M3Checkbox.stories.tsx         | 22 ++++++
 .../storybook/components/M3IconButton.mdx     |  1 +
 .../components/M3IconButton.stories.tsx       | 43 ++++++++++++
 m3-react/storybook/components/M3Menu.mdx      |  2 +
 .../storybook/components/M3Menu.stories.tsx   | 51 ++++++++++++++
 m3-react/storybook/components/M3TextField.mdx |  2 +
 .../components/M3TextField.stories.tsx        | 37 ++++++++++
 m3-vue/storybook/components/M3Button.mdx      |  2 +
 .../storybook/components/M3Button.stories.ts  | 68 +++++++++++++++++++
 m3-vue/storybook/components/M3Checkbox.mdx    |  1 +
 .../components/M3Checkbox.stories.ts          | 28 ++++++++
 m3-vue/storybook/components/M3IconButton.mdx  |  1 +
 .../components/M3IconButton.stories.ts        | 43 ++++++++++++
 m3-vue/storybook/components/M3TextField.mdx   |  2 +
 .../components/M3TextField.stories.ts         | 44 ++++++++++++
 18 files changed, 407 insertions(+)

diff --git a/m3-react/storybook/components/M3Button.mdx b/m3-react/storybook/components/M3Button.mdx
index 7685673..e5a8210 100644
--- a/m3-react/storybook/components/M3Button.mdx
+++ b/m3-react/storybook/components/M3Button.mdx
@@ -56,6 +56,8 @@ Leading icons help scanning when the metaphor is widely understood. Keep the tex
 
 - [With Text Only](?path=/story/components-m3button--with-text-only)
 - [With Leading Icon](?path=/story/components-m3button--with-leading-icon)
+- [Appearance Matrix](?path=/story/components-m3button--appearance-matrix)
+- [Disabled States](?path=/story/components-m3button--disabled-states)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Button.stories.tsx b/m3-react/storybook/components/M3Button.stories.tsx
index 1c1ffcb..6160db6 100644
--- a/m3-react/storybook/components/M3Button.stories.tsx
+++ b/m3-react/storybook/components/M3Button.stories.tsx
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
 
 import React from 'react'
+import type { CSSProperties } from 'react'
 
 import { M3Button } from '@/components/button'
 import { M3Icon } from '@/components/icon'
@@ -44,6 +45,7 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 export const WithTextOnly: Story = {}
+
 export const WithLeadingIcon: Story = {
   render: (args) => (
     <M3Button {...args}>
@@ -51,3 +53,58 @@ export const WithLeadingIcon: Story = {
     </M3Button>
   ),
 }
+
+export const AppearanceMatrix: Story = {
+  render: () => {
+    const stack = {
+      display: 'grid',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    return (
+      <div style={stack}>
+        <div style={row}>
+          {values.appearances.map(appearance => (
+            <M3Button key={appearance} appearance={appearance}>
+              Share
+            </M3Button>
+          ))}
+        </div>
+
+        <div style={row}>
+          {values.appearances.map(appearance => (
+            <M3Button key={appearance} appearance={appearance}>
+              <M3Icon name="share" /> Share
+            </M3Button>
+          ))}
+        </div>
+      </div>
+    )
+  },
+}
+
+export const DisabledStates: Story = {
+  render: () => {
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    return (
+      <div style={row}>
+        {values.appearances.map(appearance => (
+          <M3Button key={appearance} appearance={appearance} disabled={true}>
+            Share
+          </M3Button>
+        ))}
+      </div>
+    )
+  },
+}
diff --git a/m3-react/storybook/components/M3Checkbox.mdx b/m3-react/storybook/components/M3Checkbox.mdx
index 221e093..e71aefc 100644
--- a/m3-react/storybook/components/M3Checkbox.mdx
+++ b/m3-react/storybook/components/M3Checkbox.mdx
@@ -74,6 +74,7 @@ In nested lists, the parent checkbox should summarize descendant state:
 ## Story guide
 
 - [Standard](?path=/story/components-m3checkbox--standard)
+- [Nested Selection](?path=/story/components-m3checkbox--nested-selection)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Checkbox.stories.tsx b/m3-react/storybook/components/M3Checkbox.stories.tsx
index 03ad7fd..b8ff40d 100644
--- a/m3-react/storybook/components/M3Checkbox.stories.tsx
+++ b/m3-react/storybook/components/M3Checkbox.stories.tsx
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
 
 import { M3Checkbox } from '@/components/checkbox'
+import CheckboxList from '../examples/checkbox/CheckboxList'
 
 import { useState } from 'react'
 import { useId } from '@/hooks'
@@ -58,3 +59,24 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 export const Standard: Story = {}
+
+export const NestedSelection: Story = {
+  render: () => (
+    <CheckboxList
+      options={[{
+        label: 'Notifications',
+        value: 'notifications',
+        subordinates: [{
+          label: 'Email',
+          value: 'email',
+        }, {
+          label: 'Push',
+          value: 'push',
+        }, {
+          label: 'SMS',
+          value: 'sms',
+        }],
+      }]}
+    />
+  ),
+}
diff --git a/m3-react/storybook/components/M3IconButton.mdx b/m3-react/storybook/components/M3IconButton.mdx
index 0ff8677..0d2b6a5 100644
--- a/m3-react/storybook/components/M3IconButton.mdx
+++ b/m3-react/storybook/components/M3IconButton.mdx
@@ -49,6 +49,7 @@ When `toggleable` is enabled, the button should represent an on/off state such a
 
 - [Standard](?path=/story/components-m3iconbutton--standard)
 - [Toggleable](?path=/story/components-m3iconbutton--toggleable)
+- [Appearance Matrix](?path=/story/components-m3iconbutton--appearance-matrix)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3IconButton.stories.tsx b/m3-react/storybook/components/M3IconButton.stories.tsx
index 80640c5..4c3ebef 100644
--- a/m3-react/storybook/components/M3IconButton.stories.tsx
+++ b/m3-react/storybook/components/M3IconButton.stories.tsx
@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import type { CSSProperties } from 'react'
 
 import { M3Icon } from '@/components/icon'
 import { M3IconButton } from '@/components/icon-button'
@@ -73,3 +74,45 @@ export const Toggleable: Story = {
     return <M3IconButtonToggleable />
   },
 }
+
+export const AppearanceMatrix: Story = {
+  render: () => {
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    const stack = {
+      display: 'grid',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    const appearances = ['standard', 'filled', 'tonal', 'outlined'] as const
+
+    return (
+      <div style={stack}>
+        <div style={row}>
+          {appearances.map(appearance => (
+            <M3IconButton key={appearance} appearance={appearance} aria-label={appearance}>
+              <M3Icon name="favorite" />
+            </M3IconButton>
+          ))}
+        </div>
+
+        <div style={row}>
+          {appearances.map(appearance => (
+            <M3IconButton
+              key={appearance}
+              appearance={appearance}
+              aria-label={appearance + '-disabled'}
+              disabled={true}
+            >
+              <M3Icon name="favorite" />
+            </M3IconButton>
+          ))}
+        </div>
+      </div>
+    )
+  },
+}
diff --git a/m3-react/storybook/components/M3Menu.mdx b/m3-react/storybook/components/M3Menu.mdx
index da2581b..0f970b9 100644
--- a/m3-react/storybook/components/M3Menu.mdx
+++ b/m3-react/storybook/components/M3Menu.mdx
@@ -30,10 +30,12 @@ Selected rows can communicate the current choice inside the menu, but the menu i
 ## Story guide
 
 - [Standard](?path=/story/components-m3menu--standard)
+- [With Leading And Trailing Content](?path=/story/components-m3menu--with-leading-and-trailing-content)
 
 ## Demo
 
 <Canvas of={M3MenuStories.Standard} />
+<Canvas of={M3MenuStories.WithLeadingAndTrailingContent} />
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Menu.stories.tsx b/m3-react/storybook/components/M3Menu.stories.tsx
index ba907be..b641edb 100644
--- a/m3-react/storybook/components/M3Menu.stories.tsx
+++ b/m3-react/storybook/components/M3Menu.stories.tsx
@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react'
 import type { M3MenuProps } from '@/components/menu'
 
 import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
 import { M3Menu, M3MenuItem } from '@/components/menu'
 import { useCallback, useState } from 'react'
 
@@ -66,3 +67,53 @@ export const Standard: Story = {
     target: null,
   },
 }
+
+export const WithLeadingAndTrailingContent: Story = {
+  args: {
+    target: null,
+  },
+
+  render: (args) => {
+    const [target, setTarget] = useState<HTMLElement | null>(null)
+    const bindTarget = useCallback((el: HTMLButtonElement) => {
+      setTarget(el)
+      return () => {
+        setTarget(current => current === el ? null : current)
+      }
+    }, [])
+
+    return (
+      <div style={{ minHeight: '220px', minWidth: '280px' }}>
+        <M3Button effects={[bindTarget]}>
+          Open menu
+        </M3Button>
+
+        <M3Menu
+          {...args}
+          target={target}
+        >
+          <M3MenuItem>
+            <M3MenuItem.Leading>
+              <M3Icon name="edit" />
+            </M3MenuItem.Leading>
+            Edit profile
+          </M3MenuItem>
+
+          <M3MenuItem selected={true}>
+            <M3MenuItem.Leading>
+              <M3Icon name="favorite" />
+            </M3MenuItem.Leading>
+            Favorite
+            <M3MenuItem.Trailing>
+              <span style={{ fontSize: '12px' }}>Selected</span>
+            </M3MenuItem.Trailing>
+          </M3MenuItem>
+
+          <M3MenuItem disabled={true}>
+            Archive
+          </M3MenuItem>
+        </M3Menu>
+      </div>
+    )
+  },
+}
diff --git a/m3-react/storybook/components/M3TextField.mdx b/m3-react/storybook/components/M3TextField.mdx
index 64b8469..7da7248 100644
--- a/m3-react/storybook/components/M3TextField.mdx
+++ b/m3-react/storybook/components/M3TextField.mdx
@@ -42,6 +42,8 @@ Labels, support text, and validation messages should work together. The field al
 
 - [Text Field](?path=/story/components-m3textfield--text-field)
 - [Password Field](?path=/story/components-m3textfield--password-field)
+- [Outlined With Leading Icon](?path=/story/components-m3textfield--outlined-with-leading-icon)
+- [Multiline Outlined](?path=/story/components-m3textfield--multiline-outlined)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3TextField.stories.tsx b/m3-react/storybook/components/M3TextField.stories.tsx
index 97e30d2..d7bccbe 100644
--- a/m3-react/storybook/components/M3TextField.stories.tsx
+++ b/m3-react/storybook/components/M3TextField.stories.tsx
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import type { M3TextFieldProps } from '@/components/text-field'
 
+import { M3Icon } from '@/components/icon'
 import {
   M3TextField,
 } from '@/components/text-field'
@@ -74,3 +75,39 @@ export const PasswordField: Story = {
     label: 'Password field',
   },
 }
+
+export const OutlinedWithLeadingIcon: Story = {
+  render: (args) => (
+    <div style={{ width: '320px' }}>
+      <M3TextFieldStoryWithLeadingIcon {...args} />
+    </div>
+  ),
+
+  args: {
+    type: 'email',
+    label: 'Email',
+    outlined: true,
+    placeholder: 'name@example.com',
+  },
+}
+
+export const MultilineOutlined: Story = {
+  args: {
+    label: 'About',
+    outlined: true,
+    multiline: true,
+    placeholder: 'Add a short summary',
+  },
+}
+
+const M3TextFieldStoryWithLeadingIcon = (args: M3TextFieldProps) => {
+  const [value, setValue] = useState('')
+
+  return (
+    <M3TextField value={value} onUpdate={setValue} {...args}>
+      <M3TextField.LeadingIcon>
+        <M3Icon name="mail" />
+      </M3TextField.LeadingIcon>
+    </M3TextField>
+  )
+}
diff --git a/m3-vue/storybook/components/M3Button.mdx b/m3-vue/storybook/components/M3Button.mdx
index 5126987..c3b4276 100644
--- a/m3-vue/storybook/components/M3Button.mdx
+++ b/m3-vue/storybook/components/M3Button.mdx
@@ -53,6 +53,8 @@ Leading icons help scanning when the metaphor is widely understood. Keep the tex
 
 - [With Text Only](?path=/story/components-m3button--with-text-only)
 - [With Leading Icon](?path=/story/components-m3button--with-leading-icon)
+- [Appearance Matrix](?path=/story/components-m3button--appearance-matrix)
+- [Disabled States](?path=/story/components-m3button--disabled-states)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Button.stories.ts b/m3-vue/storybook/components/M3Button.stories.ts
index cc290fc..369f569 100644
--- a/m3-vue/storybook/components/M3Button.stories.ts
+++ b/m3-vue/storybook/components/M3Button.stories.ts
@@ -68,3 +68,71 @@ export const WithLeadingIcon: Story = {
     `,
   }),
 }
+
+export const AppearanceMatrix: Story = {
+  // eslint-disable-next-line max-lines-per-function
+  render: () => ({
+    components: {
+      M3Button,
+      M3Icon,
+    },
+
+    setup () {
+      return {
+        appearances: values.appearances,
+      }
+    },
+
+    template: `
+        <div style="display: grid; gap: 16px;">
+            <div style="display: flex; flex-wrap: wrap; gap: 16px;">
+                <M3Button
+                    v-for="appearance in appearances"
+                    :key="'text-' + appearance"
+                    :appearance="appearance"
+                >
+                    Share
+                </M3Button>
+            </div>
+
+            <div style="display: flex; flex-wrap: wrap; gap: 16px;">
+                <M3Button
+                    v-for="appearance in appearances"
+                    :key="'icon-' + appearance"
+                    :appearance="appearance"
+                >
+                    <M3Icon name="share" />
+                    Share
+                </M3Button>
+            </div>
+        </div>
+    `,
+  }),
+}
+
+export const DisabledStates: Story = {
+  render: () => ({
+    components: {
+      M3Button,
+    },
+
+    setup () {
+      return {
+        appearances: values.appearances,
+      }
+    },
+
+    template: `
+        <div style="display: flex; flex-wrap: wrap; gap: 16px;">
+            <M3Button
+                v-for="appearance in appearances"
+                :key="appearance"
+                :appearance="appearance"
+                disabled
+            >
+                Share
+            </M3Button>
+        </div>
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/components/M3Checkbox.mdx b/m3-vue/storybook/components/M3Checkbox.mdx
index 5c19bb6..5199ab7 100644
--- a/m3-vue/storybook/components/M3Checkbox.mdx
+++ b/m3-vue/storybook/components/M3Checkbox.mdx
@@ -66,6 +66,7 @@ In nested lists, the parent checkbox should summarize descendant state:
 ## Story guide
 
 - [Standard](?path=/story/components-m3checkbox--standard)
+- [Nested Selection](?path=/story/components-m3checkbox--nested-selection)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Checkbox.stories.ts b/m3-vue/storybook/components/M3Checkbox.stories.ts
index 30febee..d30f3b7 100644
--- a/m3-vue/storybook/components/M3Checkbox.stories.ts
+++ b/m3-vue/storybook/components/M3Checkbox.stories.ts
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/vue3'
 
 import { M3Checkbox } from '@/components/checkbox'
+import CheckboxList from '../examples/checkbox/CheckboxList.vue'
 import { ref } from 'vue'
 
 import useId from '@/composables/id'
@@ -48,3 +49,30 @@ export default meta
 type Story = StoryObj<typeof meta>
 
 export const Standard: Story = {}
+
+export const NestedSelection: Story = {
+  render: () => ({
+    components: {
+      CheckboxList,
+    },
+
+    template: `
+      <CheckboxList
+          :options="[{
+              label: 'Notifications',
+              value: 'notifications',
+              subordinates: [{
+                  label: 'Email',
+                  value: 'email',
+              }, {
+                  label: 'Push',
+                  value: 'push',
+              }, {
+                  label: 'SMS',
+                  value: 'sms',
+              }],
+          }]"
+      />
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/components/M3IconButton.mdx b/m3-vue/storybook/components/M3IconButton.mdx
index 581d715..8d66c8d 100644
--- a/m3-vue/storybook/components/M3IconButton.mdx
+++ b/m3-vue/storybook/components/M3IconButton.mdx
@@ -60,6 +60,7 @@ When `toggleable` is enabled, the button should represent an on/off state such a
 
 - [Standard](?path=/story/components-m3iconbutton--standard)
 - [Toggleable](?path=/story/components-m3iconbutton--toggleable)
+- [Appearance Matrix](?path=/story/components-m3iconbutton--appearance-matrix)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3IconButton.stories.ts b/m3-vue/storybook/components/M3IconButton.stories.ts
index 430a0a1..330e77d 100644
--- a/m3-vue/storybook/components/M3IconButton.stories.ts
+++ b/m3-vue/storybook/components/M3IconButton.stories.ts
@@ -90,3 +90,46 @@ export const Toggleable: Story = {
     `,
   }),
 }
+
+export const AppearanceMatrix: Story = {
+  // eslint-disable-next-line max-lines-per-function
+  render: () => ({
+    components: {
+      M3Icon,
+      M3IconButton,
+    },
+
+    setup () {
+      return {
+        appearances: ['standard', 'filled', 'tonal', 'outlined'],
+      }
+    },
+
+    template: `
+        <div style="display: grid; gap: 16px;">
+            <div style="display: flex; flex-wrap: wrap; gap: 16px;">
+                <M3IconButton
+                    v-for="appearance in appearances"
+                    :key="appearance"
+                    :appearance="appearance"
+                    :aria-label="appearance"
+                >
+                    <M3Icon name="favorite" />
+                </M3IconButton>
+            </div>
+
+            <div style="display: flex; flex-wrap: wrap; gap: 16px;">
+                <M3IconButton
+                    v-for="appearance in appearances"
+                    :key="appearance + '-disabled'"
+                    :appearance="appearance"
+                    :aria-label="appearance + '-disabled'"
+                    disabled
+                >
+                    <M3Icon name="favorite" />
+                </M3IconButton>
+            </div>
+        </div>
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/components/M3TextField.mdx b/m3-vue/storybook/components/M3TextField.mdx
index 05153ae..718eb66 100644
--- a/m3-vue/storybook/components/M3TextField.mdx
+++ b/m3-vue/storybook/components/M3TextField.mdx
@@ -103,6 +103,8 @@ Outlined text field:
 
 - [Text Field](?path=/story/components-m3textfield--text-field)
 - [Password Field](?path=/story/components-m3textfield--password-field)
+- [Outlined With Leading Icon](?path=/story/components-m3textfield--outlined-with-leading-icon)
+- [Multiline Outlined](?path=/story/components-m3textfield--multiline-outlined)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3TextField.stories.ts b/m3-vue/storybook/components/M3TextField.stories.ts
index 93a74fe..1e77d41 100644
--- a/m3-vue/storybook/components/M3TextField.stories.ts
+++ b/m3-vue/storybook/components/M3TextField.stories.ts
@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/vue3'
 
+import { M3Icon } from '@/components/icon'
 import { M3TextField } from '@/components/text-field'
 
 import { ref } from 'vue'
@@ -68,3 +69,46 @@ export const PasswordField: Story = {
     label: 'Password field',
   },
 }
+
+export const OutlinedWithLeadingIcon: Story = {
+  args: {
+    type: 'email',
+    label: 'Email',
+    outlined: true,
+    placeholder: 'name@example.com',
+  },
+
+  render: (args: unknown) => ({
+    components: {
+      M3Icon,
+      M3TextField,
+    },
+
+    setup () {
+      return {
+        args,
+        value: ref(''),
+      }
+    },
+
+    template: `
+        <M3TextField
+            v-model:value="value"
+            v-bind="args"
+        >
+            <template #leading-icon>
+                <M3Icon name="mail" />
+            </template>
+        </M3TextField>
+    `,
+  }),
+}
+
+export const MultilineOutlined: Story = {
+  args: {
+    label: 'About',
+    outlined: true,
+    multiline: true,
+    placeholder: 'Add a short summary',
+  },
+}

From 13bb36fc534f2868cfe1f4afec00d206a01db3e4 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 18:22:55 +0400
Subject: [PATCH 29/37] feat: Storybook coverage was expanded for Material 3
 patterns

---
 m3-react/storybook/components/M3Card.mdx      |  1 +
 .../storybook/components/M3Card.stories.tsx   | 24 +++++++
 m3-react/storybook/components/M3FabButton.mdx |  2 +
 .../components/M3FabButton.stories.tsx        | 58 ++++++++++++++++
 .../storybook/components/M3Navigation.mdx     |  1 +
 .../components/M3Navigation.stories.tsx       | 40 +++++++++++
 m3-react/storybook/components/M3Select.mdx    |  3 +
 .../storybook/components/M3Select.stories.tsx | 16 +++++
 m3-react/storybook/components/M3Slider.mdx    |  3 +
 .../storybook/components/M3Slider.stories.tsx | 18 +++++
 m3-vue/storybook/components/M3Card.mdx        |  1 +
 m3-vue/storybook/components/M3Card.stories.ts | 36 ++++++++++
 m3-vue/storybook/components/M3FabButton.mdx   |  2 +
 .../components/M3FabButton.stories.ts         | 69 +++++++++++++++++++
 m3-vue/storybook/components/M3Navigation.mdx  |  1 +
 .../components/M3Navigation.stories.ts        | 57 +++++++++++++++
 m3-vue/storybook/components/M3Select.mdx      |  3 +
 .../storybook/components/M3Select.stories.ts  | 16 +++++
 m3-vue/storybook/components/M3Slider.mdx      |  3 +
 .../storybook/components/M3Slider.stories.ts  | 18 +++++
 20 files changed, 372 insertions(+)

diff --git a/m3-react/storybook/components/M3Card.mdx b/m3-react/storybook/components/M3Card.mdx
index da3c4fb..91a0ac1 100644
--- a/m3-react/storybook/components/M3Card.mdx
+++ b/m3-react/storybook/components/M3Card.mdx
@@ -45,6 +45,7 @@ Material 3 cards rely on tone and outline treatment to signal emphasis. This imp
 - [Landscape](?path=/story/components-m3card--landscape)
 - [Landscape Without Media](?path=/story/components-m3card--landscape-without-media)
 - [Portrait](?path=/story/components-m3card--portrait)
+- [Appearance Matrix](?path=/story/components-m3card--appearance-matrix)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Card.stories.tsx b/m3-react/storybook/components/M3Card.stories.tsx
index c6512a8..06258ea 100644
--- a/m3-react/storybook/components/M3Card.stories.tsx
+++ b/m3-react/storybook/components/M3Card.stories.tsx
@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import type { CSSProperties } from 'react'
 
 import { M3Button } from '@/components/button'
 import { M3Card } from '@/components/card'
@@ -92,3 +93,26 @@ export const Portrait: Story = {
     </M3Card>
   ),
 }
+
+export const AppearanceMatrix: Story = {
+  render: () => {
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+      alignItems: 'flex-start',
+    } satisfies CSSProperties
+
+    return (
+      <div style={row}>
+        {(['filled', 'elevated', 'outlined'] as const).map(appearance => (
+          <M3Card key={appearance} appearance={appearance} style={{ width: '220px' }}>
+            <M3Card.Heading>{appearance}</M3Card.Heading>
+            <M3Card.Subheading>Card emphasis</M3Card.Subheading>
+            Supporting text for the current card style.
+          </M3Card>
+        ))}
+      </div>
+    )
+  },
+}
diff --git a/m3-react/storybook/components/M3FabButton.mdx b/m3-react/storybook/components/M3FabButton.mdx
index 720d5a2..a32b673 100644
--- a/m3-react/storybook/components/M3FabButton.mdx
+++ b/m3-react/storybook/components/M3FabButton.mdx
@@ -59,6 +59,8 @@ This implementation exposes Material 3 tonal variants such as `surface`, `primar
 
 - [Standard](?path=/story/components-m3fabbutton--standard)
 - [Extended](?path=/story/components-m3fabbutton--extended)
+- [Variant Matrix](?path=/story/components-m3fabbutton--variant-matrix)
+- [Size Matrix](?path=/story/components-m3fabbutton--size-matrix)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3FabButton.stories.tsx b/m3-react/storybook/components/M3FabButton.stories.tsx
index 8b03fe6..4f51980 100644
--- a/m3-react/storybook/components/M3FabButton.stories.tsx
+++ b/m3-react/storybook/components/M3FabButton.stories.tsx
@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import type { CSSProperties } from 'react'
 
 import React from 'react'
 
@@ -58,3 +59,60 @@ export const Extended: Story = {
     </M3FabButton>
   ),
 }
+
+export const VariantMatrix: Story = {
+  render: () => {
+    const stack = {
+      display: 'grid',
+      gap: '16px',
+    } satisfies CSSProperties
+
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+      alignItems: 'center',
+    } satisfies CSSProperties
+
+    return (
+      <div style={stack}>
+        <div style={row}>
+          {values.variants.map(variant => (
+            <M3FabButton key={variant} variant={variant} aria-label={variant}>
+              <M3Icon name="edit" />
+            </M3FabButton>
+          ))}
+        </div>
+
+        <div style={row}>
+          {values.variants.map(variant => (
+            <M3FabButton key={variant} variant={variant}>
+              <M3Icon name="edit" /> New task
+            </M3FabButton>
+          ))}
+        </div>
+      </div>
+    )
+  },
+}
+
+export const SizeMatrix: Story = {
+  render: () => {
+    const row = {
+      display: 'flex',
+      flexWrap: 'wrap',
+      gap: '16px',
+      alignItems: 'center',
+    } satisfies CSSProperties
+
+    return (
+      <div style={row}>
+        {values.sizes.map(size => (
+          <M3FabButton key={size} size={size} aria-label={size}>
+            <M3Icon name="edit" />
+          </M3FabButton>
+        ))}
+      </div>
+    )
+  },
+}
diff --git a/m3-react/storybook/components/M3Navigation.mdx b/m3-react/storybook/components/M3Navigation.mdx
index b1676f4..8fcf4fb 100644
--- a/m3-react/storybook/components/M3Navigation.mdx
+++ b/m3-react/storybook/components/M3Navigation.mdx
@@ -31,6 +31,7 @@ The current stories focus on drawer and rail, which are the forms implemented in
 
 - [Navigation Drawer](?path=/story/components-m3navigation--navigation-drawer)
 - [Navigation Rail](?path=/story/components-m3navigation--navigation-rail)
+- [Modal Navigation Drawer](?path=/story/components-m3navigation--modal-navigation-drawer)
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Navigation.stories.tsx b/m3-react/storybook/components/M3Navigation.stories.tsx
index e79c2e3..e83aa50 100644
--- a/m3-react/storybook/components/M3Navigation.stories.tsx
+++ b/m3-react/storybook/components/M3Navigation.stories.tsx
@@ -112,3 +112,43 @@ export const NavigationRail: Story = {
     appearance: 'rail',
   },
 }
+
+export const ModalNavigationDrawer: Story = {
+  render: (args) => {
+    const [expanded, setExpanded] = useState(true)
+
+    return (
+      <M3Navigation
+        expanded={expanded}
+        onToggle={setExpanded}
+        {...args}
+      >
+        <M3Navigation.Top>
+          <M3IconButton aria-label="Close menu" onClick={() => setExpanded(false)}>
+            <M3Icon name="menu" />
+          </M3IconButton>
+        </M3Navigation.Top>
+
+        <M3Navigation.Header>
+          Mail
+        </M3Navigation.Header>
+
+        <M3NavigationTab label="Inbox" active>
+          <M3Icon name="inbox" />
+        </M3NavigationTab>
+
+        <M3NavigationTab label="Drafts">
+          <M3Icon name="mail" />
+        </M3NavigationTab>
+
+        <M3NavigationTab label="Trash">
+          <M3Icon name="delete" />
+        </M3NavigationTab>
+      </M3Navigation>
+    )
+  },
+
+  args: {
+    appearance: 'drawer',
+  },
+}
diff --git a/m3-react/storybook/components/M3Select.mdx b/m3-react/storybook/components/M3Select.mdx
index 363958c..099f682 100644
--- a/m3-react/storybook/components/M3Select.mdx
+++ b/m3-react/storybook/components/M3Select.mdx
@@ -35,11 +35,14 @@ The `WithIcons` story demonstrates a useful Material 3 pattern for country, acco
 
 - [Standard](?path=/story/components-m3select--standard)
 - [With Icons](?path=/story/components-m3select--with-icons)
+- [Outlined](?path=/story/components-m3select--outlined)
+- [Invalid](?path=/story/components-m3select--invalid)
 
 ## Demo
 
 <Canvas of={M3SelectStories.Standard} />
 <Canvas of={M3SelectStories.WithIcons} />
+<Canvas of={M3SelectStories.Outlined} />
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Select.stories.tsx b/m3-react/storybook/components/M3Select.stories.tsx
index 0bf4e5a..cab4f2d 100644
--- a/m3-react/storybook/components/M3Select.stories.tsx
+++ b/m3-react/storybook/components/M3Select.stories.tsx
@@ -124,3 +124,19 @@ export const WithIcons: Story = {
 
   render: (args) => <M3SelectWithIconsStory {...args} />,
 }
+
+export const Outlined: Story = {
+  args: {
+    label: 'Choose',
+    outlined: true,
+    placeholder: 'Select an option',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    label: 'Choose',
+    invalid: true,
+    placeholder: 'Required',
+  },
+}
diff --git a/m3-react/storybook/components/M3Slider.mdx b/m3-react/storybook/components/M3Slider.mdx
index 4cd1d3f..c27674c 100644
--- a/m3-react/storybook/components/M3Slider.mdx
+++ b/m3-react/storybook/components/M3Slider.mdx
@@ -32,11 +32,14 @@ Range sliders work best when both handles affect the same conceptual value space
 
 - [Single](?path=/story/components-m3slider--single)
 - [Range](?path=/story/components-m3slider--range)
+- [Discrete Single](?path=/story/components-m3slider--discrete-single)
+- [Disabled Range](?path=/story/components-m3slider--disabled-range)
 
 ## Demo
 
 <Canvas of={M3SliderStories.Single} />
 <Canvas of={M3SliderStories.Range} />
+<Canvas of={M3SliderStories.DiscreteSingle} />
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Slider.stories.tsx b/m3-react/storybook/components/M3Slider.stories.tsx
index 815694d..cd6c57f 100644
--- a/m3-react/storybook/components/M3Slider.stories.tsx
+++ b/m3-react/storybook/components/M3Slider.stories.tsx
@@ -79,3 +79,21 @@ export const Range: Story = {
     type: 'range',
   },
 }
+
+export const DiscreteSingle: Story = {
+  args: {
+    type: 'single',
+    step: 10,
+    ariaHandle: {
+      label: 'Volume',
+    },
+    ariaHandleMax: {},
+  },
+}
+
+export const DisabledRange: Story = {
+  args: {
+    type: 'range',
+    disabled: true,
+  },
+}
diff --git a/m3-vue/storybook/components/M3Card.mdx b/m3-vue/storybook/components/M3Card.mdx
index 3d656f0..9cc6882 100644
--- a/m3-vue/storybook/components/M3Card.mdx
+++ b/m3-vue/storybook/components/M3Card.mdx
@@ -49,6 +49,7 @@ Material 3 cards rely on tone and outline treatment to signal emphasis. This imp
 - [Landscape](?path=/story/components-m3card--landscape)
 - [Landscape Without Media](?path=/story/components-m3card--landscape-without-media)
 - [Portrait](?path=/story/components-m3card--portrait)
+- [Appearance Matrix](?path=/story/components-m3card--appearance-matrix)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Card.stories.ts b/m3-vue/storybook/components/M3Card.stories.ts
index f6c009b..7084269 100644
--- a/m3-vue/storybook/components/M3Card.stories.ts
+++ b/m3-vue/storybook/components/M3Card.stories.ts
@@ -132,3 +132,39 @@ export const Portrait: Story = {
     `,
   }),
 }
+
+export const AppearanceMatrix: Story = {
+  // eslint-disable-next-line max-lines-per-function
+  render: () => ({
+    components: {
+      M3Card,
+    },
+
+    setup () {
+      return {
+        appearances: ['filled', 'elevated', 'outlined'],
+      }
+    },
+
+    template: `
+        <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start;">
+            <M3Card
+                v-for="appearance in appearances"
+                :key="appearance"
+                :appearance="appearance"
+                style="width: 220px;"
+            >
+                <template #heading>
+                    {{ appearance }}
+                </template>
+
+                <template #subheading>
+                    Card emphasis
+                </template>
+
+                Supporting text for the current card style.
+            </M3Card>
+        </div>
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/components/M3FabButton.mdx b/m3-vue/storybook/components/M3FabButton.mdx
index e735ca0..4a04a5a 100644
--- a/m3-vue/storybook/components/M3FabButton.mdx
+++ b/m3-vue/storybook/components/M3FabButton.mdx
@@ -54,6 +54,8 @@ This implementation exposes Material 3 tonal variants such as `surface`, `primar
 
 - [Standard](?path=/story/components-m3fabbutton--standard)
 - [Extended](?path=/story/components-m3fabbutton--extended)
+- [Variant Matrix](?path=/story/components-m3fabbutton--variant-matrix)
+- [Size Matrix](?path=/story/components-m3fabbutton--size-matrix)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3FabButton.stories.ts b/m3-vue/storybook/components/M3FabButton.stories.ts
index 4e89fc7..6e22250 100644
--- a/m3-vue/storybook/components/M3FabButton.stories.ts
+++ b/m3-vue/storybook/components/M3FabButton.stories.ts
@@ -81,3 +81,72 @@ export const Extended: Story = {
     `,
   }),
 }
+
+export const VariantMatrix: Story = {
+  // eslint-disable-next-line max-lines-per-function
+  render: () => ({
+    components: {
+      M3FabButton,
+      M3Icon,
+    },
+
+    setup () {
+      return {
+        variants,
+      }
+    },
+
+    template: `
+        <div style="display: grid; gap: 16px;">
+            <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+                <M3FabButton
+                    v-for="variant in variants"
+                    :key="'icon-' + variant"
+                    :variant="variant"
+                    :aria-label="variant"
+                >
+                    <M3Icon name="edit" />
+                </M3FabButton>
+            </div>
+
+            <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+                <M3FabButton
+                    v-for="variant in variants"
+                    :key="'text-' + variant"
+                    :variant="variant"
+                >
+                    <M3Icon name="edit" /> New task
+                </M3FabButton>
+            </div>
+        </div>
+    `,
+  }),
+}
+
+export const SizeMatrix: Story = {
+  render: () => ({
+    components: {
+      M3FabButton,
+      M3Icon,
+    },
+
+    setup () {
+      return {
+        sizes,
+      }
+    },
+
+    template: `
+        <div style="display: flex; flex-wrap: wrap; gap: 16px; align-items: center;">
+            <M3FabButton
+                v-for="size in sizes"
+                :key="size"
+                :size="size"
+                :aria-label="size"
+            >
+                <M3Icon name="edit" />
+            </M3FabButton>
+        </div>
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/components/M3Navigation.mdx b/m3-vue/storybook/components/M3Navigation.mdx
index b1676f4..8fcf4fb 100644
--- a/m3-vue/storybook/components/M3Navigation.mdx
+++ b/m3-vue/storybook/components/M3Navigation.mdx
@@ -31,6 +31,7 @@ The current stories focus on drawer and rail, which are the forms implemented in
 
 - [Navigation Drawer](?path=/story/components-m3navigation--navigation-drawer)
 - [Navigation Rail](?path=/story/components-m3navigation--navigation-rail)
+- [Modal Navigation Drawer](?path=/story/components-m3navigation--modal-navigation-drawer)
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Navigation.stories.ts b/m3-vue/storybook/components/M3Navigation.stories.ts
index ca1419f..28b5779 100644
--- a/m3-vue/storybook/components/M3Navigation.stories.ts
+++ b/m3-vue/storybook/components/M3Navigation.stories.ts
@@ -135,3 +135,60 @@ export const NavigationRail: Story = {
     appearance: 'rail',
   },
 }
+
+export const ModalNavigationDrawer: Story = {
+  // eslint-disable-next-line max-lines-per-function
+  render: (args: unknown) => ({
+    name: 'M3ModalNavigationDrawerStory',
+
+    components: {
+      M3Icon,
+      M3IconButton,
+      M3Navigation,
+      M3NavigationTab,
+    },
+
+    setup () {
+      return {
+        args,
+        expanded: ref(true),
+      }
+    },
+
+    template: `
+        <M3Navigation
+            v-model:expanded="expanded"
+            v-bind="args"
+        >
+            <template #top>
+                <M3IconButton
+                    aria-label="Close menu"
+                    @click="expanded = false"
+                >
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <template #header>
+                Mail
+            </template>
+
+            <M3NavigationTab label="Inbox" active>
+                <M3Icon name="inbox" />
+            </M3NavigationTab>
+
+            <M3NavigationTab label="Drafts">
+                <M3Icon name="mail" />
+            </M3NavigationTab>
+
+            <M3NavigationTab label="Trash">
+                <M3Icon name="delete" />
+            </M3NavigationTab>
+        </M3Navigation>
+    `,
+  }),
+
+  args: {
+    appearance: 'drawer',
+  },
+}
diff --git a/m3-vue/storybook/components/M3Select.mdx b/m3-vue/storybook/components/M3Select.mdx
index ce604b9..6506185 100644
--- a/m3-vue/storybook/components/M3Select.mdx
+++ b/m3-vue/storybook/components/M3Select.mdx
@@ -35,11 +35,14 @@ The `WithIcons` story demonstrates a useful Material 3 pattern for country, acco
 
 - [Standard](?path=/story/components-m3select--standard)
 - [With Icons](?path=/story/components-m3select--with-icons)
+- [Outlined](?path=/story/components-m3select--outlined)
+- [Invalid](?path=/story/components-m3select--invalid)
 
 ## Demo
 
 <Canvas of={M3SelectStories.Standard} />
 <Canvas of={M3SelectStories.WithIcons} />
+<Canvas of={M3SelectStories.Outlined} />
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Select.stories.ts b/m3-vue/storybook/components/M3Select.stories.ts
index f5288a5..0593983 100644
--- a/m3-vue/storybook/components/M3Select.stories.ts
+++ b/m3-vue/storybook/components/M3Select.stories.ts
@@ -130,3 +130,19 @@ export const WithIcons: Story = {
     `,
   }),
 }
+
+export const Outlined: Story = {
+  args: {
+    label: 'Choose',
+    outlined: true,
+    placeholder: 'Select an option',
+  },
+}
+
+export const Invalid: Story = {
+  args: {
+    label: 'Choose',
+    invalid: true,
+    placeholder: 'Required',
+  },
+}
diff --git a/m3-vue/storybook/components/M3Slider.mdx b/m3-vue/storybook/components/M3Slider.mdx
index 4cd1d3f..c27674c 100644
--- a/m3-vue/storybook/components/M3Slider.mdx
+++ b/m3-vue/storybook/components/M3Slider.mdx
@@ -32,11 +32,14 @@ Range sliders work best when both handles affect the same conceptual value space
 
 - [Single](?path=/story/components-m3slider--single)
 - [Range](?path=/story/components-m3slider--range)
+- [Discrete Single](?path=/story/components-m3slider--discrete-single)
+- [Disabled Range](?path=/story/components-m3slider--disabled-range)
 
 ## Demo
 
 <Canvas of={M3SliderStories.Single} />
 <Canvas of={M3SliderStories.Range} />
+<Canvas of={M3SliderStories.DiscreteSingle} />
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Slider.stories.ts b/m3-vue/storybook/components/M3Slider.stories.ts
index 29aacd0..d3eecd6 100644
--- a/m3-vue/storybook/components/M3Slider.stories.ts
+++ b/m3-vue/storybook/components/M3Slider.stories.ts
@@ -82,3 +82,21 @@ export const Range: Story = {
     type: 'range',
   },
 }
+
+export const DiscreteSingle: Story = {
+  args: {
+    type: 'single',
+    step: 10,
+    ariaHandle: {
+      label: 'Volume',
+    },
+    ariaHandleMax: {},
+  },
+}
+
+export const DisabledRange: Story = {
+  args: {
+    type: 'range',
+    disabled: true,
+  },
+}

From b63e7eecf6411c265d9354625060cfb4b85bad5d Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 18:35:33 +0400
Subject: [PATCH 30/37] feat: Storybook scenarios were added for tooltips and
 surfaces

---
 .../storybook/components/M3RichTooltip.mdx    |  21 +-
 .../components/M3RichTooltip.stories.tsx      |  33 ++++
 m3-react/storybook/components/M3Surface.mdx   |   4 +
 .../components/M3Surface.stories.tsx          |  10 +
 .../rich-tooltip/SelectionTooltip.tsx         |  42 ++++
 .../examples/rich-tooltip/ShortcutTooltip.tsx |  31 +++
 .../surface/SurfaceInspectorSheet.tsx         | 143 ++++++++++++++
 .../surface/SurfaceWorkspaceDialog.tsx        | 118 +++++++++++
 m3-vue/storybook/components/M3RichTooltip.mdx |  25 +--
 .../components/M3RichTooltip.stories.ts       |  51 +++++
 m3-vue/storybook/components/M3Surface.mdx     |   4 +
 .../storybook/components/M3Surface.stories.ts |  26 +++
 .../rich-tooltip/SelectionTooltip.vue         |  36 ++++
 .../examples/rich-tooltip/ShortcutTooltip.vue |  25 +++
 .../surface/SurfaceInspectorSheet.vue         | 185 ++++++++++++++++++
 .../surface/SurfaceWorkspaceDialog.vue        | 182 +++++++++++++++++
 16 files changed, 918 insertions(+), 18 deletions(-)
 create mode 100644 m3-react/storybook/components/M3RichTooltip.stories.tsx
 create mode 100644 m3-react/storybook/examples/rich-tooltip/SelectionTooltip.tsx
 create mode 100644 m3-react/storybook/examples/rich-tooltip/ShortcutTooltip.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
 create mode 100644 m3-react/storybook/examples/surface/SurfaceWorkspaceDialog.tsx
 create mode 100644 m3-vue/storybook/components/M3RichTooltip.stories.ts
 create mode 100644 m3-vue/storybook/examples/rich-tooltip/SelectionTooltip.vue
 create mode 100644 m3-vue/storybook/examples/rich-tooltip/ShortcutTooltip.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceWorkspaceDialog.vue

diff --git a/m3-react/storybook/components/M3RichTooltip.mdx b/m3-react/storybook/components/M3RichTooltip.mdx
index 2726e54..ea26489 100644
--- a/m3-react/storybook/components/M3RichTooltip.mdx
+++ b/m3-react/storybook/components/M3RichTooltip.mdx
@@ -1,6 +1,7 @@
-import { Unstyled } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3RichTooltipStories from './M3RichTooltip.stories'
 
-import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip'
+<Meta of={M3RichTooltipStories} />
 
 # Rich tooltip
 
@@ -30,11 +31,17 @@ The tooltip should remain attached to its trigger context and disappear when the
 - Keep tooltip text concise and task-relevant.
 - Avoid using tooltips as the only way to convey critical information.
 
-<Unstyled>
-  <div className="m3-panel m3-panel_elevated-1 my-4" style={{ maxWidth: '360px' }}>
-    <DeleteTooltip />
-  </div>
-</Unstyled>
+## Story guide
+
+- [Destructive Action](?path=/story/components-m3richtooltip--destructive-action)
+- [Bulk Selection](?path=/story/components-m3richtooltip--bulk-selection)
+- [Shortcut Hint](?path=/story/components-m3richtooltip--shortcut-hint)
+
+## Demo
+
+<Canvas of={M3RichTooltipStories.DestructiveAction} />
+<Canvas of={M3RichTooltipStories.BulkSelection} />
+<Canvas of={M3RichTooltipStories.ShortcutHint} />
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3RichTooltip.stories.tsx b/m3-react/storybook/components/M3RichTooltip.stories.tsx
new file mode 100644
index 0000000..d06d98a
--- /dev/null
+++ b/m3-react/storybook/components/M3RichTooltip.stories.tsx
@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip'
+import SelectionTooltip from '../examples/rich-tooltip/SelectionTooltip'
+import ShortcutTooltip from '../examples/rich-tooltip/ShortcutTooltip'
+
+const meta = {
+  title: 'Components/M3RichTooltip',
+
+  component: M3RichTooltip,
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3RichTooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const DestructiveAction: Story = {
+  render: () => <DeleteTooltip />,
+}
+
+export const BulkSelection: Story = {
+  render: () => <SelectionTooltip />,
+}
+
+export const ShortcutHint: Story = {
+  render: () => <ShortcutTooltip />,
+}
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
index ec1e5ca..b60e584 100644
--- a/m3-react/storybook/components/M3Surface.mdx
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -48,6 +48,10 @@ The component does not prescribe content anatomy. Dialogs, side sheets, and cust
   Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
   Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+- [Workspace Modal Dialog](?path=/story/components-m3surface--workspace-modal-dialog)
+  Shows a centered blocking decision surface in a realistic workspace scene without morph choreography.
+- [Inspector Side Sheet](?path=/story/components-m3surface--inspector-side-sheet)
+  Demonstrates a practical supporting-edit sheet anchored to the edge of a dashboard.
 
 ## Usage guidance
 
diff --git a/m3-react/storybook/components/M3Surface.stories.tsx b/m3-react/storybook/components/M3Surface.stories.tsx
index 440ac1a..af3c876 100644
--- a/m3-react/storybook/components/M3Surface.stories.tsx
+++ b/m3-react/storybook/components/M3Surface.stories.tsx
@@ -6,11 +6,13 @@ import type {
 import { M3Surface } from '@/components/surface'
 
 import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph'
+import SurfaceInspectorSheet from '../examples/surface/SurfaceInspectorSheet'
 import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain'
 import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal'
 import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove'
 import SurfaceSideSheetModalToWindow from '../examples/surface/SurfaceSideSheetModalToWindow'
 import SurfaceSideSheetMorph from '../examples/surface/SurfaceSideSheetMorph'
+import SurfaceWorkspaceDialog from '../examples/surface/SurfaceWorkspaceDialog'
 
 import '../examples/surface/styles.scss'
 
@@ -50,3 +52,11 @@ export const SideSheetModalToWindow: Story = {
 export const NestedDialogsChain: Story = {
   render: () => <SurfaceNestedDialogsChain />,
 }
+
+export const WorkspaceModalDialog: Story = {
+  render: () => <SurfaceWorkspaceDialog />,
+}
+
+export const InspectorSideSheet: Story = {
+  render: () => <SurfaceInspectorSheet />,
+}
diff --git a/m3-react/storybook/examples/rich-tooltip/SelectionTooltip.tsx b/m3-react/storybook/examples/rich-tooltip/SelectionTooltip.tsx
new file mode 100644
index 0000000..eff4ba7
--- /dev/null
+++ b/m3-react/storybook/examples/rich-tooltip/SelectionTooltip.tsx
@@ -0,0 +1,42 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { useM3PopperCloserEffect } from '@/components/popper'
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import { useState } from 'react'
+
+const SelectionTooltip: FC = () => {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+  const tooltipId = 'selection-tooltip-description'
+
+  return (
+    <>
+      <span ref={setTarget} style={{ display: 'inline-block' }}>
+        <M3Button aria-describedby={tooltipId}>
+          Review selection
+        </M3Button>
+      </span>
+
+      <M3RichTooltip id={tooltipId} target={target} hideOnMissClick={true}>
+        <M3RichTooltip.Heading>
+          3 items selected
+        </M3RichTooltip.Heading>
+
+        Continue with a bulk action or refine the selection before applying changes.
+
+        <M3RichTooltip.Footer>
+          <M3Button appearance="text" effects={[useM3PopperCloserEffect()]}>
+            Keep editing
+          </M3Button>
+
+          <M3Button appearance="text" effects={[useM3PopperCloserEffect()]}>
+            Apply labels
+          </M3Button>
+        </M3RichTooltip.Footer>
+      </M3RichTooltip>
+    </>
+  )
+}
+
+export default SelectionTooltip
diff --git a/m3-react/storybook/examples/rich-tooltip/ShortcutTooltip.tsx b/m3-react/storybook/examples/rich-tooltip/ShortcutTooltip.tsx
new file mode 100644
index 0000000..d4bc825
--- /dev/null
+++ b/m3-react/storybook/examples/rich-tooltip/ShortcutTooltip.tsx
@@ -0,0 +1,31 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import { useState } from 'react'
+
+const ShortcutTooltip: FC = () => {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+  const tooltipId = 'shortcut-tooltip-description'
+
+  return (
+    <>
+      <span ref={setTarget} style={{ display: 'inline-block' }}>
+        <M3Button appearance="text" aria-describedby={tooltipId}>
+          Keyboard shortcut
+        </M3Button>
+      </span>
+
+      <M3RichTooltip id={tooltipId} target={target} hideOnMissClick={true}>
+        <M3RichTooltip.Heading>
+          Jump to inbox
+        </M3RichTooltip.Heading>
+
+        Press <strong>G</strong>, then <strong>I</strong> to open the inbox from anywhere in the workspace.
+      </M3RichTooltip>
+    </>
+  )
+}
+
+export default ShortcutTooltip
diff --git a/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx b/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
new file mode 100644
index 0000000..9b5fad8
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
@@ -0,0 +1,143 @@
+import type {
+  CSSProperties,
+  FC,
+} from 'react'
+import type { M3SelectOption } from '@/components/select'
+
+import { M3Button } from '@/components/button'
+import { M3Select } from '@/components/select'
+import { M3Surface, M3SurfacePanel } from '@/components/surface'
+import { M3TextField } from '@/components/text-field'
+
+import { useState } from 'react'
+
+type Priority = 'low' | 'normal' | 'high'
+
+const priorityOptions: Array<M3SelectOption<Priority>> = [{
+  label: 'Low',
+  value: 'low',
+}, {
+  label: 'Normal',
+  value: 'normal',
+}, {
+  label: 'High',
+  value: 'high',
+}]
+
+const panelStyle = {
+  padding: '18px',
+} satisfies CSSProperties
+
+const SurfaceInspectorSheet: FC = () => {
+  const [opened, setOpened] = useState(false)
+  const [owner, setOwner] = useState('owner@example.com')
+  const [priority, setPriority] = useState<Priority | null>('normal')
+  const [notes, setNotes] = useState('Coordinate the release notes and schedule rollout approval.')
+
+  return (
+    <div style={{
+      minHeight: '100vh',
+      background: 'linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%)',
+      color: 'var(--m3-sys-on-surface)',
+      padding: '24px',
+      boxSizing: 'border-box',
+    }}
+    >
+      <M3SurfacePanel
+        fillHeight={false}
+        height={84}
+        rounding={24}
+        variant="surface-container"
+        elevation={0}
+        style={{ ...panelStyle, display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
+      >
+        <div>
+          <strong style={{ display: 'block', marginBottom: '6px' }}>Scenario: inspector side sheet</strong>
+          <span style={{ fontSize: '13px', opacity: 0.82 }}>A supplemental editing surface appears from the edge while the main dashboard stays visible.</span>
+        </div>
+
+        <M3Button appearance="tonal" onClick={() => setOpened(true)}>
+          Open inspector
+        </M3Button>
+      </M3SurfacePanel>
+
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, minmax(0, 1fr))', gap: '16px', marginTop: '16px' }}>
+        {['Launch plan', 'Dependencies', 'Approvals'].map(label => (
+          <M3SurfacePanel
+            key={label}
+            fillHeight={false}
+            height={188}
+            rounding={18}
+            variant="surface-container-low"
+            elevation={1}
+            style={panelStyle}
+          >
+            <h3 style={{ margin: '0 0 8px' }}>{label}</h3>
+            <p style={{ margin: 0 }}>Dashboard content keeps its place while the inspector surface is layered above it.</p>
+          </M3SurfacePanel>
+        ))}
+      </div>
+
+      <M3Surface
+        mode="modal"
+        shown={opened}
+        anchor="end"
+        fillWidth={false}
+        width={360}
+        insetTop={0}
+        insetRight={0}
+        insetBottom={0}
+        roundingTopLeft={28}
+        roundingBottomLeft={28}
+        roundingTopRight={0}
+        roundingBottomRight={0}
+        elevation={2}
+        variant="surface-container-high"
+        overflow="auto"
+        onToggle={setOpened}
+        onDismiss={() => setOpened(false)}
+        style={{ padding: '20px' }}
+      >
+        <h3 style={{ margin: '0 0 12px' }}>Release inspector</h3>
+        <p style={{ margin: '0 0 16px' }}>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
+
+        <div style={{ display: 'grid', gap: '12px' }}>
+          <M3TextField
+            value={owner}
+            label="Owner email"
+            outlined={true}
+            onUpdate={setOwner}
+          />
+
+          <M3Select<Priority>
+            value={priority}
+            label="Priority"
+            options={priorityOptions}
+            outlined={true}
+            onUpdate={setPriority}
+          />
+
+          <M3TextField
+            value={notes}
+            label="Notes"
+            outlined={true}
+            multiline={true}
+            onUpdate={setNotes}
+          />
+        </div>
+
+        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '12px', marginTop: '16px' }}>
+          <M3Button appearance="text" onClick={() => setOpened(false)}>
+            Dismiss
+          </M3Button>
+
+          <M3Button appearance="filled" onClick={() => setOpened(false)}>
+            Save changes
+          </M3Button>
+        </div>
+      </M3Surface>
+    </div>
+  )
+}
+
+export default SurfaceInspectorSheet
diff --git a/m3-react/storybook/examples/surface/SurfaceWorkspaceDialog.tsx b/m3-react/storybook/examples/surface/SurfaceWorkspaceDialog.tsx
new file mode 100644
index 0000000..affec30
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceWorkspaceDialog.tsx
@@ -0,0 +1,118 @@
+import type {
+  CSSProperties,
+  FC,
+} from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Surface, M3SurfacePanel } from '@/components/surface'
+
+import { useState } from 'react'
+
+const panelStyle = {
+  padding: '18px',
+} satisfies CSSProperties
+
+const SurfaceWorkspaceDialog: FC = () => {
+  const [opened, setOpened] = useState(false)
+
+  return (
+    <div style={{
+      minHeight: '100vh',
+      background: 'linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%)',
+      color: 'var(--m3-sys-on-surface)',
+      padding: '24px',
+      boxSizing: 'border-box',
+    }}
+    >
+      <M3SurfacePanel
+        fillHeight={false}
+        height={84}
+        rounding={24}
+        variant="surface-container"
+        elevation={0}
+        style={{ ...panelStyle, display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
+      >
+        <div>
+          <strong style={{ display: 'block', marginBottom: '6px' }}>Scenario: workspace confirmation dialog</strong>
+          <span style={{ fontSize: '13px', opacity: 0.82 }}>A blocking decision interrupts the current workspace without replacing the layout beneath it.</span>
+        </div>
+
+        <M3Button onClick={() => setOpened(true)}>
+          Archive project
+        </M3Button>
+      </M3SurfacePanel>
+
+      <div style={{ display: 'grid', gridTemplateColumns: '2fr 1fr', gap: '16px', marginTop: '16px' }}>
+        <M3SurfacePanel rounding={20} variant="surface-container-lowest" elevation={0} style={panelStyle}>
+          <h3 style={{ margin: '0 0 8px' }}>Workspace overview</h3>
+          <p style={{ margin: 0 }}>Main content remains visible under the dialog, so the user keeps the surrounding context while confirming the action.</p>
+        </M3SurfacePanel>
+
+        <M3SurfacePanel rounding={20} variant="surface-container-low" elevation={1} style={panelStyle}>
+          <h3 style={{ margin: '0 0 8px' }}>Activity</h3>
+          <p style={{ margin: 0 }}>12 tasks updated today</p>
+        </M3SurfacePanel>
+      </div>
+
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, minmax(0, 1fr))', gap: '16px', marginTop: '16px' }}>
+        {['Roadmap', 'Assets', 'Owners'].map(label => (
+          <M3SurfacePanel
+            key={label}
+            fillHeight={false}
+            height={180}
+            rounding={18}
+            variant="surface-container-low"
+            elevation={1}
+            style={panelStyle}
+          >
+            <h3 style={{ margin: '0 0 8px' }}>{label}</h3>
+            <p style={{ margin: 0 }}>Supporting surface inside the same workspace scene.</p>
+          </M3SurfacePanel>
+        ))}
+      </div>
+
+      <M3Surface
+        mode="modal"
+        shown={opened}
+        anchor="center"
+        fillWidth={false}
+        fillHeight={false}
+        width={520}
+        insetTop={24}
+        insetBottom={24}
+        rounding={28}
+        elevation={3}
+        variant="surface-container-high"
+        onToggle={setOpened}
+        onDismiss={() => setOpened(false)}
+        style={{ padding: '24px' }}
+      >
+        <h3 style={{ margin: '0 0 12px' }}>Archive this workspace?</h3>
+        <p style={{ margin: '0 0 12px' }}>Archiving hides the project from active planning views but keeps its history available for reporting.</p>
+
+        <M3SurfacePanel
+          fillHeight={false}
+          height={92}
+          rounding={18}
+          variant="surface-container"
+          elevation={0}
+          style={{ ...panelStyle, marginBottom: '16px' }}
+        >
+          Team members will retain read access until the workspace is restored.
+        </M3SurfacePanel>
+
+        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '12px' }}>
+          <M3Button appearance="text" onClick={() => setOpened(false)}>
+            Cancel
+          </M3Button>
+
+          <M3Button appearance="filled" onClick={() => setOpened(false)}>
+            Archive
+          </M3Button>
+        </div>
+      </M3Surface>
+    </div>
+  )
+}
+
+export default SurfaceWorkspaceDialog
diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index 13f16e6..ea26489 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -1,7 +1,7 @@
-import { Unstyled } from '@storybook/addon-docs/blocks'
+import { Canvas, Meta } from '@storybook/addon-docs/blocks'
+import * as M3RichTooltipStories from './M3RichTooltip.stories'
 
-import Inline from './Inline'
-import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip.vue'
+<Meta of={M3RichTooltipStories} />
 
 # Rich tooltip
 
@@ -31,14 +31,17 @@ The tooltip should remain attached to its trigger context and disappear when the
 - Keep tooltip text concise and task-relevant.
 - Avoid using tooltips as the only way to convey critical information.
 
-<Unstyled>
-  <div
-    className="m3-surface m3-surface_container m3-surface_elevation-0 my-4"
-    style={{ maxWidth: '360px', padding: '32px', borderRadius: '16px', color: 'var(--m3-sys-on-surface)' }}
-  >
-    <Inline is={DeleteTooltip} />
-  </div>
-</Unstyled>
+## Story guide
+
+- [Destructive Action](?path=/story/components-m3richtooltip--destructive-action)
+- [Bulk Selection](?path=/story/components-m3richtooltip--bulk-selection)
+- [Shortcut Hint](?path=/story/components-m3richtooltip--shortcut-hint)
+
+## Demo
+
+<Canvas of={M3RichTooltipStories.DestructiveAction} />
+<Canvas of={M3RichTooltipStories.BulkSelection} />
+<Canvas of={M3RichTooltipStories.ShortcutHint} />
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3RichTooltip.stories.ts b/m3-vue/storybook/components/M3RichTooltip.stories.ts
new file mode 100644
index 0000000..abc1d1c
--- /dev/null
+++ b/m3-vue/storybook/components/M3RichTooltip.stories.ts
@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import DeleteTooltip from '../examples/rich-tooltip/DeleteTooltip.vue'
+import SelectionTooltip from '../examples/rich-tooltip/SelectionTooltip.vue'
+import ShortcutTooltip from '../examples/rich-tooltip/ShortcutTooltip.vue'
+
+const meta = {
+  title: 'Components/M3RichTooltip',
+
+  component: M3RichTooltip,
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3RichTooltip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const DestructiveAction: Story = {
+  render: () => ({
+    components: {
+      DeleteTooltip,
+    },
+
+    template: '<DeleteTooltip />',
+  }),
+}
+
+export const BulkSelection: Story = {
+  render: () => ({
+    components: {
+      SelectionTooltip,
+    },
+
+    template: '<SelectionTooltip />',
+  }),
+}
+
+export const ShortcutHint: Story = {
+  render: () => ({
+    components: {
+      ShortcutTooltip,
+    },
+
+    template: '<ShortcutTooltip />',
+  }),
+}
diff --git a/m3-vue/storybook/components/M3Surface.mdx b/m3-vue/storybook/components/M3Surface.mdx
index ec1e5ca..b60e584 100644
--- a/m3-vue/storybook/components/M3Surface.mdx
+++ b/m3-vue/storybook/components/M3Surface.mdx
@@ -48,6 +48,10 @@ The component does not prescribe content anatomy. Dialogs, side sheets, and cust
   Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
   Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+- [Workspace Modal Dialog](?path=/story/components-m3surface--workspace-modal-dialog)
+  Shows a centered blocking decision surface in a realistic workspace scene without morph choreography.
+- [Inspector Side Sheet](?path=/story/components-m3surface--inspector-side-sheet)
+  Demonstrates a practical supporting-edit sheet anchored to the edge of a dashboard.
 
 ## Usage guidance
 
diff --git a/m3-vue/storybook/components/M3Surface.stories.ts b/m3-vue/storybook/components/M3Surface.stories.ts
index 6757270..c33ae18 100644
--- a/m3-vue/storybook/components/M3Surface.stories.ts
+++ b/m3-vue/storybook/components/M3Surface.stories.ts
@@ -6,11 +6,13 @@ import type {
 import M3Surface from '@/components/surface/M3Surface.vue'
 
 import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph.vue'
+import SurfaceInspectorSheet from '../examples/surface/SurfaceInspectorSheet.vue'
 import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain.vue'
 import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal.vue'
 import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove.vue'
 import SurfaceSideSheetModalToWindow from '../examples/surface/SurfaceSideSheetModalToWindow.vue'
 import SurfaceSideSheetMorph from '../examples/surface/SurfaceSideSheetMorph.vue'
+import SurfaceWorkspaceDialog from '../examples/surface/SurfaceWorkspaceDialog.vue'
 
 const meta = {
   title: 'Components/M3Surface',
@@ -96,3 +98,27 @@ export const NestedDialogsChain: Story = {
     `,
   }),
 }
+
+export const WorkspaceModalDialog: Story = {
+  render: () => ({
+    components: {
+      SurfaceWorkspaceDialog,
+    },
+
+    template: `
+        <SurfaceWorkspaceDialog />
+    `,
+  }),
+}
+
+export const InspectorSideSheet: Story = {
+  render: () => ({
+    components: {
+      SurfaceInspectorSheet,
+    },
+
+    template: `
+        <SurfaceInspectorSheet />
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/examples/rich-tooltip/SelectionTooltip.vue b/m3-vue/storybook/examples/rich-tooltip/SelectionTooltip.vue
new file mode 100644
index 0000000..c6d8833
--- /dev/null
+++ b/m3-vue/storybook/examples/rich-tooltip/SelectionTooltip.vue
@@ -0,0 +1,36 @@
+<template>
+    <span ref="target" :style="{ display: 'inline-block' }">
+        <M3Button :aria-describedby="tooltipId">
+            Review selection
+        </M3Button>
+
+        <M3RichTooltip :id="tooltipId" :target="() => target" hide-on-miss-click>
+            <template #heading>
+                3 items selected
+            </template>
+
+            Continue with a bulk action or refine the selection before applying changes.
+
+            <template #footer>
+                <M3Button v-m3-popper-closer appearance="text">
+                    Keep editing
+                </M3Button>
+
+                <M3Button v-m3-popper-closer appearance="text">
+                    Apply labels
+                </M3Button>
+            </template>
+        </M3RichTooltip>
+    </span>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { vM3PopperCloser } from '@/components/popper'
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import { ref } from 'vue'
+
+const target = ref<HTMLElement | null>(null)
+const tooltipId = 'selection-tooltip-description'
+</script>
diff --git a/m3-vue/storybook/examples/rich-tooltip/ShortcutTooltip.vue b/m3-vue/storybook/examples/rich-tooltip/ShortcutTooltip.vue
new file mode 100644
index 0000000..ad368ec
--- /dev/null
+++ b/m3-vue/storybook/examples/rich-tooltip/ShortcutTooltip.vue
@@ -0,0 +1,25 @@
+<template>
+    <span ref="target" :style="{ display: 'inline-block' }">
+        <M3Button appearance="text" :aria-describedby="tooltipId">
+            Keyboard shortcut
+        </M3Button>
+
+        <M3RichTooltip :id="tooltipId" :target="() => target" hide-on-miss-click>
+            <template #heading>
+                Jump to inbox
+            </template>
+
+            Press <strong>G</strong>, then <strong>I</strong> to open the inbox from anywhere in the workspace.
+        </M3RichTooltip>
+    </span>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3RichTooltip } from '@/components/rich-tooltip'
+
+import { ref } from 'vue'
+
+const target = ref<HTMLElement | null>(null)
+const tooltipId = 'shortcut-tooltip-description'
+</script>
diff --git a/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue b/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
new file mode 100644
index 0000000..0261110
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
@@ -0,0 +1,185 @@
+<template>
+    <div class="surface-inspector-sheet">
+        <M3SurfacePanel
+            class="surface-inspector-sheet__topbar"
+            :fill-height="false"
+            :height="84"
+            :rounding="24"
+            variant="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-inspector-sheet__topbar-content">
+                <div>
+                    <strong>Scenario: inspector side sheet</strong>
+                    <p>A supplemental editing surface appears from the edge while the main dashboard stays visible.</p>
+                </div>
+
+                <M3Button appearance="tonal" @click="opened = true">
+                    Open inspector
+                </M3Button>
+            </div>
+        </M3SurfacePanel>
+
+        <div class="surface-inspector-sheet__grid">
+            <M3SurfacePanel
+                v-for="label in ['Launch plan', 'Dependencies', 'Approvals']"
+                :key="label"
+                class="surface-inspector-sheet__panel"
+                :fill-height="false"
+                :height="188"
+                :rounding="18"
+                variant="surface-container-low"
+                :elevation="1"
+            >
+                <h3>{{ label }}</h3>
+                <p>Dashboard content keeps its place while the inspector surface is layered above it.</p>
+            </M3SurfacePanel>
+        </div>
+
+        <M3Surface
+            mode="modal"
+            :shown="opened"
+            anchor="end"
+            :fill-width="false"
+            :width="360"
+            :inset-top="0"
+            :inset-right="0"
+            :inset-bottom="0"
+            :rounding-top-left="28"
+            :rounding-bottom-left="28"
+            :rounding-top-right="0"
+            :rounding-bottom-right="0"
+            :elevation="2"
+            variant="surface-container-high"
+            overflow="auto"
+            class="surface-inspector-sheet__sheet"
+            @update:shown="opened = $event"
+            @dismiss="opened = false"
+        >
+            <h3>Release inspector</h3>
+            <p>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
+
+            <div class="surface-inspector-sheet__form">
+                <M3TextField
+                    v-model:value="owner"
+                    label="Owner email"
+                    outlined
+                />
+
+                <M3Select
+                    v-model:value="priority"
+                    label="Priority"
+                    :options="priorityOptions"
+                    outlined
+                />
+
+                <M3TextField
+                    v-model:value="notes"
+                    label="Notes"
+                    outlined
+                    multiline
+                />
+            </div>
+
+            <div class="surface-inspector-sheet__actions">
+                <M3Button appearance="text" @click="opened = false">
+                    Dismiss
+                </M3Button>
+
+                <M3Button appearance="filled" @click="opened = false">
+                    Save changes
+                </M3Button>
+            </div>
+        </M3Surface>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Select } from '@/components/select'
+import { M3Surface, M3SurfacePanel } from '@/components/surface'
+import { M3TextField } from '@/components/text-field'
+
+import { ref } from 'vue'
+
+const opened = ref(false)
+const owner = ref('owner@example.com')
+const priority = ref<'low' | 'normal' | 'high' | null>('normal')
+const notes = ref('Coordinate the release notes and schedule rollout approval.')
+
+const priorityOptions = [{
+  label: 'Low',
+  value: 'low',
+}, {
+  label: 'Normal',
+  value: 'normal',
+}, {
+  label: 'High',
+  value: 'high',
+}]
+</script>
+
+<style scoped>
+.surface-inspector-sheet {
+    min-height: 100vh;
+    padding: 24px;
+    box-sizing: border-box;
+    color: var(--m3-sys-on-surface);
+    background: linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%);
+}
+
+.surface-inspector-sheet__topbar,
+.surface-inspector-sheet__panel {
+    padding: 18px;
+}
+
+.surface-inspector-sheet__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-inspector-sheet__topbar-content strong {
+    display: block;
+    margin-bottom: 6px;
+}
+
+.surface-inspector-sheet__topbar-content p,
+.surface-inspector-sheet__panel p,
+.surface-inspector-sheet__sheet p {
+    margin: 0;
+    font-size: 13px;
+    line-height: 1.45;
+    opacity: 0.82;
+}
+
+.surface-inspector-sheet__grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 16px;
+    margin-top: 16px;
+}
+
+.surface-inspector-sheet__panel h3,
+.surface-inspector-sheet__sheet h3 {
+    margin: 0 0 8px;
+}
+
+.surface-inspector-sheet__sheet {
+    padding: 20px;
+}
+
+.surface-inspector-sheet__form {
+    display: grid;
+    gap: 12px;
+    margin-top: 16px;
+}
+
+.surface-inspector-sheet__actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 12px;
+    margin-top: 16px;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceWorkspaceDialog.vue b/m3-vue/storybook/examples/surface/SurfaceWorkspaceDialog.vue
new file mode 100644
index 0000000..e9ea7e3
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceWorkspaceDialog.vue
@@ -0,0 +1,182 @@
+<template>
+    <div class="surface-workspace-dialog">
+        <M3SurfacePanel
+            class="surface-workspace-dialog__topbar"
+            :fill-height="false"
+            :height="84"
+            :rounding="24"
+            variant="surface-container"
+            :elevation="0"
+        >
+            <div class="surface-workspace-dialog__topbar-content">
+                <div>
+                    <strong>Scenario: workspace confirmation dialog</strong>
+                    <p>A blocking decision interrupts the current workspace without replacing the layout beneath it.</p>
+                </div>
+
+                <M3Button @click="opened = true">
+                    Archive project
+                </M3Button>
+            </div>
+        </M3SurfacePanel>
+
+        <div class="surface-workspace-dialog__summary">
+            <M3SurfacePanel
+                class="surface-workspace-dialog__panel"
+                :rounding="20"
+                variant="surface-container-lowest"
+                :elevation="0"
+            >
+                <h3>Workspace overview</h3>
+                <p>Main content remains visible under the dialog, so the user keeps the surrounding context while confirming the action.</p>
+            </M3SurfacePanel>
+
+            <M3SurfacePanel
+                class="surface-workspace-dialog__panel"
+                :rounding="20"
+                variant="surface-container-low"
+                :elevation="1"
+            >
+                <h3>Activity</h3>
+                <p>12 tasks updated today</p>
+            </M3SurfacePanel>
+        </div>
+
+        <div class="surface-workspace-dialog__grid">
+            <M3SurfacePanel
+                v-for="label in ['Roadmap', 'Assets', 'Owners']"
+                :key="label"
+                class="surface-workspace-dialog__panel"
+                :fill-height="false"
+                :height="180"
+                :rounding="18"
+                variant="surface-container-low"
+                :elevation="1"
+            >
+                <h3>{{ label }}</h3>
+                <p>Supporting surface inside the same workspace scene.</p>
+            </M3SurfacePanel>
+        </div>
+
+        <M3Surface
+            mode="modal"
+            :shown="opened"
+            anchor="center"
+            :fill-width="false"
+            :fill-height="false"
+            :width="520"
+            :inset-top="24"
+            :inset-bottom="24"
+            :rounding="28"
+            :elevation="3"
+            variant="surface-container-high"
+            class="surface-workspace-dialog__dialog"
+            @update:shown="opened = $event"
+            @dismiss="opened = false"
+        >
+            <h3>Archive this workspace?</h3>
+            <p>Archiving hides the project from active planning views but keeps its history available for reporting.</p>
+
+            <M3SurfacePanel
+                class="surface-workspace-dialog__notice"
+                :fill-height="false"
+                :height="92"
+                :rounding="18"
+                variant="surface-container"
+                :elevation="0"
+            >
+                Team members will retain read access until the workspace is restored.
+            </M3SurfacePanel>
+
+            <div class="surface-workspace-dialog__actions">
+                <M3Button appearance="text" @click="opened = false">
+                    Cancel
+                </M3Button>
+
+                <M3Button appearance="filled" @click="opened = false">
+                    Archive
+                </M3Button>
+            </div>
+        </M3Surface>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3Surface, M3SurfacePanel } from '@/components/surface'
+
+import { ref } from 'vue'
+
+const opened = ref(false)
+</script>
+
+<style scoped>
+.surface-workspace-dialog {
+    min-height: 100vh;
+    padding: 24px;
+    box-sizing: border-box;
+    color: var(--m3-sys-on-surface);
+    background: linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%);
+}
+
+.surface-workspace-dialog__topbar,
+.surface-workspace-dialog__panel,
+.surface-workspace-dialog__notice {
+    padding: 18px;
+}
+
+.surface-workspace-dialog__topbar-content {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+}
+
+.surface-workspace-dialog__topbar-content strong {
+    display: block;
+    margin-bottom: 6px;
+}
+
+.surface-workspace-dialog__topbar-content p,
+.surface-workspace-dialog__panel p,
+.surface-workspace-dialog__dialog p {
+    margin: 0;
+    font-size: 13px;
+    line-height: 1.45;
+    opacity: 0.82;
+}
+
+.surface-workspace-dialog__summary {
+    display: grid;
+    grid-template-columns: 2fr 1fr;
+    gap: 16px;
+    margin-top: 16px;
+}
+
+.surface-workspace-dialog__grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 16px;
+    margin-top: 16px;
+}
+
+.surface-workspace-dialog__panel h3,
+.surface-workspace-dialog__dialog h3 {
+    margin: 0 0 8px;
+}
+
+.surface-workspace-dialog__dialog {
+    padding: 24px;
+}
+
+.surface-workspace-dialog__notice {
+    margin-top: 16px;
+}
+
+.surface-workspace-dialog__actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 12px;
+    margin-top: 16px;
+}
+</style>

From fa9103b915b2afea9493314d5f1022b583703208 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 18:43:40 +0400
Subject: [PATCH 31/37] feat: Storybook surface guidance was refined

---
 .../storybook/components/M3RichTooltip.mdx    | 22 ++++++
 m3-react/storybook/components/M3Surface.mdx   | 32 ++++++++
 .../surface/SurfaceInspectorSheet.tsx         | 73 +++++++++++-------
 m3-vue/storybook/components/M3RichTooltip.mdx | 22 ++++++
 m3-vue/storybook/components/M3Surface.mdx     | 32 ++++++++
 .../surface/SurfaceInspectorSheet.vue         | 77 +++++++++++--------
 6 files changed, 195 insertions(+), 63 deletions(-)

diff --git a/m3-react/storybook/components/M3RichTooltip.mdx b/m3-react/storybook/components/M3RichTooltip.mdx
index ea26489..ece4779 100644
--- a/m3-react/storybook/components/M3RichTooltip.mdx
+++ b/m3-react/storybook/components/M3RichTooltip.mdx
@@ -53,6 +53,28 @@ If the user must know the message to complete the task safely, do not hide it be
 
 Rich tooltips can contain more than plain text, but they should still feel like supplementary context, not a mini dialog.
 
+## Content anatomy
+
+- short title or intent cue that helps users scan quickly
+- one supporting sentence that explains the consequence, shortcut, or background
+- optional trailing hint such as a keyboard shortcut or low-friction action
+
+The stories in this workspace keep the payload deliberately compact so the tooltip stays tethered to the trigger instead of competing with nearby layout.
+
+## Do / don't
+
+### Do
+
+- keep the message tightly tied to the hovered or focused trigger
+- prefer consequence framing for risky actions and hint framing for shortcuts
+- keep the tooltip short enough to read without shifting task focus
+
+### Don’t
+
+- move essential validation, permissions, or policy copy only into a tooltip
+- stack multiple paragraphs or full form controls inside the surface
+- use a rich tooltip when the user needs blocking confirmation or multi-step input
+
 ## Resources
 
 - [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
index b60e584..f67d293 100644
--- a/m3-react/storybook/components/M3Surface.mdx
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -67,6 +67,38 @@ The orchestration examples work best when you model stable states such as `docke
 
 When morphing between surfaces, animate toward a measured target rectangle or target inset set. This prevents the “overlay shrinks somewhere else, then snaps” failure mode that surface transitions are especially sensitive to.
 
+## Content anatomy
+
+### Dialog-like surface
+
+- headline or short title that explains the decision
+- compact supporting copy that clarifies consequences
+- primary and secondary actions grouped near the end of the reading flow
+
+### Side-sheet surface
+
+- header with title and optional affordance action
+- scrollable supporting content or form body
+- footer actions anchored at the bottom when the sheet remains open during editing
+
+The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-sheet__header`, `m3-side-sheet__content`, and `m3-side-sheet__footer` structure layered on top of `M3Surface`.
+
+## Do / don't
+
+### Do
+
+- keep supporting surfaces narrowly scoped to one nearby task
+- preserve surrounding context for side sheets and supporting panels
+- align action placement with the surface role, such as bottom-aligned footer actions for longer sheets
+- use explicit stable states when one surface can morph into another
+
+### Don’t
+
+- replace a full workflow with a side sheet if the user needs a primary destination
+- overload modal surfaces with dense navigation or unrelated secondary tools
+- let transition targets drift away from the final resting geometry
+- hide critical task instructions only inside a temporary supporting surface
+
 ## Resources
 
 - [M3 Cards overview](https://m3.material.io/components/cards/overview)
diff --git a/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx b/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
index 9b5fad8..e744082 100644
--- a/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceInspectorSheet.tsx
@@ -5,6 +5,8 @@ import type {
 import type { M3SelectOption } from '@/components/select'
 
 import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
 import { M3Select } from '@/components/select'
 import { M3Surface, M3SurfacePanel } from '@/components/surface'
 import { M3TextField } from '@/components/text-field'
@@ -96,37 +98,50 @@ const SurfaceInspectorSheet: FC = () => {
         overflow="auto"
         onToggle={setOpened}
         onDismiss={() => setOpened(false)}
-        style={{ padding: '20px' }}
+        className="m3-side-sheet surface-inspector-sheet__sheet"
       >
-        <h3 style={{ margin: '0 0 12px' }}>Release inspector</h3>
-        <p style={{ margin: '0 0 16px' }}>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
-
-        <div style={{ display: 'grid', gap: '12px' }}>
-          <M3TextField
-            value={owner}
-            label="Owner email"
-            outlined={true}
-            onUpdate={setOwner}
-          />
-
-          <M3Select<Priority>
-            value={priority}
-            label="Priority"
-            options={priorityOptions}
-            outlined={true}
-            onUpdate={setPriority}
-          />
-
-          <M3TextField
-            value={notes}
-            label="Notes"
-            outlined={true}
-            multiline={true}
-            onUpdate={setNotes}
-          />
+        <header className="m3-side-sheet__header">
+          <div className="m3-side-sheet__title">Release inspector</div>
+
+          <div className="m3-side-sheet__affordance">
+            <M3IconButton appearance="text" onClick={() => setOpened(false)}>
+              <M3Icon name="close" />
+            </M3IconButton>
+          </div>
+        </header>
+
+        <div className="m3-side-sheet__content">
+          <div style={{ display: 'grid', gap: '16px', width: '100%', padding: '0 24px 24px' }}>
+            <p style={{ margin: 0 }}>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
+
+            <div style={{ display: 'grid', gap: '12px' }}>
+              <M3TextField
+                value={owner}
+                label="Owner email"
+                outlined={true}
+                onUpdate={setOwner}
+              />
+
+              <M3Select<Priority>
+                value={priority}
+                label="Priority"
+                options={priorityOptions}
+                outlined={true}
+                onUpdate={setPriority}
+              />
+
+              <M3TextField
+                value={notes}
+                label="Notes"
+                outlined={true}
+                multiline={true}
+                onUpdate={setNotes}
+              />
+            </div>
+          </div>
         </div>
 
-        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '12px', marginTop: '16px' }}>
+        <footer className="m3-side-sheet__footer" style={{ justifyContent: 'flex-end' }}>
           <M3Button appearance="text" onClick={() => setOpened(false)}>
             Dismiss
           </M3Button>
@@ -134,7 +149,7 @@ const SurfaceInspectorSheet: FC = () => {
           <M3Button appearance="filled" onClick={() => setOpened(false)}>
             Save changes
           </M3Button>
-        </div>
+        </footer>
       </M3Surface>
     </div>
   )
diff --git a/m3-vue/storybook/components/M3RichTooltip.mdx b/m3-vue/storybook/components/M3RichTooltip.mdx
index ea26489..ece4779 100644
--- a/m3-vue/storybook/components/M3RichTooltip.mdx
+++ b/m3-vue/storybook/components/M3RichTooltip.mdx
@@ -53,6 +53,28 @@ If the user must know the message to complete the task safely, do not hide it be
 
 Rich tooltips can contain more than plain text, but they should still feel like supplementary context, not a mini dialog.
 
+## Content anatomy
+
+- short title or intent cue that helps users scan quickly
+- one supporting sentence that explains the consequence, shortcut, or background
+- optional trailing hint such as a keyboard shortcut or low-friction action
+
+The stories in this workspace keep the payload deliberately compact so the tooltip stays tethered to the trigger instead of competing with nearby layout.
+
+## Do / don't
+
+### Do
+
+- keep the message tightly tied to the hovered or focused trigger
+- prefer consequence framing for risky actions and hint framing for shortcuts
+- keep the tooltip short enough to read without shifting task focus
+
+### Don’t
+
+- move essential validation, permissions, or policy copy only into a tooltip
+- stack multiple paragraphs or full form controls inside the surface
+- use a rich tooltip when the user needs blocking confirmation or multi-step input
+
 ## Resources
 
 - [M3 Tooltips overview](https://m3.material.io/components/tooltips/overview)
diff --git a/m3-vue/storybook/components/M3Surface.mdx b/m3-vue/storybook/components/M3Surface.mdx
index b60e584..f67d293 100644
--- a/m3-vue/storybook/components/M3Surface.mdx
+++ b/m3-vue/storybook/components/M3Surface.mdx
@@ -67,6 +67,38 @@ The orchestration examples work best when you model stable states such as `docke
 
 When morphing between surfaces, animate toward a measured target rectangle or target inset set. This prevents the “overlay shrinks somewhere else, then snaps” failure mode that surface transitions are especially sensitive to.
 
+## Content anatomy
+
+### Dialog-like surface
+
+- headline or short title that explains the decision
+- compact supporting copy that clarifies consequences
+- primary and secondary actions grouped near the end of the reading flow
+
+### Side-sheet surface
+
+- header with title and optional affordance action
+- scrollable supporting content or form body
+- footer actions anchored at the bottom when the sheet remains open during editing
+
+The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-sheet__header`, `m3-side-sheet__content`, and `m3-side-sheet__footer` structure layered on top of `M3Surface`.
+
+## Do / don't
+
+### Do
+
+- keep supporting surfaces narrowly scoped to one nearby task
+- preserve surrounding context for side sheets and supporting panels
+- align action placement with the surface role, such as bottom-aligned footer actions for longer sheets
+- use explicit stable states when one surface can morph into another
+
+### Don’t
+
+- replace a full workflow with a side sheet if the user needs a primary destination
+- overload modal surfaces with dense navigation or unrelated secondary tools
+- let transition targets drift away from the final resting geometry
+- hide critical task instructions only inside a temporary supporting surface
+
 ## Resources
 
 - [M3 Cards overview](https://m3.material.io/components/cards/overview)
diff --git a/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue b/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
index 0261110..2669f51 100644
--- a/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceInspectorSheet.vue
@@ -52,36 +52,49 @@
             :elevation="2"
             variant="surface-container-high"
             overflow="auto"
-            class="surface-inspector-sheet__sheet"
+            class="m3-side-sheet surface-inspector-sheet__sheet"
             @update:shown="opened = $event"
             @dismiss="opened = false"
         >
-            <h3>Release inspector</h3>
-            <p>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
-
-            <div class="surface-inspector-sheet__form">
-                <M3TextField
-                    v-model:value="owner"
-                    label="Owner email"
-                    outlined
-                />
-
-                <M3Select
-                    v-model:value="priority"
-                    label="Priority"
-                    :options="priorityOptions"
-                    outlined
-                />
-
-                <M3TextField
-                    v-model:value="notes"
-                    label="Notes"
-                    outlined
-                    multiline
-                />
+            <header class="m3-side-sheet__header">
+                <div class="m3-side-sheet__title">
+                    Release inspector
+                </div>
+
+                <div class="m3-side-sheet__affordance">
+                    <M3IconButton appearance="text" @click="opened = false">
+                        <M3Icon name="close" />
+                    </M3IconButton>
+                </div>
+            </header>
+
+            <div class="m3-side-sheet__content">
+                <div class="surface-inspector-sheet__form">
+                    <p>Use the side sheet for supporting edits that should not replace the dashboard context.</p>
+
+                    <M3TextField
+                        v-model:value="owner"
+                        label="Owner email"
+                        outlined
+                    />
+
+                    <M3Select
+                        v-model:value="priority"
+                        label="Priority"
+                        :options="priorityOptions"
+                        outlined
+                    />
+
+                    <M3TextField
+                        v-model:value="notes"
+                        label="Notes"
+                        outlined
+                        multiline
+                    />
+                </div>
             </div>
 
-            <div class="surface-inspector-sheet__actions">
+            <footer class="m3-side-sheet__footer surface-inspector-sheet__actions">
                 <M3Button appearance="text" @click="opened = false">
                     Dismiss
                 </M3Button>
@@ -89,13 +102,15 @@
                 <M3Button appearance="filled" @click="opened = false">
                     Save changes
                 </M3Button>
-            </div>
+            </footer>
         </M3Surface>
     </div>
 </template>
 
 <script lang="ts" setup>
 import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
 import { M3Select } from '@/components/select'
 import { M3Surface, M3SurfacePanel } from '@/components/surface'
 import { M3TextField } from '@/components/text-field'
@@ -166,20 +181,14 @@ const priorityOptions = [{
     margin: 0 0 8px;
 }
 
-.surface-inspector-sheet__sheet {
-    padding: 20px;
-}
-
 .surface-inspector-sheet__form {
     display: grid;
     gap: 12px;
-    margin-top: 16px;
+    width: 100%;
+    padding: 0 24px 24px;
 }
 
 .surface-inspector-sheet__actions {
-    display: flex;
     justify-content: flex-end;
-    gap: 12px;
-    margin-top: 16px;
 }
 </style>

From d2986d5c41a8222fe56e6fb6a607da7796a1214a Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Sun, 8 Mar 2026 19:00:23 +0400
Subject: [PATCH 32/37] style: Storybook typography was aligned with Material 3

---
 m3-react/storybook/manager-head.html |  22 +++++-
 m3-react/storybook/preview-head.html | 114 +++++++++++++++++++++++++++
 m3-react/storybook/preview.ts        |   2 +
 m3-react/storybook/theme.ts          |   4 +-
 m3-vue/storybook/manager-head.html   |  22 +++++-
 m3-vue/storybook/preview-head.html   | 114 +++++++++++++++++++++++++++
 m3-vue/storybook/preview.ts          |   2 +
 m3-vue/storybook/theme.ts            |   4 +-
 8 files changed, 280 insertions(+), 4 deletions(-)

diff --git a/m3-react/storybook/manager-head.html b/m3-react/storybook/manager-head.html
index 3491b87..b1bb22e 100644
--- a/m3-react/storybook/manager-head.html
+++ b/m3-react/storybook/manager-head.html
@@ -1,12 +1,32 @@
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" />
+
 <style>
+    :root {
+        --m3-storybook-font-family: 'Roboto', 'Noto Sans', 'Segoe UI', -apple-system, BlinkMacSystemFont, Arial, sans-serif;
+    }
+
+    html,
+    body,
+    #root,
+    button,
+    input,
+    select,
+    textarea {
+        font-family: var(--m3-storybook-font-family);
+    }
+
     .s-m3-logo {
         display: inline-flex;
         align-items: center;
         font-size: 24px;
+        font-family: var(--m3-storybook-font-family);
+        font-weight: 500;
         margin-left: -8px;
     }
 
     .s-m3-logo img {
         margin-right: 12px;
     }
-</style>
\ No newline at end of file
+</style>
diff --git a/m3-react/storybook/preview-head.html b/m3-react/storybook/preview-head.html
index e63338e..c1afbbe 100644
--- a/m3-react/storybook/preview-head.html
+++ b/m3-react/storybook/preview-head.html
@@ -1,7 +1,121 @@
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" />
+
 <style>
+    :root {
+        --m3-storybook-font-family: 'Roboto', 'Noto Sans', 'Segoe UI', -apple-system, BlinkMacSystemFont, Arial, sans-serif;
+        --m3-storybook-body-large-size: 16px;
+        --m3-storybook-body-large-line-height: 24px;
+        --m3-storybook-body-large-letter-spacing: 0.5px;
+        --m3-storybook-body-medium-size: 14px;
+        --m3-storybook-body-medium-line-height: 20px;
+        --m3-storybook-body-medium-letter-spacing: 0.25px;
+        --m3-storybook-title-large-size: 22px;
+        --m3-storybook-title-large-line-height: 28px;
+        --m3-storybook-title-medium-size: 16px;
+        --m3-storybook-title-medium-line-height: 24px;
+        --m3-storybook-title-medium-letter-spacing: 0.15px;
+        --m3-storybook-title-small-size: 14px;
+        --m3-storybook-title-small-line-height: 20px;
+        --m3-storybook-headline-large-size: 32px;
+        --m3-storybook-headline-large-line-height: 40px;
+        --m3-storybook-headline-medium-size: 28px;
+        --m3-storybook-headline-medium-line-height: 36px;
+        --m3-storybook-headline-small-size: 24px;
+        --m3-storybook-headline-small-line-height: 32px;
+    }
+
+    html,
     body {
         background: var(--m3-sys-surface);
         color: var(--m3-sys-on-surface);
+        font-family: var(--m3-storybook-font-family);
+    }
+
+    :where(
+        #storybook-root,
+        #storybook-docs,
+        .sb-wrapper,
+        .sb-heading,
+        .sbdocs,
+        .sbdocs-wrapper,
+        .sbdocs-content,
+        .sbdocs-title,
+        .sbdocs-subtitle,
+        .sbdocs-p,
+        .sb-bar,
+        .docblock-argstable,
+        .docblock-icongallery,
+        .docs-story
+    ) {
+        font-family: var(--m3-storybook-font-family) !important;
+    }
+
+    :where(.sb-wrapper, .sbdocs, .sbdocs-wrapper, .sbdocs-content) {
+        font-size: var(--m3-storybook-body-large-size);
+        line-height: var(--m3-storybook-body-large-line-height);
+        letter-spacing: var(--m3-storybook-body-large-letter-spacing);
+    }
+
+    :where(.sbdocs-content, .sbdocs-wrapper) {
+        max-width: 1000px;
+        margin-inline: auto;
+        width: 100%;
+    }
+
+    :where(.sbdocs-content p, .sbdocs-content li, .sbdocs-content td, .sbdocs-content th, .sbdocs-content blockquote) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-body-large-size) !important;
+        line-height: var(--m3-storybook-body-large-line-height) !important;
+        letter-spacing: var(--m3-storybook-body-large-letter-spacing) !important;
+    }
+
+    :where(.sbdocs-content h1, .sbdocs-title) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-large-size) !important;
+        line-height: var(--m3-storybook-headline-large-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h2) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-medium-size) !important;
+        line-height: var(--m3-storybook-headline-medium-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h3) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-small-size) !important;
+        line-height: var(--m3-storybook-headline-small-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h4, .sbdocs-subtitle) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-title-large-size) !important;
+        line-height: var(--m3-storybook-title-large-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h5, .sbdocs-content h6, .sb-heading) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-title-medium-size) !important;
+        line-height: var(--m3-storybook-title-medium-line-height) !important;
+        font-weight: 500 !important;
+        letter-spacing: var(--m3-storybook-title-medium-letter-spacing) !important;
+    }
+
+    :where(.sbdocs-content figcaption, .sbdocs-caption) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-body-medium-size) !important;
+        line-height: var(--m3-storybook-body-medium-line-height) !important;
+        letter-spacing: var(--m3-storybook-body-medium-letter-spacing) !important;
     }
 
     [class*=css] {
diff --git a/m3-react/storybook/preview.ts b/m3-react/storybook/preview.ts
index 0759b6d..a22d3b9 100644
--- a/m3-react/storybook/preview.ts
+++ b/m3-react/storybook/preview.ts
@@ -7,6 +7,7 @@ import './stylesheets/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
+import theme from './theme'
 import { MdxCodeBlock, MdxCodePreBlock } from './utils/mdxCodeBlock'
 
 type DocsParameter = NonNullable<NonNullable<Preview['parameters']>['docs']> & {
@@ -31,6 +32,7 @@ const docsParameter: DocsParameter = {
   source: {
     language: 'text',
   },
+  theme,
 }
 
 const applyThemeClass = (themeName?: unknown): void => {
diff --git a/m3-react/storybook/theme.ts b/m3-react/storybook/theme.ts
index 7a147d6..de2256c 100644
--- a/m3-react/storybook/theme.ts
+++ b/m3-react/storybook/theme.ts
@@ -1,5 +1,7 @@
 import { create } from 'storybook/theming'
 
+const fontBase = '\'Roboto\', \'Noto Sans\', \'Segoe UI\', -apple-system, BlinkMacSystemFont, Arial, sans-serif'
+
 export default create({
   appBg: '#141218',
   appBorderColor: '#49454F',
@@ -12,7 +14,7 @@ export default create({
   barTextColor: 'hsl(220, 100%, 89%)',
   brandTitle: '<span class="s-m3-logo"><img src="/assets/logo.png" alt="" width="42px" height="42px" /> m3-react</span>',
   colorPrimary: 'hsl(220, 55%, 25%)',
-  fontBase: '\'Roboto\', sans-serif',
+  fontBase,
   fontCode: 'monospace',
   inputBorderRadius: 4,
   textColor: '#E6E0E9',
diff --git a/m3-vue/storybook/manager-head.html b/m3-vue/storybook/manager-head.html
index 3491b87..b1bb22e 100644
--- a/m3-vue/storybook/manager-head.html
+++ b/m3-vue/storybook/manager-head.html
@@ -1,12 +1,32 @@
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" />
+
 <style>
+    :root {
+        --m3-storybook-font-family: 'Roboto', 'Noto Sans', 'Segoe UI', -apple-system, BlinkMacSystemFont, Arial, sans-serif;
+    }
+
+    html,
+    body,
+    #root,
+    button,
+    input,
+    select,
+    textarea {
+        font-family: var(--m3-storybook-font-family);
+    }
+
     .s-m3-logo {
         display: inline-flex;
         align-items: center;
         font-size: 24px;
+        font-family: var(--m3-storybook-font-family);
+        font-weight: 500;
         margin-left: -8px;
     }
 
     .s-m3-logo img {
         margin-right: 12px;
     }
-</style>
\ No newline at end of file
+</style>
diff --git a/m3-vue/storybook/preview-head.html b/m3-vue/storybook/preview-head.html
index e63338e..c1afbbe 100644
--- a/m3-vue/storybook/preview-head.html
+++ b/m3-vue/storybook/preview-head.html
@@ -1,7 +1,121 @@
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" />
+
 <style>
+    :root {
+        --m3-storybook-font-family: 'Roboto', 'Noto Sans', 'Segoe UI', -apple-system, BlinkMacSystemFont, Arial, sans-serif;
+        --m3-storybook-body-large-size: 16px;
+        --m3-storybook-body-large-line-height: 24px;
+        --m3-storybook-body-large-letter-spacing: 0.5px;
+        --m3-storybook-body-medium-size: 14px;
+        --m3-storybook-body-medium-line-height: 20px;
+        --m3-storybook-body-medium-letter-spacing: 0.25px;
+        --m3-storybook-title-large-size: 22px;
+        --m3-storybook-title-large-line-height: 28px;
+        --m3-storybook-title-medium-size: 16px;
+        --m3-storybook-title-medium-line-height: 24px;
+        --m3-storybook-title-medium-letter-spacing: 0.15px;
+        --m3-storybook-title-small-size: 14px;
+        --m3-storybook-title-small-line-height: 20px;
+        --m3-storybook-headline-large-size: 32px;
+        --m3-storybook-headline-large-line-height: 40px;
+        --m3-storybook-headline-medium-size: 28px;
+        --m3-storybook-headline-medium-line-height: 36px;
+        --m3-storybook-headline-small-size: 24px;
+        --m3-storybook-headline-small-line-height: 32px;
+    }
+
+    html,
     body {
         background: var(--m3-sys-surface);
         color: var(--m3-sys-on-surface);
+        font-family: var(--m3-storybook-font-family);
+    }
+
+    :where(
+        #storybook-root,
+        #storybook-docs,
+        .sb-wrapper,
+        .sb-heading,
+        .sbdocs,
+        .sbdocs-wrapper,
+        .sbdocs-content,
+        .sbdocs-title,
+        .sbdocs-subtitle,
+        .sbdocs-p,
+        .sb-bar,
+        .docblock-argstable,
+        .docblock-icongallery,
+        .docs-story
+    ) {
+        font-family: var(--m3-storybook-font-family) !important;
+    }
+
+    :where(.sb-wrapper, .sbdocs, .sbdocs-wrapper, .sbdocs-content) {
+        font-size: var(--m3-storybook-body-large-size);
+        line-height: var(--m3-storybook-body-large-line-height);
+        letter-spacing: var(--m3-storybook-body-large-letter-spacing);
+    }
+
+    :where(.sbdocs-content, .sbdocs-wrapper) {
+        max-width: 1000px;
+        margin-inline: auto;
+        width: 100%;
+    }
+
+    :where(.sbdocs-content p, .sbdocs-content li, .sbdocs-content td, .sbdocs-content th, .sbdocs-content blockquote) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-body-large-size) !important;
+        line-height: var(--m3-storybook-body-large-line-height) !important;
+        letter-spacing: var(--m3-storybook-body-large-letter-spacing) !important;
+    }
+
+    :where(.sbdocs-content h1, .sbdocs-title) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-large-size) !important;
+        line-height: var(--m3-storybook-headline-large-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h2) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-medium-size) !important;
+        line-height: var(--m3-storybook-headline-medium-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h3) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-headline-small-size) !important;
+        line-height: var(--m3-storybook-headline-small-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h4, .sbdocs-subtitle) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-title-large-size) !important;
+        line-height: var(--m3-storybook-title-large-line-height) !important;
+        font-weight: 400 !important;
+        letter-spacing: 0 !important;
+    }
+
+    :where(.sbdocs-content h5, .sbdocs-content h6, .sb-heading) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-title-medium-size) !important;
+        line-height: var(--m3-storybook-title-medium-line-height) !important;
+        font-weight: 500 !important;
+        letter-spacing: var(--m3-storybook-title-medium-letter-spacing) !important;
+    }
+
+    :where(.sbdocs-content figcaption, .sbdocs-caption) {
+        font-family: var(--m3-storybook-font-family) !important;
+        font-size: var(--m3-storybook-body-medium-size) !important;
+        line-height: var(--m3-storybook-body-medium-line-height) !important;
+        letter-spacing: var(--m3-storybook-body-medium-letter-spacing) !important;
     }
 
     [class*=css] {
diff --git a/m3-vue/storybook/preview.ts b/m3-vue/storybook/preview.ts
index 75fcebb..1a402d0 100644
--- a/m3-vue/storybook/preview.ts
+++ b/m3-vue/storybook/preview.ts
@@ -7,6 +7,7 @@ import './stylesheets/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
+import theme from './theme'
 import { MdxCodeBlock, MdxCodePreBlock } from './utils/mdxCodeBlock'
 
 type DocsParameter = NonNullable<NonNullable<Preview['parameters']>['docs']> & {
@@ -31,6 +32,7 @@ const docsParameter: DocsParameter = {
   source: {
     language: 'text',
   },
+  theme,
 }
 
 const applyThemeClass = (themeName?: unknown): void => {
diff --git a/m3-vue/storybook/theme.ts b/m3-vue/storybook/theme.ts
index 0369bec..1ae9c59 100644
--- a/m3-vue/storybook/theme.ts
+++ b/m3-vue/storybook/theme.ts
@@ -1,5 +1,7 @@
 import { create } from 'storybook/theming'
 
+const fontBase = '\'Roboto\', \'Noto Sans\', \'Segoe UI\', -apple-system, BlinkMacSystemFont, Arial, sans-serif'
+
 export default create({
   appBg: '#141218',
   appBorderColor: '#49454F',
@@ -12,7 +14,7 @@ export default create({
   barTextColor: 'hsl(220, 100%, 89%)',
   brandTitle: '<span class="s-m3-logo"><img src="/assets/logo.png" alt="" width="42px" height="42px" /> m3-vue</span>',
   colorPrimary: 'hsl(220, 55%, 25%)',
-  fontBase: '\'Roboto\', sans-serif',
+  fontBase,
   fontCode: 'monospace',
   inputBorderRadius: 4,
   textColor: '#E6E0E9',

From bb758d56df4cce5b53fe0b6df7868d5b1a876565 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 9 Mar 2026 13:24:02 +0400
Subject: [PATCH 33/37] feat: Storybook local theming patterns were added

---
 .../assets/stylesheets/storybook/utils.scss   | 171 ++++
 .../local-theme/LocalThemeShowcase.tsx        | 278 ++++++
 .../examples/local-theme/styles.scss          | 352 +++++++
 .../patterns/LocalTheming.stories.tsx         |  39 +
 m3-react/storybook/preview.ts                 |   3 +-
 m3-react/storybook/stylesheets/utils.scss     |  62 --
 .../local-theme/LocalThemeShowcase.vue        | 875 ++++++++++++++++++
 .../patterns/LocalTheming.stories.ts          |  75 ++
 m3-vue/storybook/preview.ts                   |   3 +-
 m3-vue/storybook/stylesheets/utils.scss       |  62 --
 10 files changed, 1792 insertions(+), 128 deletions(-)
 create mode 100644 m3-foundation/assets/stylesheets/storybook/utils.scss
 create mode 100644 m3-react/storybook/examples/local-theme/LocalThemeShowcase.tsx
 create mode 100644 m3-react/storybook/examples/local-theme/styles.scss
 create mode 100644 m3-react/storybook/patterns/LocalTheming.stories.tsx
 delete mode 100644 m3-react/storybook/stylesheets/utils.scss
 create mode 100644 m3-vue/storybook/examples/local-theme/LocalThemeShowcase.vue
 create mode 100644 m3-vue/storybook/patterns/LocalTheming.stories.ts
 delete mode 100644 m3-vue/storybook/stylesheets/utils.scss

diff --git a/m3-foundation/assets/stylesheets/storybook/utils.scss b/m3-foundation/assets/stylesheets/storybook/utils.scss
new file mode 100644
index 0000000..33cf380
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/storybook/utils.scss
@@ -0,0 +1,171 @@
+@use 'sass:map';
+
+$m3-storybook-base-space: 8px;
+$m3-storybook-multipliers: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10;
+$m3-storybook-grid-columns: 12;
+$m3-storybook-breakpoints: (
+  sm: 576px,
+  md: 768px,
+  lg: 992px,
+  xl: 1200px,
+  xxl: 1400px,
+);
+$m3-storybook-container-max-widths: (
+  sm: 540px,
+  md: 720px,
+  lg: 960px,
+  xl: 1140px,
+  xxl: 1320px,
+);
+
+.d-block { display: block !important; }
+.d-inline { display: inline !important; }
+.d-inline-block { display: inline-block !important; }
+.d-none { display: none !important; }
+.d-flex { display: flex !important; }
+
+.flex-wrap {
+  flex-wrap: wrap !important;
+}
+
+.flex-container {
+  @extend .d-flex;
+  @extend .flex-wrap;
+}
+
+.flex-row {
+  @extend .d-flex;
+  align-items: center;
+}
+
+.h-100 {
+  height: 100% !important;
+}
+
+.mw-100 {
+  max-width: 100% !important;
+}
+
+.w-100 {
+  width: 100% !important;
+}
+
+.mt-auto, .my-auto, .m-auto { margin-top: auto !important; }
+.mb-auto, .my-auto, .m-auto { margin-bottom: auto !important; }
+.ml-auto, .mx-auto, .m-auto { margin-left: auto !important; }
+.mr-auto, .mx-auto, .m-auto { margin-right: auto !important; }
+
+.mt-0, .my-0, .m-0 { margin-top: 0 !important; }
+.mb-0, .my-0, .m-0 { margin-bottom: 0 !important; }
+.ml-0, .mx-0, .m-0 { margin-left: 0 !important; }
+.mr-0, .mx-0, .m-0 { margin-right: 0 !important; }
+
+.pt-0, .py-0, .p-0 { padding-top: 0 !important; }
+.pb-0, .py-0, .p-0 { padding-bottom: 0 !important; }
+.pl-0, .px-0, .p-0 { padding-left: 0 !important; }
+.pr-0, .px-0, .p-0 { padding-right: 0 !important; }
+
+@each $value in $m3-storybook-multipliers {
+  .mt-#{$value}, .my-#{$value}, .m-#{$value} { margin-top:    0.5 * $value * $m3-storybook-base-space !important; }
+  .mb-#{$value}, .my-#{$value}, .m-#{$value} { margin-bottom: 0.5 * $value * $m3-storybook-base-space !important; }
+  .ml-#{$value}, .mx-#{$value}, .m-#{$value} { margin-left:   0.5 * $value * $m3-storybook-base-space !important; }
+  .mr-#{$value}, .mx-#{$value}, .m-#{$value} { margin-right:  0.5 * $value * $m3-storybook-base-space !important; }
+
+  .mt-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-top:    -0.5 * $value * $m3-storybook-base-space !important; }
+  .mb-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-bottom: -0.5 * $value * $m3-storybook-base-space !important; }
+  .ml-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-left:   -0.5 * $value * $m3-storybook-base-space !important; }
+  .mr-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-right:  -0.5 * $value * $m3-storybook-base-space !important; }
+
+  .pt-#{$value}, .py-#{$value}, .p-#{$value} { padding-top:    0.5 * $value * $m3-storybook-base-space !important; }
+  .pb-#{$value}, .py-#{$value}, .p-#{$value} { padding-bottom: 0.5 * $value * $m3-storybook-base-space !important; }
+  .pl-#{$value}, .px-#{$value}, .p-#{$value} { padding-left:   0.5 * $value * $m3-storybook-base-space !important; }
+  .pr-#{$value}, .px-#{$value}, .p-#{$value} { padding-right:  0.5 * $value * $m3-storybook-base-space !important; }
+}
+
+.sb-container,
+.sb-container-fluid {
+  width: 100%;
+  padding-inline: 12px;
+  margin-inline: auto;
+  box-sizing: border-box;
+}
+
+.sb-container {
+  max-width: 100%;
+}
+
+@each $breakpoint, $max-width in $m3-storybook-container-max-widths {
+  @media (min-width: map.get($m3-storybook-breakpoints, $breakpoint)) {
+    .sb-container {
+      max-width: $max-width;
+    }
+  }
+}
+
+.sb-row {
+  --sb-gutter-x: 24px;
+  --sb-gutter-y: 0px;
+  display: flex;
+  flex-wrap: wrap;
+  margin-top: calc(-1 * var(--sb-gutter-y));
+  margin-inline: calc(-0.5 * var(--sb-gutter-x));
+}
+
+.sb-row > * {
+  flex-shrink: 0;
+  width: 100%;
+  max-width: 100%;
+  padding-inline: calc(var(--sb-gutter-x) * 0.5);
+  margin-top: var(--sb-gutter-y);
+  box-sizing: border-box;
+}
+
+.sb-col {
+  flex: 1 0 0%;
+}
+
+@for $column from 1 through $m3-storybook-grid-columns {
+  .sb-col-#{$column} {
+    flex: 0 0 auto;
+    width: calc(100% * #{$column} / #{$m3-storybook-grid-columns});
+  }
+}
+
+@each $breakpoint, $width in $m3-storybook-breakpoints {
+  @media (min-width: $width) {
+    .sb-col-#{$breakpoint} {
+      flex: 1 0 0%;
+    }
+
+    @for $column from 1 through $m3-storybook-grid-columns {
+      .sb-col-#{$breakpoint}-#{$column} {
+        flex: 0 0 auto;
+        width: calc(100% * #{$column} / #{$m3-storybook-grid-columns});
+      }
+    }
+  }
+}
+
+.sb-g-0,
+.sb-gx-0 {
+  --sb-gutter-x: 0px;
+}
+
+.sb-g-0,
+.sb-gy-0 {
+  --sb-gutter-y: 0px;
+}
+
+@each $value in $m3-storybook-multipliers {
+  $space: 0.5 * $value * $m3-storybook-base-space;
+
+  .sb-g-#{$value},
+  .sb-gx-#{$value} {
+    --sb-gutter-x: #{$space};
+  }
+
+  .sb-g-#{$value},
+  .sb-gy-#{$value} {
+    --sb-gutter-y: #{$space};
+  }
+}
diff --git a/m3-react/storybook/examples/local-theme/LocalThemeShowcase.tsx b/m3-react/storybook/examples/local-theme/LocalThemeShowcase.tsx
new file mode 100644
index 0000000..f2ee59e
--- /dev/null
+++ b/m3-react/storybook/examples/local-theme/LocalThemeShowcase.tsx
@@ -0,0 +1,278 @@
+import type { FC } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3SurfacePanel } from '@/components/surface'
+
+type LocalThemeVariant = 'danger' | 'warm-alert' | 'success' | 'brand-muted' | 'nested'
+
+type ThemeCardProps = {
+  eyebrow: string
+  title: string
+  copy: string
+  scopeClassName?: string
+  primaryAction: string
+  secondaryAction?: string
+  tertiaryAction?: string
+  tertiaryScopeClassName?: string
+}
+
+type ThemeCardRowProps = {
+  cards: ThemeCardProps[]
+  className?: string
+}
+
+const ThemeCard: FC<ThemeCardProps> = ({
+  eyebrow,
+  title,
+  copy,
+  scopeClassName,
+  primaryAction,
+  secondaryAction,
+  tertiaryAction,
+  tertiaryScopeClassName,
+}) => {
+  return (
+    <M3SurfacePanel
+      className={`m3-local-theme-showcase__card h-100 ${scopeClassName ?? ''}`.trim()}
+      fillHeight={false}
+      rounding={28}
+      variant="surface-container-high"
+      elevation={1}
+    >
+      <div className="m3-local-theme-showcase__eyebrow">{eyebrow}</div>
+      <h3 className="m3-local-theme-showcase__title">{title}</h3>
+      <p className="m3-local-theme-showcase__copy">{copy}</p>
+
+      <div className="m3-local-theme-showcase__swatches">
+        <div className="m3-local-theme-showcase__swatch">
+          <span className="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+          <span>Surface</span>
+        </div>
+
+        <div className="m3-local-theme-showcase__swatch">
+          <span className="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+          <span>Container</span>
+        </div>
+
+        <div className="m3-local-theme-showcase__swatch">
+          <span className="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+          <span>Accent</span>
+        </div>
+      </div>
+
+      <div className="m3-local-theme-showcase__actions">
+        {tertiaryAction ? (
+          tertiaryScopeClassName ? (
+            <span className={tertiaryScopeClassName}>
+              <M3Button appearance="text">
+                {tertiaryAction}
+              </M3Button>
+            </span>
+          ) : (
+            <M3Button appearance="text">
+              {tertiaryAction}
+            </M3Button>
+          )
+        ) : null}
+
+        {secondaryAction ? (
+          <M3Button appearance="tonal">
+            {secondaryAction}
+          </M3Button>
+        ) : null}
+
+        <M3Button appearance="filled">
+          {primaryAction}
+        </M3Button>
+      </div>
+    </M3SurfacePanel>
+  )
+}
+
+const ThemeCardRow: FC<ThemeCardRowProps> = ({ cards, className }) => {
+  return (
+    <div className={`sb-row sb-g-5 ${className ?? ''}`.trim()}>
+      {cards.map((card) => (
+        <div key={card.eyebrow} className="sb-col-12 sb-col-lg-6 d-flex">
+          <ThemeCard {...card} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+const DangerScene: FC = () => {
+  return (
+    <>
+      <ThemeCardRow cards={[{
+        eyebrow: 'Default scope',
+        title: 'Default destructive action',
+        copy: 'Without a local theme, the same controls stay on the global primary palette and neutral surface tokens.',
+        primaryAction: 'Delete release',
+        secondaryAction: 'Review logs',
+        tertiaryAction: 'Cancel',
+      }, {
+        eyebrow: 'Danger scope',
+        title: 'Locally themed destructive action',
+        copy: 'A single wrapper class re-targets the same button and surface tokens to a red destructive palette with a warmer supporting surface.',
+        scopeClassName: 'm3-local-theme m3-local-theme--danger',
+        primaryAction: 'Delete release',
+        secondaryAction: 'Review logs',
+        tertiaryAction: 'Cancel',
+      }]}
+      />
+
+      <ThemeCardRow
+        className="mt-5"
+        cards={[{
+          eyebrow: 'Danger scope + reset action',
+          title: 'Locally themed destructive action',
+          copy: 'Nested reset scope restores the baseline global theme inside a danger module, so a single supporting action can fall back to the default button language.',
+          scopeClassName: 'm3-local-theme m3-local-theme--danger',
+          primaryAction: 'Delete release',
+          secondaryAction: 'Review logs',
+          tertiaryAction: 'Cancel',
+          tertiaryScopeClassName: 'm3-local-theme m3-local-theme--reset',
+        }]}
+      />
+    </>
+  )
+}
+
+const WarmAlertScene: FC = () => {
+  return (
+    <ThemeCardRow cards={[{
+      eyebrow: 'Default scope',
+      title: 'Billing reminder card',
+      copy: 'The neutral version uses the baseline surface hierarchy from the active global theme.',
+      primaryAction: 'Resolve hold',
+      secondaryAction: 'View invoices',
+      tertiaryAction: 'Dismiss',
+    }, {
+      eyebrow: 'Warm alert scope',
+      title: 'Billing reminder card',
+      copy: 'The local alert class shifts the panel into a warmer family and retargets tonal and filled buttons without affecting the surrounding page.',
+      scopeClassName: 'm3-local-theme m3-local-theme--warm-alert',
+      primaryAction: 'Resolve hold',
+      secondaryAction: 'View invoices',
+      tertiaryAction: 'Dismiss',
+    }]}
+    />
+  )
+}
+
+const SuccessScene: FC = () => {
+  return (
+    <ThemeCardRow cards={[{
+      eyebrow: 'Default scope',
+      title: 'Post-release success state',
+      copy: 'The neutral version keeps the message on the global theme and does not distinguish celebratory follow-up actions.',
+      primaryAction: 'Share update',
+      secondaryAction: 'Review rollout',
+      tertiaryAction: 'Close',
+    }, {
+      eyebrow: 'Success scope',
+      title: 'Post-release success state',
+      copy: 'The success class shifts the local module toward a green palette while keeping the same component API and surface hierarchy.',
+      scopeClassName: 'm3-local-theme m3-local-theme--success',
+      primaryAction: 'Share update',
+      secondaryAction: 'Review rollout',
+      tertiaryAction: 'Close',
+    }]}
+    />
+  )
+}
+
+const BrandMutedScene: FC = () => {
+  return (
+    <ThemeCardRow cards={[{
+      eyebrow: 'Default scope',
+      title: 'Brand guidance callout',
+      copy: 'By default, the card inherits the main theme accent and reads as just another primary action area.',
+      primaryAction: 'Open guidelines',
+      secondaryAction: 'Download assets',
+      tertiaryAction: 'Later',
+    }, {
+      eyebrow: 'Brand-muted scope',
+      title: 'Brand guidance callout',
+      copy: 'The muted brand class keeps a product-colored accent, but softens both controls and surfaces for secondary editorial emphasis.',
+      scopeClassName: 'm3-local-theme m3-local-theme--brand-muted',
+      primaryAction: 'Open guidelines',
+      secondaryAction: 'Download assets',
+      tertiaryAction: 'Later',
+    }]}
+    />
+  )
+}
+
+const NestedScene: FC = () => {
+  return (
+    <M3SurfacePanel
+      className="m3-local-theme-showcase__workspace"
+      fillHeight={false}
+      rounding={32}
+      variant="surface-container-low"
+      elevation={0}
+    >
+      <div className="m3-local-theme-showcase__workspace-header">
+        <div>
+          <div className="m3-local-theme-showcase__eyebrow">Nested local scopes</div>
+          <h2 className="m3-local-theme-showcase__workspace-title">One page, multiple local accents</h2>
+          <p className="m3-local-theme-showcase__copy">
+            The surrounding workspace stays on the global theme while specific modules opt into local token overrides.
+          </p>
+        </div>
+
+        <M3Button appearance="outlined">
+          Publish overview
+        </M3Button>
+      </div>
+
+      <ThemeCardRow cards={[{
+        eyebrow: 'Warm alert scope',
+        title: 'Escalated billing hold',
+        copy: 'This card uses warmer surface tokens to feel urgent without collapsing into an all-red panel.',
+        scopeClassName: 'm3-local-theme m3-local-theme--warm-alert',
+        primaryAction: 'Resolve hold',
+        secondaryAction: 'Notify finance',
+      }, {
+        eyebrow: 'Danger scope',
+        title: 'Delete workspace access',
+        copy: 'A narrower local scope can still switch buttons, supporting copy, and surface tones for destructive actions.',
+        scopeClassName: 'm3-local-theme m3-local-theme--danger',
+        primaryAction: 'Remove access',
+        secondaryAction: 'Review members',
+        tertiaryAction: 'Cancel',
+      }]}
+      />
+    </M3SurfacePanel>
+  )
+}
+
+type LocalThemeShowcaseProps = {
+  variant: LocalThemeVariant
+}
+
+const LocalThemeShowcase: FC<LocalThemeShowcaseProps> = ({ variant }) => {
+  return (
+    <div className="m3-local-theme-showcase">
+      <div className="sb-container-fluid px-6 py-6">
+        <div className="m3-local-theme-showcase__intro mb-6">
+          <div className="m3-local-theme-showcase__eyebrow">Pattern</div>
+          <h1 className="m3-local-theme-showcase__headline">Local token scopes</h1>
+          <p className="m3-local-theme-showcase__copy">
+            Local theming works by attaching a wrapper class that overrides a subset of the Material sys-tokens for descendants only.
+          </p>
+        </div>
+
+        {variant === 'danger' ? <DangerScene /> : null}
+        {variant === 'warm-alert' ? <WarmAlertScene /> : null}
+        {variant === 'success' ? <SuccessScene /> : null}
+        {variant === 'brand-muted' ? <BrandMutedScene /> : null}
+        {variant === 'nested' ? <NestedScene /> : null}
+      </div>
+    </div>
+  )
+}
+
+export default LocalThemeShowcase
diff --git a/m3-react/storybook/examples/local-theme/styles.scss b/m3-react/storybook/examples/local-theme/styles.scss
new file mode 100644
index 0000000..c6450bc
--- /dev/null
+++ b/m3-react/storybook/examples/local-theme/styles.scss
@@ -0,0 +1,352 @@
+.m3-local-theme-showcase {
+  min-height: 100vh;
+  box-sizing: border-box;
+  background:
+    radial-gradient(circle at top left, color-mix(in srgb, var(--m3-sys-primary) 10%, transparent), transparent 32%),
+    linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%);
+  color: var(--m3-sys-on-surface);
+}
+
+.m3-local-theme-showcase__intro {
+  max-width: 720px;
+}
+
+.m3-local-theme-showcase__workspace {
+  padding: 24px;
+}
+
+.m3-local-theme-showcase__workspace > * + * {
+  margin-top: 24px;
+}
+
+.m3-local-theme-showcase__workspace-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: start;
+  gap: 16px;
+}
+
+.m3-local-theme-showcase__workspace-header > :first-child {
+  min-width: 0;
+}
+
+.m3-local-theme-showcase__workspace-header > :first-child > * + * {
+  margin-top: 8px;
+}
+
+.m3-local-theme-showcase__headline,
+.m3-local-theme-showcase__workspace-title,
+.m3-local-theme-showcase__title {
+  margin: 0;
+}
+
+.m3-local-theme-showcase__headline {
+  margin: 20px 0 8px;
+  font-size: 32px;
+  line-height: 40px;
+  font-weight: 400;
+}
+
+.m3-local-theme-showcase__workspace-title {
+  font-size: 24px;
+  line-height: 32px;
+  font-weight: 400;
+}
+
+.m3-local-theme-showcase__title {
+  font-size: 22px;
+  line-height: 28px;
+  font-weight: 400;
+}
+
+.m3-local-theme-showcase__eyebrow {
+  width: fit-content;
+  padding: 6px 10px;
+  border-radius: 999px;
+  font-size: 12px;
+  line-height: 16px;
+  letter-spacing: 0.5px;
+  text-transform: uppercase;
+  font-weight: 500;
+  background: var(--m3-sys-primary-container);
+  color: var(--m3-sys-on-primary-container);
+}
+
+.m3-local-theme-showcase__copy {
+  margin: 0;
+  max-width: 58ch;
+  font-size: 16px;
+  line-height: 24px;
+  letter-spacing: 0.5px;
+  color: var(--m3-sys-on-surface-variant);
+}
+
+.m3-local-theme-showcase__card {
+  min-height: 320px;
+  width: 100%;
+  padding: 24px;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.m3-local-theme-showcase__card > * + * {
+  margin-top: 16px;
+}
+
+.m3-local-theme.m3-local-theme-showcase__card {
+  outline: 1px solid color-mix(in srgb, var(--m3-sys-primary) 32%, transparent);
+  outline-offset: -1px;
+}
+
+.m3-local-theme-showcase__swatches {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.m3-local-theme-showcase__swatch {
+  min-width: 88px;
+  border-radius: 16px;
+  padding: 10px 12px;
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  background: var(--m3-sys-surface-container-low);
+  color: var(--m3-sys-on-surface-variant);
+  font-size: 12px;
+  line-height: 16px;
+  letter-spacing: 0.5px;
+}
+
+.m3-local-theme-showcase__swatch-chip {
+  width: 12px;
+  height: 12px;
+  border-radius: 999px;
+  flex: 0 0 auto;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--m3-sys-on-surface) 12%, transparent);
+}
+
+.m3-local-theme-showcase__swatch-chip_surface {
+  background: var(--m3-sys-surface-container);
+}
+
+.m3-local-theme-showcase__swatch-chip_container {
+  background: var(--m3-sys-secondary-container);
+}
+
+.m3-local-theme-showcase__swatch-chip_accent {
+  background: var(--m3-sys-primary);
+}
+
+.m3-local-theme-showcase__actions {
+  margin-top: auto;
+  padding-top: 24px;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  align-items: center;
+  row-gap: 8px;
+  gap: 12px;
+}
+
+.m3-local-theme {
+  --m3-sys-primary: var(--m3-local-primary);
+  --m3-sys-primary-container: var(--m3-local-primary-container);
+  --m3-sys-on-primary: var(--m3-local-on-primary);
+  --m3-sys-on-primary-container: var(--m3-local-on-primary-container);
+  --m3-sys-secondary-container: var(--m3-local-secondary-container);
+  --m3-sys-on-secondary-container: var(--m3-local-on-secondary-container);
+  --m3-sys-surface: var(--m3-local-surface);
+  --m3-sys-surface-container-low: var(--m3-local-surface-low);
+  --m3-sys-surface-container: var(--m3-local-surface);
+  --m3-sys-surface-container-high: var(--m3-local-surface-high);
+  --m3-sys-surface-container-highest: var(--m3-local-surface-highest);
+  --m3-sys-on-surface: var(--m3-local-on-surface);
+  --m3-sys-on-surface-variant: var(--m3-local-on-surface-variant);
+  --m3-sys-outline: var(--m3-local-outline);
+  --m3-sys-outline-variant: var(--m3-local-outline-variant);
+  --m3-state-layers-on-surface-opacity-008: color-mix(in srgb, var(--m3-local-on-surface) 8%, transparent);
+  --m3-state-layers-on-surface-opacity-012: color-mix(in srgb, var(--m3-local-on-surface) 12%, transparent);
+  --m3-state-layers-on-surface-opacity-020: color-mix(in srgb, var(--m3-local-on-surface) 20%, transparent);
+  --m3-state-layers-on-secondary-container-opacity-008: color-mix(in srgb, var(--m3-local-on-secondary-container) 8%, transparent);
+  --m3-state-layers-on-secondary-container-opacity-012: color-mix(in srgb, var(--m3-local-on-secondary-container) 12%, transparent);
+  --m3-state-layers-on-secondary-container-opacity-020: color-mix(in srgb, var(--m3-local-on-secondary-container) 20%, transparent);
+  color: var(--m3-sys-on-surface);
+}
+
+html.m3-theme-light .m3-local-theme--reset {
+  --m3-local-primary: #6750a4;
+  --m3-local-primary-container: #e9ddff;
+  --m3-local-on-primary: #ffffff;
+  --m3-local-on-primary-container: #22005d;
+  --m3-local-secondary-container: #e8def8;
+  --m3-local-on-secondary-container: #1e192b;
+  --m3-local-surface: #fdf8fd;
+  --m3-local-surface-low: #fef7ff;
+  --m3-local-surface-high: #ece6f0;
+  --m3-local-surface-highest: #e6e0e9;
+  --m3-local-on-surface: #1d1b20;
+  --m3-local-on-surface-variant: #49454f;
+  --m3-local-outline: #79747e;
+  --m3-local-outline-variant: #cac4d0;
+}
+
+html.m3-theme-dark .m3-local-theme--reset {
+  --m3-local-primary: #cfbcff;
+  --m3-local-primary-container: #4f378a;
+  --m3-local-on-primary: #381e72;
+  --m3-local-on-primary-container: #e9ddff;
+  --m3-local-secondary-container: #4a4458;
+  --m3-local-on-secondary-container: #e8def8;
+  --m3-local-surface: #141218;
+  --m3-local-surface-low: #1d1b20;
+  --m3-local-surface-high: #2b2930;
+  --m3-local-surface-highest: #36343b;
+  --m3-local-on-surface: #e6e0e9;
+  --m3-local-on-surface-variant: #cac4d0;
+  --m3-local-outline: #938f99;
+  --m3-local-outline-variant: #49454f;
+}
+
+html.m3-theme-light .m3-local-theme--danger {
+  --m3-local-primary: #b42346;
+  --m3-local-primary-container: #ffd9e2;
+  --m3-local-on-primary: #ffffff;
+  --m3-local-on-primary-container: #400011;
+  --m3-local-secondary-container: #f7dce4;
+  --m3-local-on-secondary-container: #5b1024;
+  --m3-local-surface: #fdf0f4;
+  --m3-local-surface-low: #fff8fa;
+  --m3-local-surface-high: #f8dfe7;
+  --m3-local-surface-highest: #efc9d4;
+  --m3-local-on-surface: #34111a;
+  --m3-local-on-surface-variant: #71414e;
+  --m3-local-outline: #a37883;
+  --m3-local-outline-variant: #dfb8c2;
+}
+
+html.m3-theme-dark .m3-local-theme--danger {
+  --m3-local-primary: #ff9db8;
+  --m3-local-primary-container: #7e263f;
+  --m3-local-on-primary: #491323;
+  --m3-local-on-primary-container: #ffdbe3;
+  --m3-local-secondary-container: #653745;
+  --m3-local-on-secondary-container: #f7dbe3;
+  --m3-local-surface: #312129;
+  --m3-local-surface-low: #2a1b22;
+  --m3-local-surface-high: #38252d;
+  --m3-local-surface-highest: #46303a;
+  --m3-local-on-surface: #f2dfe4;
+  --m3-local-on-surface-variant: #d6c2c8;
+  --m3-local-outline: #ae8c97;
+  --m3-local-outline-variant: #62424d;
+}
+
+html.m3-theme-light .m3-local-theme--warm-alert {
+  --m3-local-primary: #8a4f00;
+  --m3-local-primary-container: #ffddb8;
+  --m3-local-on-primary: #ffffff;
+  --m3-local-on-primary-container: #2c1600;
+  --m3-local-secondary-container: #f3dfcf;
+  --m3-local-on-secondary-container: #37281b;
+  --m3-local-surface: #fef1e5;
+  --m3-local-surface-low: #fff8f1;
+  --m3-local-surface-high: #f8e1cc;
+  --m3-local-surface-highest: #efd0b2;
+  --m3-local-on-surface: #2f1b0d;
+  --m3-local-on-surface-variant: #6c5647;
+  --m3-local-outline: #9a7e69;
+  --m3-local-outline-variant: #dbc1ab;
+}
+
+html.m3-theme-dark .m3-local-theme--warm-alert {
+  --m3-local-primary: #f1be79;
+  --m3-local-primary-container: #6d4d1e;
+  --m3-local-on-primary: #3f2806;
+  --m3-local-on-primary-container: #ffe1c2;
+  --m3-local-secondary-container: #5e4835;
+  --m3-local-on-secondary-container: #f3e0d1;
+  --m3-local-surface: #31261d;
+  --m3-local-surface-low: #2a2018;
+  --m3-local-surface-high: #382b22;
+  --m3-local-surface-highest: #46362a;
+  --m3-local-on-surface: #efe0d2;
+  --m3-local-on-surface-variant: #d3c3b5;
+  --m3-local-outline: #ac9177;
+  --m3-local-outline-variant: #5f4937;
+}
+
+html.m3-theme-light .m3-local-theme--success {
+  --m3-local-primary: #146c2e;
+  --m3-local-primary-container: #c2efc8;
+  --m3-local-on-primary: #ffffff;
+  --m3-local-on-primary-container: #00210c;
+  --m3-local-secondary-container: #d6ead5;
+  --m3-local-on-secondary-container: #183723;
+  --m3-local-surface: #eef8ee;
+  --m3-local-surface-low: #f7fdf6;
+  --m3-local-surface-high: #dcefdc;
+  --m3-local-surface-highest: #c6dfc7;
+  --m3-local-on-surface: #132017;
+  --m3-local-on-surface-variant: #3f5343;
+  --m3-local-outline: #6f8873;
+  --m3-local-outline-variant: #bed4c0;
+}
+
+html.m3-theme-dark .m3-local-theme--success {
+  --m3-local-primary: #9ad7ac;
+  --m3-local-primary-container: #245b37;
+  --m3-local-on-primary: #112f1c;
+  --m3-local-on-primary-container: #d3f0d8;
+  --m3-local-secondary-container: #334d3d;
+  --m3-local-on-secondary-container: #dce9de;
+  --m3-local-surface: #202924;
+  --m3-local-surface-low: #1a231e;
+  --m3-local-surface-high: #27312c;
+  --m3-local-surface-highest: #313d37;
+  --m3-local-on-surface: #dce7de;
+  --m3-local-on-surface-variant: #c0cbc2;
+  --m3-local-outline: #90a592;
+  --m3-local-outline-variant: #45594a;
+}
+
+html.m3-theme-light .m3-local-theme--brand-muted {
+  --m3-local-primary: #615b8f;
+  --m3-local-primary-container: #e7e0ff;
+  --m3-local-on-primary: #ffffff;
+  --m3-local-on-primary-container: #1d1738;
+  --m3-local-secondary-container: #e1ddf1;
+  --m3-local-on-secondary-container: #302c45;
+  --m3-local-surface: #f3f1fa;
+  --m3-local-surface-low: #fbf8ff;
+  --m3-local-surface-high: #e5e1f1;
+  --m3-local-surface-highest: #d7d2e4;
+  --m3-local-on-surface: #1d1b28;
+  --m3-local-on-surface-variant: #555266;
+  --m3-local-outline: #868098;
+  --m3-local-outline-variant: #d1ccdf;
+}
+
+html.m3-theme-dark .m3-local-theme--brand-muted {
+  --m3-local-primary: #b7c8e8;
+  --m3-local-primary-container: #44526c;
+  --m3-local-on-primary: #25324b;
+  --m3-local-on-primary-container: #e4e9f6;
+  --m3-local-secondary-container: #3b4558;
+  --m3-local-on-secondary-container: #e0e4ee;
+  --m3-local-surface: #232837;
+  --m3-local-surface-low: #1d2230;
+  --m3-local-surface-high: #2a3040;
+  --m3-local-surface-highest: #343c4d;
+  --m3-local-on-surface: #e2e6ef;
+  --m3-local-on-surface-variant: #c6cdd9;
+  --m3-local-outline: #909eb8;
+  --m3-local-outline-variant: #485162;
+}
+
+@media (max-width: 720px) {
+  .m3-local-theme-showcase__workspace-header {
+    flex-direction: column;
+  }
+}
diff --git a/m3-react/storybook/patterns/LocalTheming.stories.tsx b/m3-react/storybook/patterns/LocalTheming.stories.tsx
new file mode 100644
index 0000000..15d534b
--- /dev/null
+++ b/m3-react/storybook/patterns/LocalTheming.stories.tsx
@@ -0,0 +1,39 @@
+import type {
+  Meta,
+  StoryObj,
+} from '@storybook/react'
+
+import LocalThemeShowcase from '../examples/local-theme/LocalThemeShowcase'
+
+import '../examples/local-theme/styles.scss'
+
+const meta = {
+  title: 'Patterns/Local Theming',
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const DangerActionScope: Story = {
+  render: () => <LocalThemeShowcase variant="danger" />,
+}
+
+export const WarmAlertScope: Story = {
+  render: () => <LocalThemeShowcase variant="warm-alert" />,
+}
+
+export const SuccessScope: Story = {
+  render: () => <LocalThemeShowcase variant="success" />,
+}
+
+export const BrandMutedScope: Story = {
+  render: () => <LocalThemeShowcase variant="brand-muted" />,
+}
+
+export const NestedLocalScopes: Story = {
+  render: () => <LocalThemeShowcase variant="nested" />,
+}
diff --git a/m3-react/storybook/preview.ts b/m3-react/storybook/preview.ts
index a22d3b9..45bb8a0 100644
--- a/m3-react/storybook/preview.ts
+++ b/m3-react/storybook/preview.ts
@@ -2,8 +2,7 @@ import type { Preview, ReactRenderer } from '@storybook/react'
 
 import '@modulify/m3-foundation/assets/stylesheets/normalize.scss'
 import '@modulify/m3-foundation/assets/stylesheets/index.scss'
-
-import './stylesheets/utils.scss'
+import '@modulify/m3-foundation/assets/stylesheets/storybook/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
diff --git a/m3-react/storybook/stylesheets/utils.scss b/m3-react/storybook/stylesheets/utils.scss
deleted file mode 100644
index 6b1f7f2..0000000
--- a/m3-react/storybook/stylesheets/utils.scss
+++ /dev/null
@@ -1,62 +0,0 @@
-.d-block { display: block !important; }
-.d-inline { display: inline !important; }
-.d-inline-block { display: inline-block !important; }
-.d-none { display: none !important; }
-.d-flex { display: flex !important; }
-
-.flex-wrap {
-  flex-wrap: wrap !important;
-}
-
-.flex-container {
-  @extend .d-flex;
-  @extend .flex-wrap;
-}
-
-.flex-row {
-  @extend .d-flex;
-  align-items: center;
-}
-
-.mt-auto, .my-auto, .m-auto { margin-top: auto !important; }
-.mb-auto, .my-auto, .m-auto { margin-bottom: auto !important; }
-.ml-auto, .mx-auto, .m-auto { margin-left: auto !important; }
-.mr-auto, .mx-auto, .m-auto { margin-right: auto !important; }
-
-.mt-0, .my-0, .m-0 { margin-top: 0 !important; }
-.mb-0, .my-0, .m-0 { margin-bottom: 0 !important; }
-.ml-0, .mx-0, .m-0 { margin-left: 0 !important; }
-.mr-0, .mx-0, .m-0 { margin-right: 0 !important; }
-
-.pt-0, .py-0, .p-0 { padding-top: 0 !important; }
-.pb-0, .py-0, .p-0 { padding-bottom: 0 !important; }
-.pl-0, .px-0, .p-0 { padding-left: 0 !important; }
-.pr-0, .px-0, .p-0 { padding-right: 0 !important; }
-
-$base: 8px;
-$multipliers: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10;
-
-@each $value in $multipliers {
-  .mt-#{$value}, .my-#{$value}, .m-#{$value} { margin-top:    0.5 * $value * $base !important; }
-  .mb-#{$value}, .my-#{$value}, .m-#{$value} { margin-bottom: 0.5 * $value * $base !important; }
-  .ml-#{$value}, .mx-#{$value}, .m-#{$value} { margin-left:   0.5 * $value * $base !important; }
-  .mr-#{$value}, .mx-#{$value}, .m-#{$value} { margin-right:  0.5 * $value * $base !important; }
-
-  .mt-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-top:    -0.5 * $value * $base !important; }
-  .mb-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-bottom: -0.5 * $value * $base !important; }
-  .ml-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-left:   -0.5 * $value * $base !important; }
-  .mr-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-right:  -0.5 * $value * $base !important; }
-
-  .pt-#{$value}, .py-#{$value}, .p-#{$value} { padding-top:    0.5 * $value * $base !important; }
-  .pb-#{$value}, .py-#{$value}, .p-#{$value} { padding-bottom: 0.5 * $value * $base !important; }
-  .pl-#{$value}, .px-#{$value}, .p-#{$value} { padding-left:   0.5 * $value * $base !important; }
-  .pr-#{$value}, .px-#{$value}, .p-#{$value} { padding-right:  0.5 * $value * $base !important; }
-}
-
-.mw-100 {
-  max-width: 100% !important;
-}
-
-.w-100 {
-  width: 100% !important;
-}
\ No newline at end of file
diff --git a/m3-vue/storybook/examples/local-theme/LocalThemeShowcase.vue b/m3-vue/storybook/examples/local-theme/LocalThemeShowcase.vue
new file mode 100644
index 0000000..ec4bff0
--- /dev/null
+++ b/m3-vue/storybook/examples/local-theme/LocalThemeShowcase.vue
@@ -0,0 +1,875 @@
+<template>
+    <div class="m3-local-theme-showcase">
+        <div class="sb-container-fluid px-6 py-6">
+            <div class="m3-local-theme-showcase__intro mb-6">
+                <div class="m3-local-theme-showcase__eyebrow">
+                    Pattern
+                </div>
+                <h1 class="m3-local-theme-showcase__headline">
+                    Local token scopes
+                </h1>
+                <p class="m3-local-theme-showcase__copy">
+                    Local theming works by attaching a wrapper class that overrides a subset of the Material sys-tokens for descendants only.
+                </p>
+            </div>
+
+            <div v-if="variant === 'danger'" class="sb-row sb-g-5">
+                <div v-for="card in dangerCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                    <M3SurfacePanel
+                        :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                        :fill-height="false"
+                        :rounding="28"
+                        variant="surface-container-high"
+                        :elevation="1"
+                    >
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            {{ card.eyebrow }}
+                        </div>
+                        <h3 class="m3-local-theme-showcase__title">
+                            {{ card.title }}
+                        </h3>
+                        <p class="m3-local-theme-showcase__copy">
+                            {{ card.copy }}
+                        </p>
+
+                        <div class="m3-local-theme-showcase__swatches">
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                <span>Surface</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                <span>Container</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                <span>Accent</span>
+                            </div>
+                        </div>
+
+                        <div class="m3-local-theme-showcase__actions">
+                            <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                <M3Button appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+                            </span>
+
+                            <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                {{ card.tertiaryAction }}
+                            </M3Button>
+
+                            <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                {{ card.secondaryAction }}
+                            </M3Button>
+
+                            <M3Button appearance="filled">
+                                {{ card.primaryAction }}
+                            </M3Button>
+                        </div>
+                    </M3SurfacePanel>
+                </div>
+            </div>
+
+            <div v-if="variant === 'danger'" class="sb-row sb-g-5 mt-5">
+                <div v-for="card in dangerResetCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                    <M3SurfacePanel
+                        :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                        :fill-height="false"
+                        :rounding="28"
+                        variant="surface-container-high"
+                        :elevation="1"
+                    >
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            {{ card.eyebrow }}
+                        </div>
+                        <h3 class="m3-local-theme-showcase__title">
+                            {{ card.title }}
+                        </h3>
+                        <p class="m3-local-theme-showcase__copy">
+                            {{ card.copy }}
+                        </p>
+
+                        <div class="m3-local-theme-showcase__swatches">
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                <span>Surface</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                <span>Container</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                <span>Accent</span>
+                            </div>
+                        </div>
+
+                        <div class="m3-local-theme-showcase__actions">
+                            <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                <M3Button appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+                            </span>
+
+                            <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                {{ card.tertiaryAction }}
+                            </M3Button>
+
+                            <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                {{ card.secondaryAction }}
+                            </M3Button>
+
+                            <M3Button appearance="filled">
+                                {{ card.primaryAction }}
+                            </M3Button>
+                        </div>
+                    </M3SurfacePanel>
+                </div>
+            </div>
+
+            <div v-else-if="variant === 'warm-alert'" class="sb-row sb-g-5">
+                <div v-for="card in warmCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                    <M3SurfacePanel
+                        :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                        :fill-height="false"
+                        :rounding="28"
+                        variant="surface-container-high"
+                        :elevation="1"
+                    >
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            {{ card.eyebrow }}
+                        </div>
+                        <h3 class="m3-local-theme-showcase__title">
+                            {{ card.title }}
+                        </h3>
+                        <p class="m3-local-theme-showcase__copy">
+                            {{ card.copy }}
+                        </p>
+
+                        <div class="m3-local-theme-showcase__swatches">
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                <span>Surface</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                <span>Container</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                <span>Accent</span>
+                            </div>
+                        </div>
+
+                        <div class="m3-local-theme-showcase__actions">
+                            <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                <M3Button appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+                            </span>
+
+                            <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                {{ card.tertiaryAction }}
+                            </M3Button>
+
+                            <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                {{ card.secondaryAction }}
+                            </M3Button>
+
+                            <M3Button appearance="filled">
+                                {{ card.primaryAction }}
+                            </M3Button>
+                        </div>
+                    </M3SurfacePanel>
+                </div>
+            </div>
+
+            <div v-else-if="variant === 'success'" class="sb-row sb-g-5">
+                <div v-for="card in successCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                    <M3SurfacePanel
+                        :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                        :fill-height="false"
+                        :rounding="28"
+                        variant="surface-container-high"
+                        :elevation="1"
+                    >
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            {{ card.eyebrow }}
+                        </div>
+                        <h3 class="m3-local-theme-showcase__title">
+                            {{ card.title }}
+                        </h3>
+                        <p class="m3-local-theme-showcase__copy">
+                            {{ card.copy }}
+                        </p>
+
+                        <div class="m3-local-theme-showcase__swatches">
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                <span>Surface</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                <span>Container</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                <span>Accent</span>
+                            </div>
+                        </div>
+
+                        <div class="m3-local-theme-showcase__actions">
+                            <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                <M3Button appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+                            </span>
+
+                            <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                {{ card.tertiaryAction }}
+                            </M3Button>
+
+                            <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                {{ card.secondaryAction }}
+                            </M3Button>
+
+                            <M3Button appearance="filled">
+                                {{ card.primaryAction }}
+                            </M3Button>
+                        </div>
+                    </M3SurfacePanel>
+                </div>
+            </div>
+
+            <div v-else-if="variant === 'brand-muted'" class="sb-row sb-g-5">
+                <div v-for="card in brandMutedCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                    <M3SurfacePanel
+                        :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                        :fill-height="false"
+                        :rounding="28"
+                        variant="surface-container-high"
+                        :elevation="1"
+                    >
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            {{ card.eyebrow }}
+                        </div>
+                        <h3 class="m3-local-theme-showcase__title">
+                            {{ card.title }}
+                        </h3>
+                        <p class="m3-local-theme-showcase__copy">
+                            {{ card.copy }}
+                        </p>
+
+                        <div class="m3-local-theme-showcase__swatches">
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                <span>Surface</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                <span>Container</span>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__swatch">
+                                <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                <span>Accent</span>
+                            </div>
+                        </div>
+
+                        <div class="m3-local-theme-showcase__actions">
+                            <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                <M3Button appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+                            </span>
+
+                            <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                {{ card.tertiaryAction }}
+                            </M3Button>
+
+                            <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                {{ card.secondaryAction }}
+                            </M3Button>
+
+                            <M3Button appearance="filled">
+                                {{ card.primaryAction }}
+                            </M3Button>
+                        </div>
+                    </M3SurfacePanel>
+                </div>
+            </div>
+
+            <M3SurfacePanel
+                v-else
+                class="m3-local-theme-showcase__workspace"
+                :fill-height="false"
+                :rounding="32"
+                variant="surface-container-low"
+                :elevation="0"
+            >
+                <div class="m3-local-theme-showcase__workspace-header">
+                    <div>
+                        <div class="m3-local-theme-showcase__eyebrow">
+                            Nested local scopes
+                        </div>
+                        <h2 class="m3-local-theme-showcase__workspace-title">
+                            One page, multiple local accents
+                        </h2>
+                        <p class="m3-local-theme-showcase__copy">
+                            The surrounding workspace stays on the global theme while specific modules opt into local token overrides.
+                        </p>
+                    </div>
+
+                    <M3Button appearance="outlined">
+                        Publish overview
+                    </M3Button>
+                </div>
+
+                <div class="sb-row sb-g-5">
+                    <div v-for="card in nestedCards" :key="card.eyebrow" class="sb-col-12 sb-col-lg-6 d-flex">
+                        <M3SurfacePanel
+                            :class="['m3-local-theme-showcase__card', 'h-100', card.scopeClassName]"
+                            :fill-height="false"
+                            :rounding="28"
+                            variant="surface-container-high"
+                            :elevation="1"
+                        >
+                            <div class="m3-local-theme-showcase__eyebrow">
+                                {{ card.eyebrow }}
+                            </div>
+                            <h3 class="m3-local-theme-showcase__title">
+                                {{ card.title }}
+                            </h3>
+                            <p class="m3-local-theme-showcase__copy">
+                                {{ card.copy }}
+                            </p>
+
+                            <div class="m3-local-theme-showcase__swatches">
+                                <div class="m3-local-theme-showcase__swatch">
+                                    <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_surface" />
+                                    <span>Surface</span>
+                                </div>
+
+                                <div class="m3-local-theme-showcase__swatch">
+                                    <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_container" />
+                                    <span>Container</span>
+                                </div>
+
+                                <div class="m3-local-theme-showcase__swatch">
+                                    <span class="m3-local-theme-showcase__swatch-chip m3-local-theme-showcase__swatch-chip_accent" />
+                                    <span>Accent</span>
+                                </div>
+                            </div>
+
+                            <div class="m3-local-theme-showcase__actions">
+                                <span v-if="card.tertiaryAction && card.tertiaryScopeClassName" :class="card.tertiaryScopeClassName">
+                                    <M3Button appearance="text">
+                                        {{ card.tertiaryAction }}
+                                    </M3Button>
+                                </span>
+
+                                <M3Button v-else-if="card.tertiaryAction" appearance="text">
+                                    {{ card.tertiaryAction }}
+                                </M3Button>
+
+                                <M3Button v-if="card.secondaryAction" appearance="tonal">
+                                    {{ card.secondaryAction }}
+                                </M3Button>
+
+                                <M3Button appearance="filled">
+                                    {{ card.primaryAction }}
+                                </M3Button>
+                            </div>
+                        </M3SurfacePanel>
+                    </div>
+                </div>
+            </M3SurfacePanel>
+        </div>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { M3Button } from '@/components/button'
+import { M3SurfacePanel } from '@/components/surface'
+
+const props = defineProps<{
+  variant: 'danger' | 'warm-alert' | 'success' | 'brand-muted' | 'nested'
+}>()
+
+defineOptions({
+  name: 'LocalThemeShowcase',
+})
+
+type ThemeCardProps = {
+  eyebrow: string
+  title: string
+  copy: string
+  scopeClassName?: string
+  primaryAction: string
+  secondaryAction?: string
+  tertiaryAction?: string
+  tertiaryScopeClassName?: string
+}
+
+const dangerCards: ThemeCardProps[] = [{
+  eyebrow: 'Default scope',
+  title: 'Default destructive action',
+  copy: 'Without a local theme, the same controls stay on the global primary palette and neutral surface tokens.',
+  primaryAction: 'Delete release',
+  secondaryAction: 'Review logs',
+  tertiaryAction: 'Cancel',
+}, {
+  eyebrow: 'Danger scope',
+  title: 'Locally themed destructive action',
+  copy: 'A single wrapper class re-targets the same button and surface tokens to a red destructive palette with a warmer supporting surface.',
+  scopeClassName: 'm3-local-theme m3-local-theme--danger',
+  primaryAction: 'Delete release',
+  secondaryAction: 'Review logs',
+  tertiaryAction: 'Cancel',
+}]
+
+const warmCards: ThemeCardProps[] = [{
+  eyebrow: 'Default scope',
+  title: 'Billing reminder card',
+  copy: 'The neutral version uses the baseline surface hierarchy from the active global theme.',
+  primaryAction: 'Resolve hold',
+  secondaryAction: 'View invoices',
+  tertiaryAction: 'Dismiss',
+}, {
+  eyebrow: 'Warm alert scope',
+  title: 'Billing reminder card',
+  copy: 'The local alert class shifts the panel into a warmer family and retargets tonal and filled buttons without affecting the surrounding page.',
+  scopeClassName: 'm3-local-theme m3-local-theme--warm-alert',
+  primaryAction: 'Resolve hold',
+  secondaryAction: 'View invoices',
+  tertiaryAction: 'Dismiss',
+}]
+
+const dangerResetCards: ThemeCardProps[] = [{
+  eyebrow: 'Danger scope + reset action',
+  title: 'Locally themed destructive action',
+  copy: 'Nested reset scope restores the baseline global theme inside a danger module, so a single supporting action can fall back to the default button language.',
+  scopeClassName: 'm3-local-theme m3-local-theme--danger',
+  primaryAction: 'Delete release',
+  secondaryAction: 'Review logs',
+  tertiaryAction: 'Cancel',
+  tertiaryScopeClassName: 'm3-local-theme m3-local-theme--reset',
+}]
+
+const successCards: ThemeCardProps[] = [{
+  eyebrow: 'Default scope',
+  title: 'Post-release success state',
+  copy: 'The neutral version keeps the message on the global theme and does not distinguish celebratory follow-up actions.',
+  primaryAction: 'Share update',
+  secondaryAction: 'Review rollout',
+  tertiaryAction: 'Close',
+}, {
+  eyebrow: 'Success scope',
+  title: 'Post-release success state',
+  copy: 'The success class shifts the local module toward a green palette while keeping the same component API and surface hierarchy.',
+  scopeClassName: 'm3-local-theme m3-local-theme--success',
+  primaryAction: 'Share update',
+  secondaryAction: 'Review rollout',
+  tertiaryAction: 'Close',
+}]
+
+const brandMutedCards: ThemeCardProps[] = [{
+  eyebrow: 'Default scope',
+  title: 'Brand guidance callout',
+  copy: 'By default, the card inherits the main theme accent and reads as just another primary action area.',
+  primaryAction: 'Open guidelines',
+  secondaryAction: 'Download assets',
+  tertiaryAction: 'Later',
+}, {
+  eyebrow: 'Brand-muted scope',
+  title: 'Brand guidance callout',
+  copy: 'The muted brand class keeps a product-colored accent, but softens both controls and surfaces for secondary editorial emphasis.',
+  scopeClassName: 'm3-local-theme m3-local-theme--brand-muted',
+  primaryAction: 'Open guidelines',
+  secondaryAction: 'Download assets',
+  tertiaryAction: 'Later',
+}]
+
+const nestedCards: ThemeCardProps[] = [{
+  eyebrow: 'Warm alert scope',
+  title: 'Escalated billing hold',
+  copy: 'This card uses warmer surface tokens to feel urgent without collapsing into an all-red panel.',
+  scopeClassName: 'm3-local-theme m3-local-theme--warm-alert',
+  primaryAction: 'Resolve hold',
+  secondaryAction: 'Notify finance',
+}, {
+  eyebrow: 'Danger scope',
+  title: 'Delete workspace access',
+  copy: 'A narrower local scope can still switch buttons, supporting copy, and surface tones for destructive actions.',
+  scopeClassName: 'm3-local-theme m3-local-theme--danger',
+  primaryAction: 'Remove access',
+  secondaryAction: 'Review members',
+  tertiaryAction: 'Cancel',
+}]
+
+void props.variant
+</script>
+
+<style>
+.m3-local-theme-showcase {
+    min-height: 100vh;
+    box-sizing: border-box;
+    background:
+        radial-gradient(circle at top left, color-mix(in srgb, var(--m3-sys-primary) 10%, transparent), transparent 32%),
+        linear-gradient(180deg, var(--m3-sys-surface) 0%, var(--m3-sys-surface-container-low) 100%);
+    color: var(--m3-sys-on-surface);
+}
+
+.m3-local-theme-showcase__intro {
+    max-width: 720px;
+}
+
+.m3-local-theme-showcase__workspace {
+    padding: 24px;
+}
+
+.m3-local-theme-showcase__workspace > * + * {
+    margin-top: 24px;
+}
+
+.m3-local-theme-showcase__workspace-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: start;
+    gap: 16px;
+}
+
+.m3-local-theme-showcase__workspace-header > :first-child {
+    min-width: 0;
+}
+
+.m3-local-theme-showcase__workspace-header > :first-child > * + * {
+    margin-top: 8px;
+}
+
+.m3-local-theme-showcase__headline,
+.m3-local-theme-showcase__workspace-title,
+.m3-local-theme-showcase__title {
+    margin: 0;
+}
+
+.m3-local-theme-showcase__headline {
+    margin: 20px 0 8px;
+    font-size: 32px;
+    line-height: 40px;
+    font-weight: 400;
+}
+
+.m3-local-theme-showcase__workspace-title {
+    font-size: 24px;
+    line-height: 32px;
+    font-weight: 400;
+}
+
+.m3-local-theme-showcase__title {
+    font-size: 22px;
+    line-height: 28px;
+    font-weight: 400;
+}
+
+.m3-local-theme-showcase__eyebrow {
+    width: fit-content;
+    padding: 6px 10px;
+    border-radius: 999px;
+    font-size: 12px;
+    line-height: 16px;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+    font-weight: 500;
+    background: var(--m3-sys-primary-container);
+    color: var(--m3-sys-on-primary-container);
+}
+
+.m3-local-theme-showcase__copy {
+    margin: 0;
+    max-width: 58ch;
+    font-size: 16px;
+    line-height: 24px;
+    letter-spacing: 0.5px;
+    color: var(--m3-sys-on-surface-variant);
+}
+
+.m3-local-theme-showcase__card {
+    min-height: 320px;
+    width: 100%;
+    padding: 24px;
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+}
+
+.m3-local-theme-showcase__card > * + * {
+    margin-top: 16px;
+}
+
+.m3-local-theme.m3-local-theme-showcase__card {
+    outline: 1px solid color-mix(in srgb, var(--m3-sys-primary) 32%, transparent);
+    outline-offset: -1px;
+}
+
+.m3-local-theme-showcase__swatches {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+}
+
+.m3-local-theme-showcase__swatch {
+    min-width: 88px;
+    border-radius: 16px;
+    padding: 10px 12px;
+    display: inline-flex;
+    align-items: center;
+    gap: 10px;
+    background: var(--m3-sys-surface-container-low);
+    color: var(--m3-sys-on-surface-variant);
+    font-size: 12px;
+    line-height: 16px;
+    letter-spacing: 0.5px;
+}
+
+.m3-local-theme-showcase__swatch-chip {
+    width: 12px;
+    height: 12px;
+    border-radius: 999px;
+    flex: 0 0 auto;
+    box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--m3-sys-on-surface) 12%, transparent);
+}
+
+.m3-local-theme-showcase__swatch-chip_surface {
+    background: var(--m3-sys-surface-container);
+}
+
+.m3-local-theme-showcase__swatch-chip_container {
+    background: var(--m3-sys-secondary-container);
+}
+
+.m3-local-theme-showcase__swatch-chip_accent {
+    background: var(--m3-sys-primary);
+}
+
+.m3-local-theme-showcase__actions {
+    margin-top: auto;
+    padding-top: 24px;
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    align-items: center;
+    row-gap: 8px;
+    gap: 12px;
+}
+
+.m3-local-theme {
+    --m3-sys-primary: var(--m3-local-primary);
+    --m3-sys-primary-container: var(--m3-local-primary-container);
+    --m3-sys-on-primary: var(--m3-local-on-primary);
+    --m3-sys-on-primary-container: var(--m3-local-on-primary-container);
+    --m3-sys-secondary-container: var(--m3-local-secondary-container);
+    --m3-sys-on-secondary-container: var(--m3-local-on-secondary-container);
+    --m3-sys-surface: var(--m3-local-surface);
+    --m3-sys-surface-container-low: var(--m3-local-surface-low);
+    --m3-sys-surface-container: var(--m3-local-surface);
+    --m3-sys-surface-container-high: var(--m3-local-surface-high);
+    --m3-sys-surface-container-highest: var(--m3-local-surface-highest);
+    --m3-sys-on-surface: var(--m3-local-on-surface);
+    --m3-sys-on-surface-variant: var(--m3-local-on-surface-variant);
+    --m3-sys-outline: var(--m3-local-outline);
+    --m3-sys-outline-variant: var(--m3-local-outline-variant);
+    --m3-state-layers-on-surface-opacity-008: color-mix(in srgb, var(--m3-local-on-surface) 8%, transparent);
+    --m3-state-layers-on-surface-opacity-012: color-mix(in srgb, var(--m3-local-on-surface) 12%, transparent);
+    --m3-state-layers-on-surface-opacity-020: color-mix(in srgb, var(--m3-local-on-surface) 20%, transparent);
+    --m3-state-layers-on-secondary-container-opacity-008: color-mix(in srgb, var(--m3-local-on-secondary-container) 8%, transparent);
+    --m3-state-layers-on-secondary-container-opacity-012: color-mix(in srgb, var(--m3-local-on-secondary-container) 12%, transparent);
+    --m3-state-layers-on-secondary-container-opacity-020: color-mix(in srgb, var(--m3-local-on-secondary-container) 20%, transparent);
+    color: var(--m3-sys-on-surface);
+}
+
+html.m3-theme-light .m3-local-theme--reset {
+    --m3-local-primary: #6750a4;
+    --m3-local-primary-container: #e9ddff;
+    --m3-local-on-primary: #ffffff;
+    --m3-local-on-primary-container: #22005d;
+    --m3-local-secondary-container: #e8def8;
+    --m3-local-on-secondary-container: #1e192b;
+    --m3-local-surface: #fdf8fd;
+    --m3-local-surface-low: #fef7ff;
+    --m3-local-surface-high: #ece6f0;
+    --m3-local-surface-highest: #e6e0e9;
+    --m3-local-on-surface: #1d1b20;
+    --m3-local-on-surface-variant: #49454f;
+    --m3-local-outline: #79747e;
+    --m3-local-outline-variant: #cac4d0;
+}
+
+html.m3-theme-dark .m3-local-theme--reset {
+    --m3-local-primary: #cfbcff;
+    --m3-local-primary-container: #4f378a;
+    --m3-local-on-primary: #381e72;
+    --m3-local-on-primary-container: #e9ddff;
+    --m3-local-secondary-container: #4a4458;
+    --m3-local-on-secondary-container: #e8def8;
+    --m3-local-surface: #141218;
+    --m3-local-surface-low: #1d1b20;
+    --m3-local-surface-high: #2b2930;
+    --m3-local-surface-highest: #36343b;
+    --m3-local-on-surface: #e6e0e9;
+    --m3-local-on-surface-variant: #cac4d0;
+    --m3-local-outline: #938f99;
+    --m3-local-outline-variant: #49454f;
+}
+
+html.m3-theme-light .m3-local-theme--danger {
+    --m3-local-primary: #b42346;
+    --m3-local-primary-container: #ffd9e2;
+    --m3-local-on-primary: #ffffff;
+    --m3-local-on-primary-container: #400011;
+    --m3-local-secondary-container: #f7dce4;
+    --m3-local-on-secondary-container: #5b1024;
+    --m3-local-surface: #fdf0f4;
+    --m3-local-surface-low: #fff8fa;
+    --m3-local-surface-high: #f8dfe7;
+    --m3-local-surface-highest: #efc9d4;
+    --m3-local-on-surface: #34111a;
+    --m3-local-on-surface-variant: #71414e;
+    --m3-local-outline: #a37883;
+    --m3-local-outline-variant: #dfb8c2;
+}
+
+html.m3-theme-dark .m3-local-theme--danger {
+    --m3-local-primary: #ff9db8;
+    --m3-local-primary-container: #7e263f;
+    --m3-local-on-primary: #491323;
+    --m3-local-on-primary-container: #ffdbe3;
+    --m3-local-secondary-container: #653745;
+    --m3-local-on-secondary-container: #f7dbe3;
+    --m3-local-surface: #312129;
+    --m3-local-surface-low: #2a1b22;
+    --m3-local-surface-high: #38252d;
+    --m3-local-surface-highest: #46303a;
+    --m3-local-on-surface: #f2dfe4;
+    --m3-local-on-surface-variant: #d6c2c8;
+    --m3-local-outline: #ae8c97;
+    --m3-local-outline-variant: #62424d;
+}
+
+html.m3-theme-light .m3-local-theme--warm-alert {
+    --m3-local-primary: #8a4f00;
+    --m3-local-primary-container: #ffddb8;
+    --m3-local-on-primary: #ffffff;
+    --m3-local-on-primary-container: #2c1600;
+    --m3-local-secondary-container: #f3dfcf;
+    --m3-local-on-secondary-container: #37281b;
+    --m3-local-surface: #fef1e5;
+    --m3-local-surface-low: #fff8f1;
+    --m3-local-surface-high: #f8e1cc;
+    --m3-local-surface-highest: #efd0b2;
+    --m3-local-on-surface: #2f1b0d;
+    --m3-local-on-surface-variant: #6c5647;
+    --m3-local-outline: #9a7e69;
+    --m3-local-outline-variant: #dbc1ab;
+}
+
+html.m3-theme-dark .m3-local-theme--warm-alert {
+    --m3-local-primary: #f1be79;
+    --m3-local-primary-container: #6d4d1e;
+    --m3-local-on-primary: #3f2806;
+    --m3-local-on-primary-container: #ffe1c2;
+    --m3-local-secondary-container: #5e4835;
+    --m3-local-on-secondary-container: #f3e0d1;
+    --m3-local-surface: #31261d;
+    --m3-local-surface-low: #2a2018;
+    --m3-local-surface-high: #382b22;
+    --m3-local-surface-highest: #46362a;
+    --m3-local-on-surface: #efe0d2;
+    --m3-local-on-surface-variant: #d3c3b5;
+    --m3-local-outline: #ac9177;
+    --m3-local-outline-variant: #5f4937;
+}
+
+html.m3-theme-light .m3-local-theme--success {
+    --m3-local-primary: #146c2e;
+    --m3-local-primary-container: #c2efc8;
+    --m3-local-on-primary: #ffffff;
+    --m3-local-on-primary-container: #00210c;
+    --m3-local-secondary-container: #d6ead5;
+    --m3-local-on-secondary-container: #183723;
+    --m3-local-surface: #eef8ee;
+    --m3-local-surface-low: #f7fdf6;
+    --m3-local-surface-high: #dcefdc;
+    --m3-local-surface-highest: #c6dfc7;
+    --m3-local-on-surface: #132017;
+    --m3-local-on-surface-variant: #3f5343;
+    --m3-local-outline: #6f8873;
+    --m3-local-outline-variant: #bed4c0;
+}
+
+html.m3-theme-dark .m3-local-theme--success {
+    --m3-local-primary: #9ad7ac;
+    --m3-local-primary-container: #245b37;
+    --m3-local-on-primary: #112f1c;
+    --m3-local-on-primary-container: #d3f0d8;
+    --m3-local-secondary-container: #334d3d;
+    --m3-local-on-secondary-container: #dce9de;
+    --m3-local-surface: #202924;
+    --m3-local-surface-low: #1a231e;
+    --m3-local-surface-high: #27312c;
+    --m3-local-surface-highest: #313d37;
+    --m3-local-on-surface: #dce7de;
+    --m3-local-on-surface-variant: #c0cbc2;
+    --m3-local-outline: #90a592;
+    --m3-local-outline-variant: #45594a;
+}
+
+html.m3-theme-light .m3-local-theme--brand-muted {
+    --m3-local-primary: #615b8f;
+    --m3-local-primary-container: #e7e0ff;
+    --m3-local-on-primary: #ffffff;
+    --m3-local-on-primary-container: #1d1738;
+    --m3-local-secondary-container: #e1ddf1;
+    --m3-local-on-secondary-container: #302c45;
+    --m3-local-surface: #f3f1fa;
+    --m3-local-surface-low: #fbf8ff;
+    --m3-local-surface-high: #e5e1f1;
+    --m3-local-surface-highest: #d7d2e4;
+    --m3-local-on-surface: #1d1b28;
+    --m3-local-on-surface-variant: #555266;
+    --m3-local-outline: #868098;
+    --m3-local-outline-variant: #d1ccdf;
+}
+
+html.m3-theme-dark .m3-local-theme--brand-muted {
+    --m3-local-primary: #b7c8e8;
+    --m3-local-primary-container: #44526c;
+    --m3-local-on-primary: #25324b;
+    --m3-local-on-primary-container: #e4e9f6;
+    --m3-local-secondary-container: #3b4558;
+    --m3-local-on-secondary-container: #e0e4ee;
+    --m3-local-surface: #232837;
+    --m3-local-surface-low: #1d2230;
+    --m3-local-surface-high: #2a3040;
+    --m3-local-surface-highest: #343c4d;
+    --m3-local-on-surface: #e2e6ef;
+    --m3-local-on-surface-variant: #c6cdd9;
+    --m3-local-outline: #909eb8;
+    --m3-local-outline-variant: #485162;
+}
+
+@media (max-width: 720px) {
+    .m3-local-theme-showcase__workspace-header {
+        flex-direction: column;
+    }
+}
+</style>
diff --git a/m3-vue/storybook/patterns/LocalTheming.stories.ts b/m3-vue/storybook/patterns/LocalTheming.stories.ts
new file mode 100644
index 0000000..2b5b4c5
--- /dev/null
+++ b/m3-vue/storybook/patterns/LocalTheming.stories.ts
@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import LocalThemeShowcase from '../examples/local-theme/LocalThemeShowcase.vue'
+
+const meta = {
+  title: 'Patterns/Local Theming',
+
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const DangerActionScope: Story = {
+  render: () => ({
+    components: {
+      LocalThemeShowcase,
+    },
+
+    template: `
+        <LocalThemeShowcase variant="danger" />
+    `,
+  }),
+}
+
+export const WarmAlertScope: Story = {
+  render: () => ({
+    components: {
+      LocalThemeShowcase,
+    },
+
+    template: `
+        <LocalThemeShowcase variant="warm-alert" />
+    `,
+  }),
+}
+
+export const SuccessScope: Story = {
+  render: () => ({
+    components: {
+      LocalThemeShowcase,
+    },
+
+    template: `
+        <LocalThemeShowcase variant="success" />
+    `,
+  }),
+}
+
+export const BrandMutedScope: Story = {
+  render: () => ({
+    components: {
+      LocalThemeShowcase,
+    },
+
+    template: `
+        <LocalThemeShowcase variant="brand-muted" />
+    `,
+  }),
+}
+
+export const NestedLocalScopes: Story = {
+  render: () => ({
+    components: {
+      LocalThemeShowcase,
+    },
+
+    template: `
+        <LocalThemeShowcase variant="nested" />
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/preview.ts b/m3-vue/storybook/preview.ts
index 1a402d0..b749950 100644
--- a/m3-vue/storybook/preview.ts
+++ b/m3-vue/storybook/preview.ts
@@ -2,8 +2,7 @@ import type { Preview, VueRenderer } from '@storybook/vue3'
 
 import '@modulify/m3-foundation/assets/stylesheets/normalize.scss'
 import '@modulify/m3-foundation/assets/stylesheets/index.scss'
-
-import './stylesheets/utils.scss'
+import '@modulify/m3-foundation/assets/stylesheets/storybook/utils.scss'
 
 import { withThemeByClassName } from '@storybook/addon-themes'
 import { addons } from 'storybook/preview-api'
diff --git a/m3-vue/storybook/stylesheets/utils.scss b/m3-vue/storybook/stylesheets/utils.scss
deleted file mode 100644
index 6b1f7f2..0000000
--- a/m3-vue/storybook/stylesheets/utils.scss
+++ /dev/null
@@ -1,62 +0,0 @@
-.d-block { display: block !important; }
-.d-inline { display: inline !important; }
-.d-inline-block { display: inline-block !important; }
-.d-none { display: none !important; }
-.d-flex { display: flex !important; }
-
-.flex-wrap {
-  flex-wrap: wrap !important;
-}
-
-.flex-container {
-  @extend .d-flex;
-  @extend .flex-wrap;
-}
-
-.flex-row {
-  @extend .d-flex;
-  align-items: center;
-}
-
-.mt-auto, .my-auto, .m-auto { margin-top: auto !important; }
-.mb-auto, .my-auto, .m-auto { margin-bottom: auto !important; }
-.ml-auto, .mx-auto, .m-auto { margin-left: auto !important; }
-.mr-auto, .mx-auto, .m-auto { margin-right: auto !important; }
-
-.mt-0, .my-0, .m-0 { margin-top: 0 !important; }
-.mb-0, .my-0, .m-0 { margin-bottom: 0 !important; }
-.ml-0, .mx-0, .m-0 { margin-left: 0 !important; }
-.mr-0, .mx-0, .m-0 { margin-right: 0 !important; }
-
-.pt-0, .py-0, .p-0 { padding-top: 0 !important; }
-.pb-0, .py-0, .p-0 { padding-bottom: 0 !important; }
-.pl-0, .px-0, .p-0 { padding-left: 0 !important; }
-.pr-0, .px-0, .p-0 { padding-right: 0 !important; }
-
-$base: 8px;
-$multipliers: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10;
-
-@each $value in $multipliers {
-  .mt-#{$value}, .my-#{$value}, .m-#{$value} { margin-top:    0.5 * $value * $base !important; }
-  .mb-#{$value}, .my-#{$value}, .m-#{$value} { margin-bottom: 0.5 * $value * $base !important; }
-  .ml-#{$value}, .mx-#{$value}, .m-#{$value} { margin-left:   0.5 * $value * $base !important; }
-  .mr-#{$value}, .mx-#{$value}, .m-#{$value} { margin-right:  0.5 * $value * $base !important; }
-
-  .mt-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-top:    -0.5 * $value * $base !important; }
-  .mb-n#{$value}, .my-n#{$value}, .m-n#{$value} { margin-bottom: -0.5 * $value * $base !important; }
-  .ml-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-left:   -0.5 * $value * $base !important; }
-  .mr-n#{$value}, .mx-n#{$value}, .m-n#{$value} { margin-right:  -0.5 * $value * $base !important; }
-
-  .pt-#{$value}, .py-#{$value}, .p-#{$value} { padding-top:    0.5 * $value * $base !important; }
-  .pb-#{$value}, .py-#{$value}, .p-#{$value} { padding-bottom: 0.5 * $value * $base !important; }
-  .pl-#{$value}, .px-#{$value}, .p-#{$value} { padding-left:   0.5 * $value * $base !important; }
-  .pr-#{$value}, .px-#{$value}, .p-#{$value} { padding-right:  0.5 * $value * $base !important; }
-}
-
-.mw-100 {
-  max-width: 100% !important;
-}
-
-.w-100 {
-  width: 100% !important;
-}
\ No newline at end of file

From e1da694091d791feda300fbf10154092b3ec0ad7 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 9 Mar 2026 18:15:46 +0400
Subject: [PATCH 34/37] feat: Runtime analysis recipes were added

---
 AGENTS.md                             |  10 +
 docs/en/index.md                      |   1 +
 docs/en/runtime-analysis-recipes.md   | 103 +++
 docs/ru/index.md                      |   1 +
 docs/ru/runtime-analysis-recipes.md   | 105 +++
 recipes/research.mk                   | 218 ++++++
 scripts/playwright-capture-diff.mjs   | 210 ++++++
 scripts/playwright-capture-matrix.mjs | 336 +++++++++
 scripts/playwright-research.mjs       | 999 ++++++++++++++++++++++++++
 9 files changed, 1983 insertions(+)
 create mode 100644 docs/en/runtime-analysis-recipes.md
 create mode 100644 docs/ru/runtime-analysis-recipes.md
 create mode 100644 scripts/playwright-capture-diff.mjs
 create mode 100644 scripts/playwright-capture-matrix.mjs
 create mode 100644 scripts/playwright-research.mjs

diff --git a/AGENTS.md b/AGENTS.md
index 267506d..cab7d21 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -108,6 +108,16 @@ make help
   its output to see whether an existing recipe already covers the task.
 - If a suitable recipe exists, prefer it over ad hoc commands to reduce extra
   work, keep workflows standardized, and avoid unnecessary escalations.
+- The project includes a Playwright container and make recipes for screenshot
+  capture; use them when visual analysis of Storybook pages, component states,
+  or other UI behavior is helpful.
+- The project also includes runtime-analysis research recipes for DOM, styles,
+  layout metrics, a11y snapshots, traces, network/performance logs, token
+  diffs, and screenshot matrices; use them to reduce uncertainty and to
+  understand what is going wrong before guessing at visual or runtime issues.
+  Read `docs/en/runtime-analysis-recipes.md` first when the task involves
+  visual regressions, layout ambiguity, token/theme uncertainty, unclear
+  animation behavior, or other runtime issues where these recipes may help.
 - Run eslint before handoff or commit preparation only when changed files
   include code covered by eslint rules (for example `*.js`, `*.ts`, and
   similar source files). Do not run eslint for markdown-only changes.
diff --git a/docs/en/index.md b/docs/en/index.md
index 3d3428c..012396c 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -3,6 +3,7 @@
 ## Contents
 
 - [Contributing Guide](./contributing.md) - Development workflow, core commands, and CI quality gates.
+- [Runtime Analysis Recipes](./runtime-analysis-recipes.md) - Playwright-based recipes for visual, layout, style, motion, and runtime investigation.
 - [TSConfig Layering](./tsconfig-layering.md) - How TypeScript configs are split between editor DX and CI checks.
 
 ## Translations
diff --git a/docs/en/runtime-analysis-recipes.md b/docs/en/runtime-analysis-recipes.md
new file mode 100644
index 0000000..7bed121
--- /dev/null
+++ b/docs/en/runtime-analysis-recipes.md
@@ -0,0 +1,103 @@
+# Runtime Analysis Recipes
+
+This document describes the Playwright-based research recipes available in
+`m3-web` for reducing uncertainty when visual or runtime behavior is unclear.
+
+## When To Use
+
+Use these recipes when:
+- a Storybook page looks wrong and screenshots are not enough;
+- a layout shifts, overlaps, or animates unexpectedly;
+- local theming or CSS tokens appear to be ignored;
+- React and Vue parity is unclear;
+- visual regressions need before/after or matrix comparison;
+- runtime errors may be hidden in console, network, or accessibility state.
+
+## Core Principle
+
+Prefer these recipes before guessing. They are intended to turn “something is
+off” into concrete evidence: screenshots, computed styles, layout metrics,
+accessibility trees, traces, and diffs.
+
+## Most Useful Recipes
+
+- `make research-capture url='...'` - Single screenshot with metadata.
+- `make research-capture-batch in=urls.txt out_dir=drafts/screenshots/...` -
+  Batch screenshot capture from a URL list.
+- `make research-style-dump url='...' selector='...'` - Computed styles and CSS
+  custom properties for one element.
+- `make research-layout-metrics url='...' selectors='.a||.b||.c'` - Bounding
+  boxes, scroll metrics, offsets, and layout details for multiple elements.
+- `make research-token-diff url='...' selector='.left' compare_selector='.right'`
+  - CSS variable diff between two scopes.
+- `make research-console-capture url='...'` - Console messages, page errors,
+  and failed requests.
+- `make research-a11y-snapshot url='...' selector='...'` - Accessibility tree
+  for the page or a subtree.
+- `make research-trace url='...' action_selector='...' interaction=click` -
+  Playwright trace for a page and optional interaction.
+- `make research-motion-sample url='...' action_selector='...' interaction=click`
+  - Timed frame sequence for motion and transitions.
+- `make research-capture-diff left=before.png right=after.png out=diff.png` -
+  Pixel diff for two images or directories.
+- `make research-capture-matrix ...` - Capture one URL across multiple themes,
+  globals, args, and viewports.
+- `make research-story-props story_id='...' themes='light,dark' args_sets='...'`
+  - Storybook-oriented matrix capture for story args and globals.
+
+## Typical Workflows
+
+## Investigate A Broken Layout
+
+1. Capture the current page:
+   `make research-capture url='...'`
+2. Dump layout metrics:
+   `make research-layout-metrics url='...' selectors='.host||.panel||.scrim'`
+3. Dump computed styles for the suspicious node:
+   `make research-style-dump url='...' selector='.panel'`
+
+## Investigate A Theme Or Token Problem
+
+1. Capture the page in both themes:
+   `make research-capture-matrix story_id='...' themes='light,dark'`
+2. Compare token scopes:
+   `make research-token-diff url='...' selector='.default-scope' compare_selector='.local-scope'`
+3. Inspect computed variables:
+   `make research-style-dump url='...' selector='.local-scope' var_prefixes='--m3-sys-,--m3-state-layers-'`
+
+## Investigate Animation Or Motion
+
+1. Capture a motion sequence:
+   `make research-motion-sample url='...' action_selector='...' interaction=click`
+2. If behavior is still unclear, capture a trace:
+   `make research-trace url='...' action_selector='...' interaction=click`
+
+## Compare Two Runtime States
+
+1. Capture both states into separate directories.
+2. Run:
+   `make research-capture-diff left=dir-a right=dir-b out_dir=drafts/research/diff`
+
+## Storybook Notes
+
+- Storybook pages can be opened directly with:
+  `http://m3-vue.modulify.test/?path=/story/...&globals=theme:dark`
+- For systematic capture across states, prefer `research-story-props` and
+  `research-capture-matrix` over manually building many URLs.
+
+## Output Conventions
+
+- Screenshots are written under `drafts/screenshots/...` unless overridden.
+- Runtime inspection outputs default to `drafts/research/...`.
+- Most recipes emit machine-readable JSON so results can be inspected or
+  compared later.
+
+## Recommendation
+
+When a bug report is vague, start with:
+1. `research-capture`
+2. `research-style-dump`
+3. `research-layout-metrics`
+
+That combination usually clarifies whether the problem is geometry, styling,
+token inheritance, or runtime state.
diff --git a/docs/ru/index.md b/docs/ru/index.md
index 6a36c7c..e5f7526 100644
--- a/docs/ru/index.md
+++ b/docs/ru/index.md
@@ -3,4 +3,5 @@
 ## Содержание
 
 - [Руководство по участию](./contributing.md) - Процесс разработки, ключевые команды и проверки в CI.
+- [Рецепты runtime-анализа](./runtime-analysis-recipes.md) - Playwright-рецепты для исследования visual, layout, style, motion и runtime-проблем.
 - [Слои TSConfig](./tsconfig-layering.md) - Разделение TypeScript-конфигов для IDE и package-level typecheck.
diff --git a/docs/ru/runtime-analysis-recipes.md b/docs/ru/runtime-analysis-recipes.md
new file mode 100644
index 0000000..32cd720
--- /dev/null
+++ b/docs/ru/runtime-analysis-recipes.md
@@ -0,0 +1,105 @@
+# Рецепты runtime-анализа
+
+Этот документ описывает Playwright-рецепты исследования, доступные в
+`m3-web`, чтобы снимать неопределённость, когда визуальное или runtime-поведение
+непонятно.
+
+## Когда применять
+
+Используйте эти рецепты, когда:
+- Storybook-страница выглядит неправильно, и одного скриншота недостаточно;
+- layout сдвигается, наползает или анимируется неожиданно;
+- локальная тема или CSS-токены как будто игнорируются;
+- неясно, есть ли parity между React и Vue;
+- нужно сравнить состояния до/после или матрицу сценариев;
+- runtime-ошибки могут прятаться в console, network или accessibility-состоянии.
+
+## Базовый принцип
+
+Предпочитайте эти рецепты угадыванию. Их задача — превращать расплывчатое
+«что-то не так» в конкретные артефакты: скриншоты, computed styles, layout
+метрики, accessibility tree, traces и diffs.
+
+## Самые полезные рецепты
+
+- `make research-capture url='...'` - Один скриншот с метаданными.
+- `make research-capture-batch in=urls.txt out_dir=drafts/screenshots/...` -
+  Пакетное снятие скриншотов по списку URL.
+- `make research-style-dump url='...' selector='...'` - Computed styles и CSS
+  custom properties для одного элемента.
+- `make research-layout-metrics url='...' selectors='.a||.b||.c'` - Bounding
+  boxes, scroll-метрики, offsets и layout-детали для нескольких элементов.
+- `make research-token-diff url='...' selector='.left' compare_selector='.right'`
+  - Diff CSS-переменных между двумя scope.
+- `make research-console-capture url='...'` - Console messages, page errors и
+  failed requests.
+- `make research-a11y-snapshot url='...' selector='...'` - Accessibility tree
+  для страницы или subtree.
+- `make research-trace url='...' action_selector='...' interaction=click` -
+  Playwright trace для страницы и опционального взаимодействия.
+- `make research-motion-sample url='...' action_selector='...' interaction=click`
+  - Последовательность кадров для motion и transitions.
+- `make research-capture-diff left=before.png right=after.png out=diff.png` -
+  Pixel diff для двух изображений или каталогов.
+- `make research-capture-matrix ...` - Съёмка одного URL по нескольким themes,
+  globals, args и viewports.
+- `make research-story-props story_id='...' themes='light,dark' args_sets='...'`
+  - Storybook-oriented matrix capture для story args и globals.
+
+## Типовые сценарии
+
+## Разобрать сломанный layout
+
+1. Снять текущую страницу:
+   `make research-capture url='...'`
+2. Снять layout metrics:
+   `make research-layout-metrics url='...' selectors='.host||.panel||.scrim'`
+3. Снять computed styles для подозрительного узла:
+   `make research-style-dump url='...' selector='.panel'`
+
+## Разобрать проблему темы или токенов
+
+1. Снять страницу в обеих темах:
+   `make research-capture-matrix story_id='...' themes='light,dark'`
+2. Сравнить token scope:
+   `make research-token-diff url='...' selector='.default-scope' compare_selector='.local-scope'`
+3. Посмотреть computed variables:
+   `make research-style-dump url='...' selector='.local-scope' var_prefixes='--m3-sys-,--m3-state-layers-'`
+
+## Разобрать анимацию или motion
+
+1. Снять последовательность кадров:
+   `make research-motion-sample url='...' action_selector='...' interaction=click`
+2. Если поведение всё ещё неясно, снять trace:
+   `make research-trace url='...' action_selector='...' interaction=click`
+
+## Сравнить два runtime-состояния
+
+1. Снять оба состояния в разные каталоги.
+2. Запустить:
+   `make research-capture-diff left=dir-a right=dir-b out_dir=drafts/research/diff`
+
+## Примечания по Storybook
+
+- Storybook-страницы можно открывать напрямую так:
+  `http://m3-vue.modulify.test/?path=/story/...&globals=theme:dark`
+- Для систематической съёмки по состояниям лучше использовать
+  `research-story-props` и `research-capture-matrix`, а не собирать множество
+  URL вручную.
+
+## Формат артефактов
+
+- Скриншоты по умолчанию пишутся в `drafts/screenshots/...`.
+- Runtime inspection outputs по умолчанию пишутся в `drafts/research/...`.
+- Большинство рецептов сохраняет machine-readable JSON, чтобы результаты можно
+  было потом изучать и сравнивать.
+
+## Рекомендация
+
+Когда баг-репорт расплывчатый, начинайте с:
+1. `research-capture`
+2. `research-style-dump`
+3. `research-layout-metrics`
+
+Эта комбинация обычно быстро показывает, проблема в геометрии, styling,
+наследовании токенов или runtime-состоянии.
diff --git a/recipes/research.mk b/recipes/research.mk
index b05676b..de1439c 100644
--- a/recipes/research.mk
+++ b/recipes/research.mk
@@ -90,3 +90,221 @@ research-capture-batch: ## [Research][docker][playwright][capture] Captures scre
 		$(if $(full_page),--full-page "$(full_page)",) \
 		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
 	$(TARGET_OK)
+
+.PHONY: research-dom-snapshot
+research-dom-snapshot: ## [Research][docker][playwright][inspect] Saves outerHTML/text snapshot for a page selector
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action dom-snapshot \
+		--url "$(url)" \
+		$(if $(selector),--selector "$(selector)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-style-dump
+research-style-dump: ## [Research][docker][playwright][inspect] Saves computed styles and CSS variables for a selector
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action style-dump \
+		--url "$(url)" \
+		$(if $(selector),--selector "$(selector)",) \
+		$(if $(props),--props "$(props)",) \
+		$(if $(var_prefixes),--var-prefixes "$(var_prefixes)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-layout-metrics
+research-layout-metrics: ## [Research][docker][playwright][inspect] Saves bounding boxes and layout metrics for selectors
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action layout-metrics \
+		--url "$(url)" \
+		$(if $(selector),--selector "$(selector)",) \
+		$(if $(selectors),--selectors "$(selectors)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-a11y-snapshot
+research-a11y-snapshot: ## [Research][docker][playwright][a11y] Saves Playwright accessibility snapshot for a page or selector
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action a11y-snapshot \
+		--url "$(url)" \
+		$(if $(selector),--selector "$(selector)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-console-capture
+research-console-capture: ## [Research][docker][playwright][inspect] Saves console messages, page errors, and failed requests
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action console-capture \
+		--url "$(url)" \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-trace
+research-trace: ## [Research][docker][playwright][trace] Saves Playwright trace for a page and optional interaction
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action trace \
+		--url "$(url)" \
+		$(if $(action_selector),--action-selector "$(action_selector)",) \
+		$(if $(interaction),--interaction "$(interaction)",) \
+		$(if $(post_action_wait_ms),--post-action-wait-ms "$(post_action_wait_ms)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-network-log
+research-network-log: ## [Research][docker][playwright][inspect] Saves request/response timeline for a page load
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action network-log \
+		--url "$(url)" \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-perf-marks
+research-perf-marks: ## [Research][docker][playwright][inspect] Saves Performance API entries for a page
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action perf-marks \
+		--url "$(url)" \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-token-diff
+research-token-diff: ## [Research][docker][playwright][inspect] Compares computed CSS custom properties between two selectors
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action token-diff \
+		--url "$(url)" \
+		$(if $(selector),--selector "$(selector)",) \
+		$(if $(compare_selector),--compare-selector "$(compare_selector)",) \
+		$(if $(var_prefixes),--var-prefixes "$(var_prefixes)",) \
+		$(if $(out),--out "$(out)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-motion-sample
+research-motion-sample: ## [Research][docker][playwright][capture] Captures a timed frame sequence for page motion and optional interaction
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-research.mjs \
+		--action motion-sample \
+		--url "$(url)" \
+		$(if $(action_selector),--action-selector "$(action_selector)",) \
+		$(if $(interaction),--interaction "$(interaction)",) \
+		$(if $(count),--count "$(count)",) \
+		$(if $(interval_ms),--interval-ms "$(interval_ms)",) \
+		$(if $(full_page),--full-page "$(full_page)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(width),--width "$(width)",) \
+		$(if $(height),--height "$(height)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",)
+	$(TARGET_OK)
+
+.PHONY: research-capture-diff
+research-capture-diff: ## [Research][docker][inspect][capture] Creates image diffs for two screenshots or two screenshot directories
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-capture-diff.mjs \
+		--left "$(left)" \
+		--right "$(right)" \
+		$(if $(out),--out "$(out)",) \
+		$(if $(summary),--summary "$(summary)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(threshold),--threshold "$(threshold)",)
+	$(TARGET_OK)
+
+.PHONY: research-capture-matrix
+research-capture-matrix: ## [Research][docker][playwright][capture] Captures URL or Storybook matrices across themes, globals, args, and viewports
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-capture-matrix.mjs \
+		$(if $(url),--url "$(url)",) \
+		$(if $(base_url),--base-url "$(base_url)",) \
+		$(if $(story_id),--story-id "$(story_id)",) \
+		$(if $(globals),--globals "$(globals)",) \
+		$(if $(globals_sets),--globals-sets "$(globals_sets)",) \
+		$(if $(args),--args "$(args)",) \
+		$(if $(args_sets),--args-sets "$(args_sets)",) \
+		$(if $(themes),--themes "$(themes)",) \
+		$(if $(viewports),--viewports "$(viewports)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",) \
+		$(if $(full_page),--full-page "$(full_page)",)
+	$(TARGET_OK)
+
+.PHONY: research-story-props
+research-story-props: ## [Research][docker][playwright][capture] Captures Storybook story matrices for args/globals/theme combinations
+	$(TARGET_HEADER)
+	@$(PLAYWRIGHT_NODE_CMD) scripts/playwright-capture-matrix.mjs \
+		$(if $(base_url),--base-url "$(base_url)",) \
+		--story-id "$(story_id)" \
+		$(if $(globals),--globals "$(globals)",) \
+		$(if $(globals_sets),--globals-sets "$(globals_sets)",) \
+		$(if $(args),--args "$(args)",) \
+		$(if $(args_sets),--args-sets "$(args_sets)",) \
+		$(if $(themes),--themes "$(themes)",) \
+		$(if $(viewports),--viewports "$(viewports)",) \
+		$(if $(out_dir),--out-dir "$(out_dir)",) \
+		$(if $(wait_ms),--wait-ms "$(wait_ms)",) \
+		$(if $(wait_until),--wait-until "$(wait_until)",) \
+		$(if $(wait_selector),--wait-selector "$(wait_selector)",) \
+		$(if $(full_page),--full-page "$(full_page)",)
+	$(TARGET_OK)
diff --git a/scripts/playwright-capture-diff.mjs b/scripts/playwright-capture-diff.mjs
new file mode 100644
index 0000000..ee2fcfe
--- /dev/null
+++ b/scripts/playwright-capture-diff.mjs
@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+import path from 'node:path'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { PNG } from 'pngjs'
+import pixelmatch from 'pixelmatch'
+
+function usage() {
+  console.log([
+    'usage:',
+    '  node scripts/playwright-capture-diff.mjs --left path.png --right path.png [--out diff.png] [--summary summary.json]',
+    '  node scripts/playwright-capture-diff.mjs --left dir-a --right dir-b [--out-dir diffs]',
+    '',
+    'options:',
+    '  --left PATH',
+    '  --right PATH',
+    '  --out FILE          diff PNG path for single-image mode',
+    '  --summary FILE      JSON summary path for single-image mode',
+    '  --out-dir DIR       output directory for directory mode',
+    '  --threshold N       pixelmatch threshold (default: 0.1)',
+  ].join('\n'))
+}
+
+function parseArgs(argv) {
+  const args = {}
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+
+    if (!token.startsWith('--')) {
+      continue
+    }
+
+    const key = token.slice(2)
+    const next = argv[index + 1]
+    const value = !next || next.startsWith('--') ? 'true' : next
+    args[key] = value
+
+    if (value !== 'true') {
+      index += 1
+    }
+  }
+
+  return args
+}
+
+async function statKind(targetPath) {
+  try {
+    const { stat } = await import('node:fs/promises')
+    const metadata = await stat(targetPath)
+
+    if (metadata.isDirectory()) {
+      return 'dir'
+    }
+
+    if (metadata.isFile()) {
+      return 'file'
+    }
+
+    return 'other'
+  } catch {
+    return null
+  }
+}
+
+async function readPng(filePath) {
+  const content = await readFile(filePath)
+
+  return PNG.sync.read(content)
+}
+
+async function writePng(filePath, png) {
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, PNG.sync.write(png))
+}
+
+async function diffPair(leftPath, rightPath, outPath, threshold) {
+  const left = await readPng(leftPath)
+  const right = await readPng(rightPath)
+
+  if (left.width !== right.width || left.height !== right.height) {
+    return {
+      left_path: leftPath,
+      right_path: rightPath,
+      out_path: outPath ?? null,
+      size_mismatch: {
+        left: { width: left.width, height: left.height },
+        right: { width: right.width, height: right.height },
+      },
+      different_pixels: null,
+      total_pixels: null,
+      mismatch_ratio: null,
+    }
+  }
+
+  const diff = new PNG({ width: left.width, height: left.height })
+  const differentPixels = pixelmatch(left.data, right.data, diff.data, left.width, left.height, { threshold })
+  const totalPixels = left.width * left.height
+
+  if (outPath) {
+    await writePng(outPath, diff)
+  }
+
+  return {
+    left_path: leftPath,
+    right_path: rightPath,
+    out_path: outPath ?? null,
+    size_mismatch: null,
+    different_pixels: differentPixels,
+    total_pixels: totalPixels,
+    mismatch_ratio: totalPixels === 0 ? 0 : differentPixels / totalPixels,
+  }
+}
+
+async function listPngFiles(dirPath) {
+  const files = await readdir(dirPath)
+
+  return files.filter((fileName) => fileName.toLowerCase().endsWith('.png')).sort()
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const helpRequested = args.help === 'true'
+
+  if (helpRequested || !args.left || !args.right) {
+    usage()
+    process.exit(helpRequested ? 0 : 2)
+  }
+
+  const leftPath = args.left
+  const rightPath = args.right
+  const leftKind = await statKind(leftPath)
+  const rightKind = await statKind(rightPath)
+  const threshold = Number(args.threshold ?? 0.1)
+
+  if (!leftKind || !rightKind) {
+    throw new Error('expected existing --left and --right paths')
+  }
+
+  if (leftKind !== rightKind) {
+    throw new Error('--left and --right must both be files or both be directories')
+  }
+
+  if (leftKind === 'file') {
+    const outPath = args.out
+    const summaryPath = args.summary
+      ?? (outPath ? outPath.replace(/\.png$/i, '.json') : path.join('drafts', 'research', 'capture-diff', 'summary.json'))
+    const result = await diffPair(leftPath, rightPath, outPath, threshold)
+
+    await mkdir(path.dirname(summaryPath), { recursive: true })
+    await writeFile(summaryPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8')
+
+    if (outPath) {
+      console.log(outPath)
+    }
+    console.log(summaryPath)
+    return
+  }
+
+  const outDir = args['out-dir'] ?? path.join('drafts', 'research', 'capture-diff')
+  const leftFiles = await listPngFiles(leftPath)
+  const rightFiles = await listPngFiles(rightPath)
+  const leftSet = new Set(leftFiles)
+  const rightSet = new Set(rightFiles)
+  const common = leftFiles.filter((fileName) => rightSet.has(fileName))
+  const leftOnly = leftFiles.filter((fileName) => !rightSet.has(fileName))
+  const rightOnly = rightFiles.filter((fileName) => !leftSet.has(fileName))
+  const results = []
+
+  for (const fileName of common) {
+    const result = await diffPair(
+      path.join(leftPath, fileName),
+      path.join(rightPath, fileName),
+      path.join(outDir, fileName),
+      threshold,
+    )
+
+    results.push({
+      file_name: fileName,
+      ...result,
+    })
+  }
+
+  const summary = {
+    compared_at: new Date().toISOString(),
+    left_dir: leftPath,
+    right_dir: rightPath,
+    compared_files: results.length,
+    left_only: leftOnly,
+    right_only: rightOnly,
+    results,
+  }
+  const summaryPath = path.join(outDir, 'summary.json')
+
+  await mkdir(outDir, { recursive: true })
+  await writeFile(summaryPath, `${JSON.stringify(summary, null, 2)}\n`, 'utf8')
+
+  console.log(outDir)
+  console.log(summaryPath)
+}
+
+main().catch((error) => {
+  if (error instanceof Error) {
+    console.error(error.message)
+  } else {
+    console.error(String(error))
+  }
+
+  process.exit(1)
+})
diff --git a/scripts/playwright-capture-matrix.mjs b/scripts/playwright-capture-matrix.mjs
new file mode 100644
index 0000000..4594b5c
--- /dev/null
+++ b/scripts/playwright-capture-matrix.mjs
@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { chromium } from 'playwright'
+
+function usage() {
+  console.log([
+    'usage:',
+    '  node scripts/playwright-capture-matrix.mjs --url https://... [--themes dark,light] [--viewports desktop:1440x1024,mobile:390x844]',
+    '  node scripts/playwright-capture-matrix.mjs --base-url http://m3-vue.modulify.test/ --story-id patterns-local-theming--danger-action-scope',
+    '',
+    'options:',
+    '  --url URL',
+    '  --base-url URL        default: http://m3-vue.modulify.test/',
+    '  --story-id ID',
+    '  --globals KEY:VALUE;KEY:VALUE',
+    '  --globals-sets SET1||SET2',
+    '  --args KEY:VALUE;KEY:VALUE',
+    '  --args-sets SET1||SET2',
+    '  --themes dark,light',
+    '  --viewports NAME:WIDTHxHEIGHT,NAME:WIDTHxHEIGHT',
+    '  --out-dir DIR',
+    '  --wait-ms MS',
+    '  --wait-until STATE',
+    '  --wait-selector CSS',
+    '  --full-page BOOL',
+  ].join('\n'))
+}
+
+function parseArgs(argv) {
+  const args = {}
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+
+    if (!token.startsWith('--')) {
+      continue
+    }
+
+    const key = token.slice(2)
+    const next = argv[index + 1]
+    const value = !next || next.startsWith('--') ? 'true' : next
+    args[key] = value
+
+    if (value !== 'true') {
+      index += 1
+    }
+  }
+
+  return args
+}
+
+function parseHttpUrl(value) {
+  let parsed
+
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new Error(`Invalid URL: ${value}`)
+  }
+
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Unsupported URL protocol: ${value}`)
+  }
+
+  return parsed
+}
+
+function toBool(value, fallback = true) {
+  if (value == null) {
+    return fallback
+  }
+
+  return !['0', 'false', 'no', 'off'].includes(String(value).toLowerCase())
+}
+
+function toNumber(value, fallback) {
+  const parsed = Number(value)
+
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function sanitizePart(value) {
+  return value
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+function defaultFileName(url, variant) {
+  const parsed = new URL(url)
+  const base = sanitizePart(`${parsed.hostname}${parsed.pathname || '/index'}-${variant}`.toLowerCase()) || 'capture'
+  const hash = crypto.createHash('sha1').update(`${url}:${variant}`).digest('hex').slice(0, 8)
+  return `${base}-${hash}.png`
+}
+
+function splitSetList(value) {
+  if (!value) {
+    return ['']
+  }
+
+  return String(value)
+    .split('||')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+function parseThemes(value) {
+  if (!value) {
+    return ['']
+  }
+
+  return String(value)
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+function parseViewports(value) {
+  if (!value) {
+    return [{
+      name: 'desktop',
+      width: 1440,
+      height: 1024,
+    }]
+  }
+
+  return String(value)
+    .split(',')
+    .map((entry, index) => {
+      const trimmed = entry.trim()
+      const [namePart, sizePartRaw] = trimmed.includes(':')
+        ? trimmed.split(':')
+        : [`viewport-${index + 1}`, trimmed]
+      const sizePart = sizePartRaw.trim()
+      const match = sizePart.match(/^(\d+)x(\d+)$/i)
+
+      if (!match) {
+        throw new Error(`Invalid viewport entry: ${trimmed}`)
+      }
+
+      return {
+        name: sanitizePart(namePart.trim()) || `viewport-${index + 1}`,
+        width: Number(match[1]),
+        height: Number(match[2]),
+      }
+    })
+}
+
+function mergeQueryGroup(baseGroup, extraGroup) {
+  const parts = []
+
+  if (baseGroup) {
+    parts.push(...baseGroup.split(';').map((entry) => entry.trim()).filter(Boolean))
+  }
+
+  if (extraGroup) {
+    parts.push(...extraGroup.split(';').map((entry) => entry.trim()).filter(Boolean))
+  }
+
+  return parts.join(';')
+}
+
+function buildStoryUrl(args, theme, globalsSet, argSet) {
+  const baseUrl = parseHttpUrl(args['base-url'] ?? 'http://m3-vue.modulify.test/')
+  const storyId = args['story-id']
+
+  if (!storyId) {
+    throw new Error('expected --story-id when --url is not provided')
+  }
+
+  const url = new URL(baseUrl.toString())
+  url.searchParams.set('path', `/story/${storyId}`)
+
+  const globals = mergeQueryGroup(args.globals ?? '', mergeQueryGroup(theme ? `theme:${theme}` : '', globalsSet))
+  const storyArgs = mergeQueryGroup(args.args ?? '', argSet)
+
+  if (globals) {
+    url.searchParams.set('globals', globals)
+  }
+
+  if (storyArgs) {
+    url.searchParams.set('args', storyArgs)
+  }
+
+  return url.toString()
+}
+
+function buildDirectUrl(args, theme, globalsSet) {
+  const baseUrl = new URL(parseHttpUrl(args.url).toString())
+  const currentGlobals = baseUrl.searchParams.get('globals') ?? ''
+  const globals = mergeQueryGroup(currentGlobals, mergeQueryGroup(args.globals ?? '', mergeQueryGroup(theme ? `theme:${theme}` : '', globalsSet)))
+
+  if (globals) {
+    baseUrl.searchParams.set('globals', globals)
+  }
+
+  return baseUrl.toString()
+}
+
+async function captureOne({ url, outPath, viewport, waitMs, waitUntil, waitSelector, fullPage }) {
+  const browser = await chromium.launch({ headless: true })
+  const context = await browser.newContext({
+    viewport: {
+      width: viewport.width,
+      height: viewport.height,
+    },
+  })
+  const page = await context.newPage()
+
+  try {
+    await page.goto(url, {
+      waitUntil,
+      timeout: 45000,
+    })
+
+    if (waitSelector) {
+      await page.waitForSelector(waitSelector, { timeout: 45000 })
+    }
+
+    if (waitMs > 0) {
+      await page.waitForTimeout(waitMs)
+    }
+
+    await mkdir(path.dirname(outPath), { recursive: true })
+    await page.screenshot({
+      path: outPath,
+      fullPage,
+    })
+
+    const metaPath = outPath.replace(/\.png$/i, '.meta.json')
+    await writeFile(metaPath, `${JSON.stringify({
+      captured_at: new Date().toISOString(),
+      url_requested: url,
+      url_final: page.url(),
+      title: await page.title(),
+      viewport,
+      wait_ms: waitMs,
+      wait_until: waitUntil,
+      wait_selector: waitSelector || null,
+      full_page: fullPage,
+      image_path: outPath,
+    }, null, 2)}\n`, 'utf8')
+
+    return {
+      image_path: outPath,
+      meta_path: metaPath,
+      final_url: page.url(),
+      title: await page.title(),
+    }
+  } finally {
+    await page.close().catch(() => {})
+    await context.close().catch(() => {})
+    await browser.close().catch(() => {})
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const helpRequested = args.help === 'true'
+
+  if (helpRequested || (!args.url && !args['story-id'])) {
+    usage()
+    process.exit(helpRequested ? 0 : 2)
+  }
+
+  const themes = parseThemes(args.themes)
+  const globalsSets = splitSetList(args['globals-sets'])
+  const argsSets = splitSetList(args['args-sets'])
+  const viewports = parseViewports(args.viewports)
+  const outDir = args['out-dir'] ?? path.join('drafts', 'screenshots', 'capture-matrix')
+  const waitMs = toNumber(args['wait-ms'] ?? '1200', 1200)
+  const waitUntil = args['wait-until'] ?? 'networkidle'
+  const waitSelector = args['wait-selector'] ?? ''
+  const fullPage = toBool(args['full-page'], false)
+  const results = []
+
+  for (const theme of themes) {
+    for (const globalsSet of globalsSets) {
+      for (const argSet of argsSets) {
+        for (const viewport of viewports) {
+          const url = args.url
+            ? buildDirectUrl(args, theme, globalsSet)
+            : buildStoryUrl(args, theme, globalsSet, argSet)
+          const variant = [
+            theme || 'default-theme',
+            globalsSet ? sanitizePart(globalsSet) : 'base-globals',
+            argSet ? sanitizePart(argSet) : 'base-args',
+            viewport.name,
+          ].join('-')
+          const outPath = path.join(outDir, defaultFileName(url, variant))
+          const capture = await captureOne({
+            url,
+            outPath,
+            viewport,
+            waitMs,
+            waitUntil,
+            waitSelector,
+            fullPage,
+          })
+
+          results.push({
+            theme: theme || null,
+            globals_set: globalsSet || null,
+            args_set: argSet || null,
+            viewport,
+            url,
+            ...capture,
+          })
+        }
+      }
+    }
+  }
+
+  const summaryPath = path.join(outDir, 'summary.json')
+  await mkdir(outDir, { recursive: true })
+  await writeFile(summaryPath, `${JSON.stringify({
+    captured_at: new Date().toISOString(),
+    results,
+  }, null, 2)}\n`, 'utf8')
+
+  console.log(outDir)
+  console.log(summaryPath)
+}
+
+main().catch((error) => {
+  if (error instanceof Error) {
+    console.error(error.message)
+  } else {
+    console.error(String(error))
+  }
+
+  process.exit(1)
+})
diff --git a/scripts/playwright-research.mjs b/scripts/playwright-research.mjs
new file mode 100644
index 0000000..421c074
--- /dev/null
+++ b/scripts/playwright-research.mjs
@@ -0,0 +1,999 @@
+#!/usr/bin/env node
+
+import crypto from 'node:crypto'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { chromium } from 'playwright'
+
+function usage() {
+  console.log([
+    'usage:',
+    '  node scripts/playwright-research.mjs --action style-dump --url https://... [options]',
+    '',
+    'actions:',
+    '  dom-snapshot',
+    '  style-dump',
+    '  layout-metrics',
+    '  a11y-snapshot',
+    '  console-capture',
+    '  trace',
+    '  network-log',
+    '  perf-marks',
+    '  token-diff',
+    '  motion-sample',
+    '',
+    'common options:',
+    '  --url URL',
+    '  --out FILE',
+    '  --out-dir DIR',
+    '  --width PX             default: 1440',
+    '  --height PX            default: 1024',
+    '  --wait-ms MS           default: 1200',
+    '  --wait-until STATE     default: networkidle',
+    '  --wait-selector CSS',
+    '  --timeout MS           default: 45000',
+    '',
+    'selector options:',
+    '  --selector CSS',
+    '  --selectors CSS1||CSS2||CSS3',
+    '  --compare-selector CSS',
+    '',
+    'action-specific options:',
+    '  --props display,color,gap',
+    '  --var-prefix --m3-sys-   may be repeated',
+    '  --var-prefixes --m3-sys-,--m3-state-layers-',
+    '  --action-selector CSS',
+    '  --interaction click|hover|focus',
+    '  --count N               motion-sample only; default: 6',
+    '  --interval-ms MS        motion-sample only; default: 120',
+  ].join('\n'))
+}
+
+function parseArgs(argv) {
+  const args = {}
+  const optionsWithValues = new Set([
+    'action',
+    'url',
+    'out',
+    'out-dir',
+    'width',
+    'height',
+    'wait-ms',
+    'wait-until',
+    'wait-selector',
+    'timeout',
+    'selector',
+    'selectors',
+    'compare-selector',
+    'props',
+    'var-prefix',
+    'var-prefixes',
+    'action-selector',
+    'interaction',
+    'count',
+    'interval-ms',
+    'post-action-wait-ms',
+    'full-page',
+  ])
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]
+
+    if (!token.startsWith('--')) {
+      continue
+    }
+
+    const inlineSeparatorIndex = token.indexOf('=')
+    const hasInlineValue = inlineSeparatorIndex !== -1
+    const key = hasInlineValue ? token.slice(2, inlineSeparatorIndex) : token.slice(2)
+    const next = argv[index + 1]
+    const expectsValue = optionsWithValues.has(key)
+    const value = hasInlineValue
+      ? token.slice(inlineSeparatorIndex + 1)
+      : (!expectsValue || next == null ? 'true' : next)
+
+    if (Object.hasOwn(args, key)) {
+      const current = Array.isArray(args[key]) ? args[key] : [args[key]]
+      current.push(value)
+      args[key] = current
+    } else {
+      args[key] = value
+    }
+
+    if (!hasInlineValue && value !== 'true') {
+      index += 1
+    }
+  }
+
+  return args
+}
+
+function getArg(args, key, fallback = undefined) {
+  const value = args[key]
+
+  if (Array.isArray(value)) {
+    return value[value.length - 1] ?? fallback
+  }
+
+  return value ?? fallback
+}
+
+function getArgs(args, key) {
+  const value = args[key]
+
+  if (value == null) {
+    return []
+  }
+
+  return Array.isArray(value) ? value : [value]
+}
+
+function toBool(value, fallback = true) {
+  if (value == null) {
+    return fallback
+  }
+
+  return !['0', 'false', 'no', 'off'].includes(String(value).toLowerCase())
+}
+
+function toNumber(value, fallback) {
+  const parsed = Number(value)
+
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function sanitizePart(value) {
+  return value
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+function parseHttpUrl(value) {
+  let parsed
+
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new Error(`Invalid --url value: ${value}`)
+  }
+
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Unsupported URL protocol in --url: ${value}`)
+  }
+
+  return parsed
+}
+
+function defaultStem(action, parsedUrl, rawUrl) {
+  const base = sanitizePart(`${parsedUrl.hostname}${parsedUrl.pathname || '/index'}`.toLowerCase()) || 'page'
+  const hash = crypto.createHash('sha1').update(`${action}:${rawUrl}`).digest('hex').slice(0, 8)
+  return `${base}-${action}-${hash}`
+}
+
+function defaultOutputPath({ action, parsedUrl, rawUrl, out, outDir, extension }) {
+  if (out) {
+    return out
+  }
+
+  const baseDir = outDir ?? path.join('drafts', 'research', action)
+
+  return path.join(baseDir, `${defaultStem(action, parsedUrl, rawUrl)}.${extension}`)
+}
+
+function splitDelimitedValues(value, delimiter = '||') {
+  if (!value) {
+    return []
+  }
+
+  return String(value)
+    .split(delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+function resolveSelectors(args) {
+  const directSelectors = getArgs(args, 'selector')
+  const groupedSelectors = splitDelimitedValues(getArg(args, 'selectors', ''))
+
+  const selectors = [...directSelectors, ...groupedSelectors].filter(Boolean)
+
+  return selectors.length > 0 ? selectors : ['body']
+}
+
+function resolveVarPrefixes(args) {
+  const directPrefixes = getArgs(args, 'var-prefix')
+  const groupedPrefixes = String(getArg(args, 'var-prefixes', '--m3-sys-'))
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+
+  const prefixes = [...directPrefixes, ...groupedPrefixes]
+
+  return prefixes.length > 0 ? prefixes : ['--m3-sys-']
+}
+
+function resolveCssProps(args) {
+  return String(getArg(
+    args,
+    'props',
+    'display,position,width,height,min-width,min-height,max-width,max-height,margin,padding,gap,font-size,line-height,color,background-color,border-radius,z-index',
+  ))
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+}
+
+async function createPage(args) {
+  const width = toNumber(getArg(args, 'width', '1440'), 1440)
+  const height = toNumber(getArg(args, 'height', '1024'), 1024)
+  const browser = await chromium.launch({ headless: true })
+  const context = await browser.newContext({
+    viewport: { width, height },
+  })
+  const page = await context.newPage()
+
+  return {
+    browser,
+    context,
+    page,
+    viewport: { width, height },
+  }
+}
+
+async function navigate(page, args) {
+  const url = getArg(args, 'url')
+  const timeout = toNumber(getArg(args, 'timeout', '45000'), 45000)
+  const waitUntil = getArg(args, 'wait-until', 'networkidle')
+  const waitSelector = getArg(args, 'wait-selector', '')
+  const waitMs = toNumber(getArg(args, 'wait-ms', '1200'), 1200)
+
+  await page.goto(url, { waitUntil, timeout })
+
+  if (waitSelector) {
+    await page.waitForSelector(waitSelector, { timeout })
+  }
+
+  if (waitMs > 0) {
+    await page.waitForTimeout(waitMs)
+  }
+
+  return {
+    finalUrl: page.url(),
+    title: await page.title(),
+    waitUntil,
+    waitSelector: waitSelector || null,
+    waitMs,
+    timeout,
+  }
+}
+
+async function writeJson(outPath, payload) {
+  await mkdir(path.dirname(outPath), { recursive: true })
+  await writeFile(outPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+}
+
+async function collectElementSnapshot(page, selector, fn, errorLabel = 'selector') {
+  return page.evaluate(({ selector: targetSelector, label, evaluateFnSource }) => {
+    const element = document.querySelector(targetSelector)
+
+    if (!element) {
+      throw new Error(`${label} not found: ${targetSelector}`)
+    }
+
+    const evaluateFn = new Function('element', `return (${evaluateFnSource})(element)`)
+
+    return evaluateFn(element)
+  }, { selector, label: errorLabel, evaluateFnSource: fn.toString() })
+}
+
+async function runDomSnapshot(page, args, meta) {
+  const selector = getArg(args, 'selector', 'body')
+  const outPath = defaultOutputPath({
+    action: 'dom-snapshot',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const snapshot = await collectElementSnapshot(page, selector, (element) => {
+    const htmlElement = element
+
+    return {
+      tag_name: htmlElement.tagName.toLowerCase(),
+      id: htmlElement.id || null,
+      class_name: htmlElement.className || '',
+      text_content: htmlElement.textContent ?? '',
+      outer_html: htmlElement.outerHTML,
+    }
+  })
+
+  await writeJson(outPath, {
+    action: 'dom-snapshot',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: meta.navigation.finalUrl,
+    title: meta.navigation.title,
+    selector,
+    snapshot,
+  })
+
+  console.log(outPath)
+}
+
+async function runStyleDump(page, args, meta) {
+  const selector = getArg(args, 'selector', 'body')
+  const cssProps = resolveCssProps(args)
+  const varPrefixes = resolveVarPrefixes(args)
+  const outPath = defaultOutputPath({
+    action: 'style-dump',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const styles = await page.evaluate(({ targetSelector, cssProps: props, prefixes }) => {
+    const element = document.querySelector(targetSelector)
+
+    if (!element) {
+      throw new Error(`selector not found: ${targetSelector}`)
+    }
+
+    const style = getComputedStyle(element)
+    const cssProps = Object.fromEntries(props.map((prop) => [prop, style.getPropertyValue(prop).trim()]))
+    const variables = {}
+
+    for (const property of style) {
+      if (prefixes.some((prefix) => property.startsWith(prefix))) {
+        variables[property] = style.getPropertyValue(property).trim()
+      }
+    }
+
+    return {
+      tag_name: element.tagName.toLowerCase(),
+      class_name: element.className || '',
+      css_props: cssProps,
+      variables,
+    }
+  }, { targetSelector: selector, cssProps, prefixes: varPrefixes })
+
+  await writeJson(outPath, {
+    action: 'style-dump',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: meta.navigation.finalUrl,
+    title: meta.navigation.title,
+    selector,
+    css_props: cssProps,
+    var_prefixes: varPrefixes,
+    styles,
+  })
+
+  console.log(outPath)
+}
+
+async function runLayoutMetrics(page, args, meta) {
+  const selectors = resolveSelectors(args)
+  const outPath = defaultOutputPath({
+    action: 'layout-metrics',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const metrics = await page.evaluate((requestedSelectors) => {
+    const describeElement = (element) => {
+      const rect = element.getBoundingClientRect()
+      const style = getComputedStyle(element)
+      const offsetParent = element.offsetParent
+
+      return {
+        tag_name: element.tagName.toLowerCase(),
+        class_name: element.className || '',
+        rect: {
+          x: rect.x,
+          y: rect.y,
+          top: rect.top,
+          left: rect.left,
+          right: rect.right,
+          bottom: rect.bottom,
+          width: rect.width,
+          height: rect.height,
+        },
+        client: {
+          width: element.clientWidth,
+          height: element.clientHeight,
+        },
+        offset: {
+          width: element.offsetWidth,
+          height: element.offsetHeight,
+          top: element.offsetTop,
+          left: element.offsetLeft,
+        },
+        scroll: {
+          width: element.scrollWidth,
+          height: element.scrollHeight,
+          top: element.scrollTop,
+          left: element.scrollLeft,
+        },
+        computed: {
+          display: style.display,
+          position: style.position,
+          box_sizing: style.boxSizing,
+          margin: style.margin,
+          padding: style.padding,
+          gap: style.gap,
+          z_index: style.zIndex,
+        },
+        offset_parent: offsetParent
+          ? {
+            tag_name: offsetParent.tagName.toLowerCase(),
+            class_name: offsetParent.className || '',
+          }
+          : null,
+      }
+    }
+
+    return {
+      viewport: {
+        inner_width: window.innerWidth,
+        inner_height: window.innerHeight,
+        scroll_x: window.scrollX,
+        scroll_y: window.scrollY,
+      },
+      selectors: requestedSelectors.map((selector) => {
+        const element = document.querySelector(selector)
+
+        return {
+          selector,
+          found: Boolean(element),
+          metrics: element ? describeElement(element) : null,
+        }
+      }),
+    }
+  }, selectors)
+
+  await writeJson(outPath, {
+    action: 'layout-metrics',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: meta.navigation.finalUrl,
+    title: meta.navigation.title,
+    selectors,
+    metrics,
+  })
+
+  console.log(outPath)
+}
+
+async function runA11ySnapshot(page, args, meta) {
+  const selector = getArg(args, 'selector')
+  const timeout = toNumber(getArg(args, 'timeout', '45000'), 45000)
+  const outPath = defaultOutputPath({
+    action: 'a11y-snapshot',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const targetSelector = selector ?? 'body'
+  const locator = page.locator(targetSelector)
+  const elementCount = await locator.count()
+
+  if (elementCount === 0) {
+    throw new Error(`selector not found: ${targetSelector}`)
+  }
+
+  const snapshotYaml = await locator.first().ariaSnapshot({ timeout })
+  const snapshot = snapshotYaml
+    .split('\n')
+    .map((line) => line.replace(/\r$/, ''))
+    .filter((line) => line.length > 0)
+
+  await writeJson(outPath, {
+    action: 'a11y-snapshot',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: meta.navigation.finalUrl,
+    title: meta.navigation.title,
+    selector: targetSelector,
+    matched_count: elementCount,
+    snapshot_yaml: snapshotYaml,
+    snapshot,
+  })
+
+  console.log(outPath)
+}
+
+async function runConsoleCapture(page, args, meta) {
+  const outPath = defaultOutputPath({
+    action: 'console-capture',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const consoleEntries = []
+  const pageErrors = []
+  const requestFailures = []
+
+  page.on('console', (message) => {
+    consoleEntries.push({
+      type: message.type(),
+      text: message.text(),
+      location: message.location(),
+    })
+  })
+
+  page.on('pageerror', (error) => {
+    pageErrors.push({
+      message: error.message,
+      stack: error.stack ?? null,
+    })
+  })
+
+  page.on('requestfailed', (request) => {
+    requestFailures.push({
+      url: request.url(),
+      method: request.method(),
+      resource_type: request.resourceType(),
+      failure_text: request.failure()?.errorText ?? null,
+    })
+  })
+
+  const navigation = await navigate(page, args)
+
+  await writeJson(outPath, {
+    action: 'console-capture',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: navigation.finalUrl,
+    title: navigation.title,
+    console: consoleEntries,
+    page_errors: pageErrors,
+    request_failures: requestFailures,
+  })
+
+  console.log(outPath)
+}
+
+async function runTrace(page, context, args, meta) {
+  const outPath = defaultOutputPath({
+    action: 'trace',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'zip',
+  })
+  const actionSelector = getArg(args, 'action-selector', '')
+  const interaction = getArg(args, 'interaction', 'click')
+
+  await mkdir(path.dirname(outPath), { recursive: true })
+  await context.tracing.start({
+    screenshots: true,
+    snapshots: true,
+    sources: true,
+  })
+
+  const navigation = await navigate(page, args)
+
+  if (actionSelector) {
+    const locator = page.locator(actionSelector)
+
+    if (interaction === 'hover') {
+      await locator.hover()
+    } else if (interaction === 'focus') {
+      await locator.focus()
+    } else {
+      await locator.click()
+    }
+
+    await page.waitForTimeout(toNumber(getArg(args, 'post-action-wait-ms', '400'), 400))
+  }
+
+  await context.tracing.stop({ path: outPath })
+
+  const metaPath = outPath.replace(/\.zip$/i, '.meta.json')
+
+  await writeJson(metaPath, {
+    action: 'trace',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: navigation.finalUrl,
+    title: navigation.title,
+    interaction: actionSelector
+      ? {
+        selector: actionSelector,
+        type: interaction,
+      }
+      : null,
+    trace_path: outPath,
+  })
+
+  console.log(outPath)
+  console.log(metaPath)
+}
+
+async function runNetworkLog(page, args, meta) {
+  const outPath = defaultOutputPath({
+    action: 'network-log',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const entries = []
+  const requestIndex = new Map()
+  let nextId = 1
+
+  page.on('request', (request) => {
+    const entry = {
+      id: nextId,
+      url: request.url(),
+      method: request.method(),
+      resource_type: request.resourceType(),
+      started_at: new Date().toISOString(),
+      status: null,
+      ok: null,
+      failed: false,
+      failure_text: null,
+    }
+
+    nextId += 1
+    entries.push(entry)
+    requestIndex.set(request, entry)
+  })
+
+  page.on('response', (response) => {
+    const entry = requestIndex.get(response.request())
+
+    if (!entry) {
+      return
+    }
+
+    entry.status = response.status()
+    entry.ok = response.ok()
+    entry.ended_at = new Date().toISOString()
+  })
+
+  page.on('requestfailed', (request) => {
+    const entry = requestIndex.get(request)
+
+    if (!entry) {
+      return
+    }
+
+    entry.failed = true
+    entry.failure_text = request.failure()?.errorText ?? null
+    entry.ended_at = new Date().toISOString()
+  })
+
+  const navigation = await navigate(page, args)
+
+  await writeJson(outPath, {
+    action: 'network-log',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: navigation.finalUrl,
+    title: navigation.title,
+    entries,
+  })
+
+  console.log(outPath)
+}
+
+async function runPerfMarks(page, args, meta) {
+  const outPath = defaultOutputPath({
+    action: 'perf-marks',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+
+  const navigation = await navigate(page, args)
+  const perf = await page.evaluate(() => {
+    const serializeEntry = (entry) => ({
+      name: entry.name,
+      entry_type: entry.entryType,
+      start_time: entry.startTime,
+      duration: entry.duration,
+      initiator_type: 'initiatorType' in entry ? entry.initiatorType : undefined,
+      transfer_size: 'transferSize' in entry ? entry.transferSize : undefined,
+      encoded_body_size: 'encodedBodySize' in entry ? entry.encodedBodySize : undefined,
+      decoded_body_size: 'decodedBodySize' in entry ? entry.decodedBodySize : undefined,
+      render_blocking_status: 'renderBlockingStatus' in entry ? entry.renderBlockingStatus : undefined,
+      response_end: 'responseEnd' in entry ? entry.responseEnd : undefined,
+      dom_complete: 'domComplete' in entry ? entry.domComplete : undefined,
+      dom_content_loaded: 'domContentLoadedEventEnd' in entry ? entry.domContentLoadedEventEnd : undefined,
+      load_event_end: 'loadEventEnd' in entry ? entry.loadEventEnd : undefined,
+    })
+
+    return {
+      time_origin: performance.timeOrigin,
+      now: performance.now(),
+      navigation: performance.getEntriesByType('navigation').map(serializeEntry),
+      paints: performance.getEntriesByType('paint').map(serializeEntry),
+      marks: performance.getEntriesByType('mark').map(serializeEntry),
+      measures: performance.getEntriesByType('measure').map(serializeEntry),
+      resources: performance.getEntriesByType('resource').slice(0, 200).map(serializeEntry),
+      memory: 'memory' in performance
+        ? {
+          js_heap_size_limit: performance.memory.jsHeapSizeLimit,
+          total_js_heap_size: performance.memory.totalJSHeapSize,
+          used_js_heap_size: performance.memory.usedJSHeapSize,
+        }
+        : null,
+    }
+  })
+
+  await writeJson(outPath, {
+    action: 'perf-marks',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: navigation.finalUrl,
+    title: navigation.title,
+    perf,
+  })
+
+  console.log(outPath)
+}
+
+async function runTokenDiff(page, args, meta) {
+  const selector = getArg(args, 'selector')
+  const compareSelector = getArg(args, 'compare-selector')
+
+  if (!selector || !compareSelector) {
+    throw new Error('token-diff requires --selector and --compare-selector')
+  }
+
+  const outPath = defaultOutputPath({
+    action: 'token-diff',
+    parsedUrl: meta.parsedUrl,
+    rawUrl: meta.url,
+    out: getArg(args, 'out'),
+    outDir: getArg(args, 'out-dir'),
+    extension: 'json',
+  })
+  const prefixes = resolveVarPrefixes(args)
+
+  const diff = await page.evaluate(({ leftSelector, rightSelector, varPrefixes }) => {
+    const collectVariables = (element) => {
+      const style = getComputedStyle(element)
+      const variables = {}
+
+      for (const property of style) {
+        if (varPrefixes.some((prefix) => property.startsWith(prefix))) {
+          variables[property] = style.getPropertyValue(property).trim()
+        }
+      }
+
+      return variables
+    }
+
+    const left = document.querySelector(leftSelector)
+    const right = document.querySelector(rightSelector)
+
+    if (!left) {
+      throw new Error(`selector not found: ${leftSelector}`)
+    }
+
+    if (!right) {
+      throw new Error(`compare selector not found: ${rightSelector}`)
+    }
+
+    const leftVariables = collectVariables(left)
+    const rightVariables = collectVariables(right)
+    const names = [...new Set([...Object.keys(leftVariables), ...Object.keys(rightVariables)])].sort()
+    const changed = {}
+
+    for (const name of names) {
+      if ((leftVariables[name] ?? null) !== (rightVariables[name] ?? null)) {
+        changed[name] = {
+          left: leftVariables[name] ?? null,
+          right: rightVariables[name] ?? null,
+        }
+      }
+    }
+
+    return {
+      left_selector: leftSelector,
+      right_selector: rightSelector,
+      prefixes: varPrefixes,
+      changed,
+      left_variables: leftVariables,
+      right_variables: rightVariables,
+    }
+  }, { leftSelector: selector, rightSelector: compareSelector, varPrefixes: prefixes })
+
+  await writeJson(outPath, {
+    action: 'token-diff',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: meta.navigation.finalUrl,
+    title: meta.navigation.title,
+    diff,
+  })
+
+  console.log(outPath)
+}
+
+async function runMotionSample(page, args, meta) {
+  const interactionSelector = getArg(args, 'action-selector', '')
+  const interaction = getArg(args, 'interaction', interactionSelector ? 'click' : '')
+  const count = toNumber(getArg(args, 'count', '6'), 6)
+  const intervalMs = toNumber(getArg(args, 'interval-ms', '120'), 120)
+  const fullPage = toBool(getArg(args, 'full-page', 'false'), false)
+  const outDir = getArg(args, 'out-dir')
+    ?? path.join('drafts', 'research', 'motion-sample', defaultStem('motion-sample', meta.parsedUrl, meta.url))
+
+  await mkdir(outDir, { recursive: true })
+
+  const navigation = await navigate(page, args)
+
+  if (interactionSelector) {
+    const locator = page.locator(interactionSelector)
+
+    if (interaction === 'hover') {
+      await locator.hover()
+    } else if (interaction === 'focus') {
+      await locator.focus()
+    } else {
+      await locator.click()
+    }
+  }
+
+  const frames = []
+
+  for (let index = 0; index < count; index += 1) {
+    const filePath = path.join(outDir, `frame-${String(index + 1).padStart(2, '0')}.png`)
+    await page.screenshot({
+      path: filePath,
+      fullPage,
+    })
+
+    frames.push({
+      index: index + 1,
+      elapsed_ms: index * intervalMs,
+      image_path: filePath,
+    })
+
+    if (index < count - 1 && intervalMs > 0) {
+      await page.waitForTimeout(intervalMs)
+    }
+  }
+
+  const metaPath = path.join(outDir, 'meta.json')
+
+  await writeJson(metaPath, {
+    action: 'motion-sample',
+    captured_at: new Date().toISOString(),
+    url_requested: meta.url,
+    url_final: navigation.finalUrl,
+    title: navigation.title,
+    interaction: interactionSelector
+      ? {
+        selector: interactionSelector,
+        type: interaction || null,
+      }
+      : null,
+    count,
+    interval_ms: intervalMs,
+    frames,
+  })
+
+  console.log(outDir)
+  console.log(metaPath)
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const helpRequested = toBool(getArg(args, 'help', 'false'), false)
+
+  if (helpRequested || !getArg(args, 'action')) {
+    usage()
+    process.exit(helpRequested ? 0 : 2)
+  }
+
+  const action = getArg(args, 'action')
+  const requestedUrl = getArg(args, 'url')
+
+  if (!requestedUrl) {
+    throw new Error('expected --url')
+  }
+
+  const parsedUrl = parseHttpUrl(requestedUrl)
+  const url = parsedUrl.toString()
+  const runtime = await createPage(args)
+  const meta = {
+    action,
+    url,
+    parsedUrl,
+    viewport: runtime.viewport,
+    navigation: null,
+  }
+
+  try {
+    if (action === 'console-capture') {
+      await runConsoleCapture(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'network-log') {
+      await runNetworkLog(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'trace') {
+      await runTrace(runtime.page, runtime.context, args, meta)
+      return
+    }
+
+    if (action === 'perf-marks') {
+      await runPerfMarks(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'motion-sample') {
+      await runMotionSample(runtime.page, args, meta)
+      return
+    }
+
+    meta.navigation = await navigate(runtime.page, args)
+
+    if (action === 'dom-snapshot') {
+      await runDomSnapshot(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'style-dump') {
+      await runStyleDump(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'layout-metrics') {
+      await runLayoutMetrics(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'a11y-snapshot') {
+      await runA11ySnapshot(runtime.page, args, meta)
+      return
+    }
+
+    if (action === 'token-diff') {
+      await runTokenDiff(runtime.page, args, meta)
+      return
+    }
+
+    throw new Error(`Unsupported --action value: ${action}`)
+  } finally {
+    await runtime.page.close().catch(() => {})
+    await runtime.context.close().catch(() => {})
+    await runtime.browser.close().catch(() => {})
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof Error) {
+    console.error(error.message)
+  } else {
+    console.error(String(error))
+  }
+
+  process.exit(1)
+})

From cad953bf2809e07abb925b4b39b715155060274c Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 9 Mar 2026 20:40:48 +0400
Subject: [PATCH 35/37] feat: M3 Radio component was added

Closes #20
---
 .../assets/stylesheets/components/index.scss  |   1 +
 .../stylesheets/components/radio/index.scss   | 142 ++++++++++++++++++
 m3-react/src/components/radio/M3Radio.tsx     | 114 ++++++++++++++
 m3-react/src/components/radio/index.ts        |   6 +
 m3-react/src/index.ts                         |   9 ++
 m3-react/storybook/components/M3Radio.mdx     |  70 +++++++++
 .../storybook/components/M3Radio.stories.tsx  |  99 ++++++++++++
 .../storybook/examples/radio/RadioGroup.tsx   |  78 ++++++++++
 m3-react/tests/M3Radio.test.tsx               |  44 ++++++
 m3-vue/src/components/radio/M3Radio.vue       | 117 +++++++++++++++
 m3-vue/src/components/radio/index.ts          |   1 +
 m3-vue/src/index.ts                           |   4 +
 m3-vue/storybook/components/M3Radio.mdx       |  67 +++++++++
 .../storybook/components/M3Radio.stories.ts   | 103 +++++++++++++
 .../storybook/examples/radio/RadioGroup.vue   |  75 +++++++++
 m3-vue/tests/M3Radio.test.ts                  |  42 ++++++
 16 files changed, 972 insertions(+)
 create mode 100644 m3-foundation/assets/stylesheets/components/radio/index.scss
 create mode 100644 m3-react/src/components/radio/M3Radio.tsx
 create mode 100644 m3-react/src/components/radio/index.ts
 create mode 100644 m3-react/storybook/components/M3Radio.mdx
 create mode 100644 m3-react/storybook/components/M3Radio.stories.tsx
 create mode 100644 m3-react/storybook/examples/radio/RadioGroup.tsx
 create mode 100644 m3-react/tests/M3Radio.test.tsx
 create mode 100644 m3-vue/src/components/radio/M3Radio.vue
 create mode 100644 m3-vue/src/components/radio/index.ts
 create mode 100644 m3-vue/storybook/components/M3Radio.mdx
 create mode 100644 m3-vue/storybook/components/M3Radio.stories.ts
 create mode 100644 m3-vue/storybook/examples/radio/RadioGroup.vue
 create mode 100644 m3-vue/tests/M3Radio.test.ts

diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index 0fb04f0..7e6c9db 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -10,6 +10,7 @@
 @use 'navigation';
 @use 'plane-tooltip';
 @use 'popper';
+@use 'radio';
 @use 'rich-tooltip';
 @use 'ripple';
 @use 'scrim';
diff --git a/m3-foundation/assets/stylesheets/components/radio/index.scss b/m3-foundation/assets/stylesheets/components/radio/index.scss
new file mode 100644
index 0000000..7530151
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/radio/index.scss
@@ -0,0 +1,142 @@
+@use "../../basics/motion" as m3-motion;
+@use "../../basics/shape" as m3-shape;
+
+.m3-radio {
+  --state-color: var(--m3-sys-primary);
+  --outline-color: var(--m3-sys-on-surface-variant);
+  --dot-scale: 0;
+
+  --m3-ripple-color: var(--m3-sys-primary);
+  --m3-ripple-effect-duration: 0.75s;
+  --m3-ripple-opacity: 0.2;
+
+  display: inline-block;
+  flex-grow: 0;
+  flex-shrink: 0;
+  width: 40px;
+  height: 40px;
+  padding: 8px;
+  border-radius: 50%;
+  overflow: hidden;
+  cursor: pointer;
+  outline: none;
+  position: relative;
+
+  @include m3-shape.reset-box-sizing;
+
+  &_checked {
+    --outline-color: var(--state-color);
+    --dot-scale: 1;
+  }
+
+  &_invalid {
+    --state-color: var(--m3-sys-error);
+    --outline-color: var(--m3-sys-error);
+    --m3-ripple-color: var(--m3-sys-error);
+  }
+
+  &__input {
+    width: 100%;
+    height: 100%;
+    appearance: none;
+    cursor: inherit;
+    outline: none;
+    position: absolute;
+    left: 0;
+    top: 0;
+    margin: 0;
+    z-index: 1;
+  }
+
+  &__icon {
+    display: inline-block;
+    width: 24px;
+    height: 24px;
+    position: relative;
+    z-index: 0;
+
+    &::before,
+    &::after {
+      content: ' ';
+      display: inline-block;
+      position: absolute;
+      border-radius: 50%;
+      transition:
+        m3-motion.timing-standard(background-color),
+        m3-motion.timing-standard(border-color),
+        m3-motion.timing-standard(transform)
+      ;
+    }
+
+    &::before {
+      width: 20px;
+      height: 20px;
+      border: 2px solid var(--outline-color);
+      left: 2px;
+      top: 2px;
+      box-sizing: border-box;
+    }
+
+    &::after {
+      width: 10px;
+      height: 10px;
+      left: 7px;
+      top: 7px;
+      background-color: var(--state-color);
+      transform: scale(var(--dot-scale));
+    }
+  }
+
+  &__state {
+    display: inline-block;
+    width: 100%;
+    height: 100%;
+    border-radius: inherit;
+    opacity: 0;
+    overflow: hidden;
+    animation: m3-motion.timing-standard(m3-animation-zoom-out);
+    animation-fill-mode: forwards;
+    z-index: 0;
+    position: absolute;
+    left: 0;
+    top: 0;
+
+    &::before {
+      content: ' ';
+      width: 100%;
+      height: 100%;
+      background: var(--state-color);
+      border-radius: inherit;
+      opacity: 0;
+      position: absolute;
+      left: 0;
+      top: 0;
+      transition: m3-motion.timing-standard(opacity);
+    }
+  }
+
+  &__input:hover ~ &__state,
+  &__input:focus ~ &__state {
+    animation: m3-motion.timing-standard(m3-animation-zoom-in);
+    animation-fill-mode: forwards;
+  }
+
+  &__input:hover ~ &__state::before { opacity: 0.08; }
+  &__input:focus ~ &__state::before { opacity: 0.12; }
+
+  &_disabled {
+    cursor: default;
+  }
+
+  &_disabled &__icon::before {
+    border-color: color-mix(in srgb, var(--outline-color) 38%, transparent);
+  }
+
+  &_checked#{&}_disabled &__icon::after {
+    background-color: color-mix(in srgb, var(--state-color) 38%, transparent);
+  }
+
+  &_disabled &__state::before {
+    background: transparent;
+  }
+}
diff --git a/m3-react/src/components/radio/M3Radio.tsx b/m3-react/src/components/radio/M3Radio.tsx
new file mode 100644
index 0000000..94495da
--- /dev/null
+++ b/m3-react/src/components/radio/M3Radio.tsx
@@ -0,0 +1,114 @@
+import type {
+  ForwardRefRenderFunction,
+  HTMLAttributes,
+} from 'react'
+
+import type {
+  Clickable,
+  Focusable,
+} from '@modulify/m3-foundation'
+
+import type { M3RippleMethods } from '@/components/ripple'
+
+import { M3Ripple } from '@/components/ripple'
+
+import {
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react'
+
+import {
+  useElementEffect,
+  useId,
+  useTarget,
+} from '@/hooks'
+
+import { toClassName } from '@/utils/styling'
+
+export interface M3RadioProps extends HTMLAttributes<HTMLElement> {
+  id?: string;
+  name?: string;
+  model?: unknown;
+  value?: unknown;
+  invalid?: boolean;
+  disabled?: boolean;
+  equalsFn?: (a: unknown, b: unknown) => boolean;
+  onChange?: (value: unknown) => void;
+}
+
+export interface M3RadioMethods extends Clickable, Focusable {}
+
+const M3Radio: ForwardRefRenderFunction<
+  M3RadioMethods,
+  M3RadioProps
+> = ({
+  id,
+  name,
+  model,
+  value = true,
+  invalid = false,
+  disabled = false,
+  equalsFn = (a: unknown, b: unknown): boolean => a === b,
+  className = '',
+  onChange = (_: unknown) => {},
+  ...args
+}, ref) => {
+  const root = useRef<HTMLElement | null>(null)
+  const input = useRef<HTMLInputElement | null>(null)
+  const ripple = useRef<M3RippleMethods | null>(null)
+  const [rippleTarget, setRippleTarget] = useTarget<HTMLElement>()
+
+  useImperativeHandle(ref, () => ({
+    click: () => input.current?.click(),
+    focus: () => input.current?.focus(),
+    blur: () => input.current?.blur(),
+  }))
+
+  useElementEffect(root, setRippleTarget)
+
+  const checked = useMemo(() => equalsFn(model, value), [equalsFn, model, value])
+  const inputId = useId(id, 'm3-radio')
+
+  const handleChange = useCallback((nextChecked: boolean) => {
+    if (nextChecked) {
+      onChange(value)
+    }
+  }, [onChange, value])
+
+  return (
+    <span
+      ref={root}
+      className={toClassName([className, {
+        'm3-radio': true,
+        'm3-radio_checked': checked,
+        'm3-radio_invalid': invalid,
+        'm3-radio_disabled': disabled,
+      }])}
+      {...args}
+    >
+      <M3Ripple ref={ripple} owner={rippleTarget} />
+
+      <input
+        ref={input}
+        id={inputId}
+        type="radio"
+        name={name}
+        aria-checked={checked}
+        aria-invalid={invalid}
+        aria-disabled={disabled}
+        className="m3-radio__input"
+        checked={checked}
+        disabled={disabled}
+        onChange={event => handleChange(event.currentTarget.checked)}
+      />
+
+      <span aria-hidden={true} className="m3-radio__state" />
+      <span aria-hidden={true} className="m3-radio__icon" />
+    </span>
+  )
+}
+
+export default forwardRef(M3Radio)
diff --git a/m3-react/src/components/radio/index.ts b/m3-react/src/components/radio/index.ts
new file mode 100644
index 0000000..130f2c3
--- /dev/null
+++ b/m3-react/src/components/radio/index.ts
@@ -0,0 +1,6 @@
+export type {
+  M3RadioMethods,
+  M3RadioProps,
+} from './M3Radio'
+
+export { default as M3Radio } from './M3Radio'
diff --git a/m3-react/src/index.ts b/m3-react/src/index.ts
index 2f47713..a48cb10 100644
--- a/m3-react/src/index.ts
+++ b/m3-react/src/index.ts
@@ -46,6 +46,11 @@ export type {
   M3PopperCloserOptions,
 } from '@/components/popper'
 
+export type {
+  M3RadioMethods,
+  M3RadioProps,
+} from '@/components/radio'
+
 export type {
   M3RichTooltipMethods,
   M3RichTooltipProps,
@@ -143,6 +148,10 @@ export {
   useM3PopperCloserEffect,
 } from '@/components/popper'
 
+export {
+  M3Radio,
+} from '@/components/radio'
+
 export {
   M3RichTooltip,
 } from '@/components/rich-tooltip'
diff --git a/m3-react/storybook/components/M3Radio.mdx b/m3-react/storybook/components/M3Radio.mdx
new file mode 100644
index 0000000..7fa8d36
--- /dev/null
+++ b/m3-react/storybook/components/M3Radio.mdx
@@ -0,0 +1,70 @@
+import { Meta, Unstyled } from '@storybook/addon-docs/blocks'
+
+import RadioGroup from '../examples/radio/RadioGroup'
+import * as M3RadioStories from './M3Radio.stories'
+
+<Meta of={M3RadioStories} />
+
+# Radio buttons
+
+Radio buttons let users choose exactly one option from a related set. Unlike checkboxes, they are not meant for independent multi-selection or parent-child aggregate states.
+
+## API
+
+### When to use
+
+Use `M3Radio` when the user must choose one option from a small, visible list. If multiple options can be selected together, prefer `M3Checkbox`.
+
+### Selection model
+
+This implementation treats each radio as a single-value option. A radio is checked when `model` equals `value`, and selecting it emits that `value`.
+
+### Grouping
+
+For native keyboard and form semantics, related radios should share the same `name`. Wrap related options in a `fieldset` with a visible `legend` whenever possible.
+
+## Accessibility semantics
+
+- Every radio needs a visible text label.
+- Related radios should be grouped under a shared label.
+- Use `name` consistently across one group so browser navigation behaves predictably.
+- Mark the group or options invalid only when the selection is required and unresolved.
+
+### Preference group
+
+<Unstyled className="m3-panel m3-panel_elevated-1">
+  <RadioGroup
+    legend="Theme preference"
+    options={[{
+      label: 'System',
+      value: 'system',
+    }, {
+      label: 'Light',
+      value: 'light',
+    }, {
+      label: 'Dark',
+      value: 'dark',
+    }]}
+  />
+</Unstyled>
+
+## Story guide
+
+- [Standard](?path=/story/components-m3radio--standard)
+- [Preference Group](?path=/story/components-m3radio--preference-group)
+- [Invalid Group](?path=/story/components-m3radio--invalid-group)
+
+## Usage guidance
+
+### Keep option sets short and explicit
+
+Radio groups work best when all options are visible at once and labels are mutually exclusive.
+
+### Do not use radios for toggles
+
+If the choice is simply on/off, prefer a switch or checkbox. Radios communicate one-of-many selection.
+
+## Resources
+
+- [M3 Radio button overview](https://m3.material.io/components/radio-button/overview)
+- [WAI-ARIA APG: Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
diff --git a/m3-react/storybook/components/M3Radio.stories.tsx b/m3-react/storybook/components/M3Radio.stories.tsx
new file mode 100644
index 0000000..edce17a
--- /dev/null
+++ b/m3-react/storybook/components/M3Radio.stories.tsx
@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3Radio } from '@/components/radio'
+import RadioGroup from '../examples/radio/RadioGroup'
+
+import { useState } from 'react'
+import { useId } from '@/hooks'
+
+const meta = {
+  title: 'Components/M3Radio',
+
+  component: M3Radio,
+
+  argTypes: {
+    invalid: {
+      control: 'boolean',
+    },
+
+    disabled: {
+      control: 'boolean',
+    },
+  },
+
+  args: {
+    invalid: false,
+    disabled: false,
+  },
+
+  render: (args) => {
+    const name = useId(null, 'm3-radio-group')
+    const id = useId(null, 'm3-radio')
+    const [model, setModel] = useState('choice')
+
+    return (
+      <label style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: '12px',
+      }}
+      >
+        <M3Radio
+          id={id}
+          name={name}
+          model={model}
+          value="choice"
+          onChange={setModel}
+          {...args}
+        />
+
+        <span>Choice</span>
+      </label>
+    )
+  },
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Radio>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {}
+
+export const PreferenceGroup: Story = {
+  render: () => (
+    <RadioGroup
+      legend="Notification channel"
+      options={[{
+        label: 'Email',
+        value: 'email',
+      }, {
+        label: 'Push',
+        value: 'push',
+      }, {
+        label: 'SMS',
+        value: 'sms',
+        disabled: true,
+      }]}
+    />
+  ),
+}
+
+export const InvalidGroup: Story = {
+  render: () => (
+    <RadioGroup
+      legend="Release cadence"
+      invalid={true}
+      options={[{
+        label: 'Stable',
+        value: 'stable',
+      }, {
+        label: 'Preview',
+        value: 'preview',
+      }]}
+    />
+  ),
+}
diff --git a/m3-react/storybook/examples/radio/RadioGroup.tsx b/m3-react/storybook/examples/radio/RadioGroup.tsx
new file mode 100644
index 0000000..eb2bfed
--- /dev/null
+++ b/m3-react/storybook/examples/radio/RadioGroup.tsx
@@ -0,0 +1,78 @@
+import { M3Radio } from '@/components/radio'
+
+import { useId } from '@/hooks'
+import { useState } from 'react'
+
+export interface RadioOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  legend?: string;
+  options: RadioOption[];
+  invalid?: boolean;
+}
+
+const RadioGroup = ({
+  legend = 'Selection',
+  options,
+  invalid = false,
+}: RadioGroupProps) => {
+  const name = useId(null, 'm3-radio-group')
+  const [model, setModel] = useState(options[0]?.value)
+
+  return (
+    <fieldset style={{
+      margin: 0,
+      padding: 0,
+      border: 'none',
+      display: 'grid',
+      gap: '12px',
+      minWidth: '280px',
+    }}
+    >
+      <legend style={{
+        padding: 0,
+        marginBottom: '8px',
+        fontSize: '14px',
+        lineHeight: '20px',
+        color: 'var(--m3-sys-on-surface-variant)',
+      }}
+      >
+        {legend}
+      </legend>
+
+      {options.map(option => {
+        const id = `${name}-${option.value}`
+
+        return (
+          <label
+            key={option.value}
+            htmlFor={id}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '12px',
+            }}
+          >
+            <M3Radio
+              id={id}
+              name={name}
+              model={model}
+              value={option.value}
+              invalid={invalid}
+              disabled={option.disabled}
+              onChange={setModel}
+            />
+
+            <span>{option.label}</span>
+          </label>
+        )
+      })}
+    </fieldset>
+  )
+}
+
+export default RadioGroup
diff --git a/m3-react/tests/M3Radio.test.tsx b/m3-react/tests/M3Radio.test.tsx
new file mode 100644
index 0000000..59c6d63
--- /dev/null
+++ b/m3-react/tests/M3Radio.test.tsx
@@ -0,0 +1,44 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react'
+
+import { M3Radio } from '@/components/radio'
+
+describe('m3-react/radio', () => {
+  test('reflects checked state and emits selected value', () => {
+    const onChange = vi.fn()
+
+    render(
+      <M3Radio
+        name="channel"
+        model="push"
+        value="email"
+        invalid={true}
+        onChange={onChange}
+      />
+    )
+
+    const input = screen.getByRole('radio') as HTMLInputElement
+
+    expect(input.getAttribute('aria-invalid')).toBe('true')
+    expect(input.checked).toBe(false)
+
+    fireEvent.click(input)
+
+    expect(onChange).toHaveBeenCalledWith('email')
+  })
+
+  test('supports custom equality', () => {
+    render(
+      <M3Radio
+        model={{ id: 2 }}
+        value={{ id: 2 }}
+        equalsFn={(a, b) => (a as { id: number }).id === (b as { id: number }).id}
+      />
+    )
+
+    expect((screen.getByRole('radio') as HTMLInputElement).checked).toBe(true)
+  })
+})
diff --git a/m3-vue/src/components/radio/M3Radio.vue b/m3-vue/src/components/radio/M3Radio.vue
new file mode 100644
index 0000000..948a918
--- /dev/null
+++ b/m3-vue/src/components/radio/M3Radio.vue
@@ -0,0 +1,117 @@
+<template>
+    <span
+        ref="root"
+        :class="{
+            'm3-radio': true,
+            'm3-radio_checked': checked,
+            'm3-radio_invalid': invalid,
+            'm3-radio_disabled': disabled,
+        }"
+        v-bind="$attrs"
+    >
+        <M3Ripple :owner="ref(root)" />
+
+        <input
+            :id="_id"
+            ref="_input"
+            :name="name"
+            :aria-checked="checked ? 'true' : 'false'"
+            :aria-invalid="invalid ? 'true' : 'false'"
+            :aria-disabled="disabled ? 'true' : 'false'"
+            :checked="checked"
+            :disabled="disabled"
+            type="radio"
+            class="m3-radio__input"
+            @change="onChange"
+        />
+
+        <span aria-hidden="true" class="m3-radio__state" />
+        <span aria-hidden="true" class="m3-radio__icon" />
+    </span>
+</template>
+
+<script lang="ts" setup>
+import type { Interactive } from '@modulify/m3-foundation'
+import type { PropType } from 'vue'
+
+import { M3Ripple } from '@/components/ripple'
+
+import {
+  computed,
+  ref,
+} from 'vue'
+
+import {
+  isId,
+  isUndefined,
+  Or,
+} from '@modulify/m3-foundation/lib/predicates'
+
+import useId from '@/composables/id'
+
+const props = defineProps({
+  id: {
+    type: null as unknown as PropType<string | undefined>,
+    validator: Or(isId, isUndefined),
+    default: undefined,
+  },
+
+  name: {
+    type: null as unknown as PropType<string | undefined>,
+    default: undefined,
+  },
+
+  model: {
+    type: null as unknown as PropType<unknown>,
+    default: undefined as unknown,
+  },
+
+  value: {
+    type: null as unknown as PropType<unknown>,
+    default: true as unknown,
+  },
+
+  invalid: {
+    type: Boolean,
+    default: false,
+  },
+
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+
+  equalsFn: {
+    type: Function as PropType<(a: unknown, b: unknown) => boolean>,
+    default: (a: unknown, b: unknown): boolean => a === b,
+  },
+})
+
+const emit = defineEmits([
+  'change',
+  'update:model',
+])
+
+const root = ref<HTMLElement | null>(null)
+
+const _id = useId('m3-radio', computed(() => props.id))
+const _input = ref<HTMLInputElement | null>(null)
+
+defineExpose({
+  click: () => _input.value?.click(),
+  focus: () => _input.value?.focus(),
+  blur: () => _input.value?.blur(),
+} satisfies Interactive)
+
+const equals = (a: unknown, b: unknown) => props.equalsFn.call(null, a, b)
+const checked = computed(() => equals(props.model, props.value))
+
+const onChange = (event: Event) => {
+  if (!(event.target as HTMLInputElement).checked) {
+    return
+  }
+
+  emit('change', props.value)
+  emit('update:model', props.value)
+}
+</script>
diff --git a/m3-vue/src/components/radio/index.ts b/m3-vue/src/components/radio/index.ts
new file mode 100644
index 0000000..2c7fa93
--- /dev/null
+++ b/m3-vue/src/components/radio/index.ts
@@ -0,0 +1 @@
+export { default as M3Radio } from './M3Radio.vue'
diff --git a/m3-vue/src/index.ts b/m3-vue/src/index.ts
index b8ad7e4..5f0ef64 100644
--- a/m3-vue/src/index.ts
+++ b/m3-vue/src/index.ts
@@ -58,6 +58,10 @@ export {
   vM3PopperCloser,
 } from '@/components/popper'
 
+export {
+  M3Radio,
+} from '@/components/radio'
+
 export {
   M3RichTooltip,
 } from '@/components/rich-tooltip'
diff --git a/m3-vue/storybook/components/M3Radio.mdx b/m3-vue/storybook/components/M3Radio.mdx
new file mode 100644
index 0000000..475fdb2
--- /dev/null
+++ b/m3-vue/storybook/components/M3Radio.mdx
@@ -0,0 +1,67 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import Inline from './Inline'
+import RadioGroup from '../examples/radio/RadioGroup.vue'
+import * as M3RadioStories from './M3Radio.stories'
+
+<Meta of={M3RadioStories} />
+
+# Radio buttons
+
+Radio buttons let users choose exactly one option from a related set. Unlike checkboxes, they are not meant for independent multi-selection or parent-child aggregate states.
+
+## API
+
+### When to use
+
+Use `M3Radio` when the user must choose one option from a small, visible list. If multiple options can be selected together, prefer `M3Checkbox`.
+
+### Selection model
+
+This implementation treats each radio as a single-value option. A radio is checked when `model` equals `value`, and selecting it emits that `value`.
+
+### Grouping
+
+For native keyboard and form semantics, related radios should share the same `name`. Wrap related options in a `fieldset` with a visible `legend` whenever possible.
+
+## Accessibility semantics
+
+- Every radio needs a visible text label.
+- Related radios should be grouped under a shared label.
+- Use `name` consistently across one group so browser navigation behaves predictably.
+- Mark the group or options invalid only when the selection is required and unresolved.
+
+### Preference group
+
+<div className="m3-panel m3-panel_elevated-1">
+  <Inline is={RadioGroup} legend="Theme preference" options={[{
+    label: 'System',
+    value: 'system',
+  }, {
+    label: 'Light',
+    value: 'light',
+  }, {
+    label: 'Dark',
+    value: 'dark',
+  }]} />
+</div>
+
+## Story guide
+
+- [Standard](?path=/story/components-m3radio--standard)
+- [Preference Group](?path=/story/components-m3radio--preference-group)
+- [Invalid Group](?path=/story/components-m3radio--invalid-group)
+
+## Usage guidance
+
+### Keep option sets short and explicit
+
+Radio groups work best when all options are visible at once and labels are mutually exclusive.
+
+### Do not use radios for toggles
+
+If the choice is simply on/off, prefer a switch or checkbox. Radios communicate one-of-many selection.
+
+## Resources
+
+- [M3 Radio button overview](https://m3.material.io/components/radio-button/overview)
+- [WAI-ARIA APG: Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
diff --git a/m3-vue/storybook/components/M3Radio.stories.ts b/m3-vue/storybook/components/M3Radio.stories.ts
new file mode 100644
index 0000000..72c8da7
--- /dev/null
+++ b/m3-vue/storybook/components/M3Radio.stories.ts
@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3Radio } from '@/components/radio'
+import RadioGroup from '../examples/radio/RadioGroup.vue'
+import { ref } from 'vue'
+
+import useId from '@/composables/id'
+
+const meta = {
+  title: 'Components/M3Radio',
+
+  component: M3Radio,
+
+  args: {
+    invalid: false,
+    disabled: false,
+  },
+
+  render: (args: unknown) => ({
+    components: {
+      M3Radio,
+    },
+
+    setup: () => ({
+      id: useId('m3-radio'),
+      name: useId('m3-radio-group'),
+      args,
+      model: ref('choice'),
+    }),
+
+    template: `
+      <label style="display: flex; align-items: center; gap: 12px;">
+          <M3Radio
+              :id="id"
+              :name="name"
+              :model="model"
+              value="choice"
+              v-bind="args"
+              @update:model="model = $event"
+          />
+
+          <span>Choice</span>
+      </label>
+    `,
+  }),
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Radio>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {}
+
+export const PreferenceGroup: Story = {
+  render: () => ({
+    components: {
+      RadioGroup,
+    },
+
+    template: `
+      <RadioGroup
+          legend="Notification channel"
+          :options="[{
+              label: 'Email',
+              value: 'email',
+          }, {
+              label: 'Push',
+              value: 'push',
+          }, {
+              label: 'SMS',
+              value: 'sms',
+              disabled: true,
+          }]"
+      />
+    `,
+  }),
+}
+
+export const InvalidGroup: Story = {
+  render: () => ({
+    components: {
+      RadioGroup,
+    },
+
+    template: `
+      <RadioGroup
+          legend="Release cadence"
+          invalid
+          :options="[{
+              label: 'Stable',
+              value: 'stable',
+          }, {
+              label: 'Preview',
+              value: 'preview',
+          }]"
+      />
+    `,
+  }),
+}
diff --git a/m3-vue/storybook/examples/radio/RadioGroup.vue b/m3-vue/storybook/examples/radio/RadioGroup.vue
new file mode 100644
index 0000000..a6e403d
--- /dev/null
+++ b/m3-vue/storybook/examples/radio/RadioGroup.vue
@@ -0,0 +1,75 @@
+<template>
+    <fieldset :style="fieldsetStyle">
+        <legend :style="legendStyle">
+            {{ legend }}
+        </legend>
+
+        <label
+            v-for="option in options"
+            :key="option.value"
+            :for="name + '-' + option.value"
+            :style="labelStyle"
+        >
+            <M3Radio
+                :id="name + '-' + option.value"
+                :name="name"
+                :model="model"
+                :value="option.value"
+                :invalid="invalid"
+                :disabled="option.disabled"
+                @update:model="model = $event"
+            />
+
+            <span>{{ option.label }}</span>
+        </label>
+    </fieldset>
+</template>
+
+<script lang="ts" setup>
+import { M3Radio } from '@/components/radio'
+
+import { ref } from 'vue'
+
+import useId from '@/composables/id'
+
+export interface RadioOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+}
+
+const props = withDefaults(defineProps<{
+  legend?: string;
+  options: RadioOption[];
+  invalid?: boolean;
+}>(), {
+  legend: 'Selection',
+  invalid: false,
+})
+
+const name = useId('m3-radio-group')
+const model = ref(props.options[0]?.value)
+
+const fieldsetStyle = {
+  margin: 0,
+  padding: 0,
+  border: 'none',
+  display: 'grid',
+  gap: '12px',
+  minWidth: '280px',
+}
+
+const legendStyle = {
+  padding: 0,
+  marginBottom: '8px',
+  fontSize: '14px',
+  lineHeight: '20px',
+  color: 'var(--m3-sys-on-surface-variant)',
+}
+
+const labelStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: '12px',
+}
+</script>
diff --git a/m3-vue/tests/M3Radio.test.ts b/m3-vue/tests/M3Radio.test.ts
new file mode 100644
index 0000000..2c88e64
--- /dev/null
+++ b/m3-vue/tests/M3Radio.test.ts
@@ -0,0 +1,42 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/vue'
+
+import { M3Radio } from '@/components/radio'
+
+describe('m3-vue/radio', () => {
+  test('reflects checked state and emits selected value', async () => {
+    const view = render(M3Radio, {
+      props: {
+        name: 'channel',
+        model: 'push',
+        value: 'email',
+        invalid: true,
+      } as Record<string, unknown>,
+    })
+
+    const input = screen.getByRole('radio') as HTMLInputElement
+
+    expect(input.getAttribute('aria-invalid')).toBe('true')
+    expect(input.checked).toBe(false)
+
+    await fireEvent.click(input)
+
+    expect(view.emitted().change?.[0]).toEqual(['email'])
+    expect(view.emitted()['update:model']?.[0]).toEqual(['email'])
+  })
+
+  test('supports custom equality', () => {
+    render(M3Radio, {
+      props: {
+        model: { id: 2 },
+        value: { id: 2 },
+        equalsFn: (a: { id: number }, b: { id: number }) => a.id === b.id,
+      } as Record<string, unknown>,
+    })
+
+    expect((screen.getByRole('radio') as HTMLInputElement).checked).toBe(true)
+  })
+})

From 3ac34caee6218e35494ec424eb29a200b2b2cda6 Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 9 Mar 2026 23:50:43 +0400
Subject: [PATCH 36/37] feat: M3 Chip component was added

Closes #15
---
 .../stylesheets/components/chip/index.scss    | 215 ++++++++++++++++++
 .../assets/stylesheets/components/index.scss  |   1 +
 m3-foundation/types/components/chip.d.ts      |   1 +
 m3-react/src/components/chip/M3Chip.tsx       | 181 +++++++++++++++
 m3-react/src/components/chip/index.ts         |   5 +
 m3-react/src/index.ts                         |   9 +
 m3-react/storybook/components/M3Chip.mdx      |  75 ++++++
 .../storybook/components/M3Chip.stories.tsx   |  90 ++++++++
 .../storybook/examples/chip/ChipShowcase.tsx  |  89 ++++++++
 m3-react/tests/M3Chip.test.tsx                |  60 +++++
 m3-vue/src/components/chip/M3Chip.vue         | 210 +++++++++++++++++
 m3-vue/src/components/chip/index.ts           |   1 +
 m3-vue/src/components/chip/properties.ts      |  13 ++
 m3-vue/src/components/chip/values.ts          |   3 +
 m3-vue/src/index.ts                           |   4 +
 m3-vue/storybook/components/M3Chip.mdx        |  75 ++++++
 m3-vue/storybook/components/M3Chip.stories.ts |  98 ++++++++
 .../storybook/examples/chip/ChipShowcase.vue  |  87 +++++++
 m3-vue/tests/M3Chip.test.ts                   |  63 +++++
 19 files changed, 1280 insertions(+)
 create mode 100644 m3-foundation/assets/stylesheets/components/chip/index.scss
 create mode 100644 m3-foundation/types/components/chip.d.ts
 create mode 100644 m3-react/src/components/chip/M3Chip.tsx
 create mode 100644 m3-react/src/components/chip/index.ts
 create mode 100644 m3-react/storybook/components/M3Chip.mdx
 create mode 100644 m3-react/storybook/components/M3Chip.stories.tsx
 create mode 100644 m3-react/storybook/examples/chip/ChipShowcase.tsx
 create mode 100644 m3-react/tests/M3Chip.test.tsx
 create mode 100644 m3-vue/src/components/chip/M3Chip.vue
 create mode 100644 m3-vue/src/components/chip/index.ts
 create mode 100644 m3-vue/src/components/chip/properties.ts
 create mode 100644 m3-vue/src/components/chip/values.ts
 create mode 100644 m3-vue/storybook/components/M3Chip.mdx
 create mode 100644 m3-vue/storybook/components/M3Chip.stories.ts
 create mode 100644 m3-vue/storybook/examples/chip/ChipShowcase.vue
 create mode 100644 m3-vue/tests/M3Chip.test.ts

diff --git a/m3-foundation/assets/stylesheets/components/chip/index.scss b/m3-foundation/assets/stylesheets/components/chip/index.scss
new file mode 100644
index 0000000..27bef0a
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/chip/index.scss
@@ -0,0 +1,215 @@
+@use '../../basics/motion' as m3-motion;
+@use '../../basics/typography' as m3-typography;
+
+.m3-chip {
+  --m3-icon-size: 18px;
+  --m3-ripple-color: var(--m3-sys-on-surface-variant);
+  --m3-ripple-opacity: 0.16;
+  --chip-container-color: transparent;
+  --chip-outline-color: var(--m3-sys-outline);
+  --chip-label-color: var(--m3-sys-on-surface);
+  --chip-state-color: var(--m3-sys-on-surface);
+  --chip-shadow: none;
+
+  display: inline-flex;
+  align-items: stretch;
+  min-height: 32px;
+  max-width: 100%;
+  border-radius: 8px;
+  background: var(--chip-container-color);
+  box-shadow: var(--chip-shadow);
+  position: relative;
+  overflow: hidden;
+  vertical-align: middle;
+  transition:
+    m3-motion.timing-standard(background-color),
+    m3-motion.timing-standard(box-shadow)
+  ;
+
+  &,
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  &::before {
+    content: ' ';
+    border: 1px solid var(--chip-outline-color);
+    border-radius: inherit;
+    position: absolute;
+    inset: 0;
+    transition: m3-motion.timing-standard(border-color);
+    pointer-events: none;
+  }
+
+  &_assist {
+    --m3-ripple-color: var(--m3-sys-primary);
+    --chip-state-color: var(--m3-sys-primary);
+  }
+
+  &_filter {
+    --m3-ripple-color: var(--m3-sys-on-surface);
+    --chip-state-color: var(--m3-sys-on-surface);
+  }
+
+  &_filter#{&}_selected {
+    --m3-ripple-color: var(--m3-sys-on-secondary-container);
+    --chip-container-color: var(--m3-sys-secondary-container);
+    --chip-outline-color: transparent;
+    --chip-label-color: var(--m3-sys-on-secondary-container);
+    --chip-state-color: var(--m3-sys-on-secondary-container);
+  }
+
+  &_input {
+    --chip-container-color: var(--m3-sys-surface-container-low);
+    --chip-label-color: var(--m3-sys-on-surface);
+    --chip-state-color: var(--m3-sys-on-surface);
+  }
+
+  &_suggestion {
+    --chip-container-color: var(--m3-sys-surface-container-lowest);
+    --chip-label-color: var(--m3-sys-on-surface);
+    --chip-state-color: var(--m3-sys-on-surface);
+    --chip-shadow: var(--m3-elevation-1);
+  }
+
+  &_dismissible &__action {
+    padding-right: 10px;
+  }
+
+  &__action,
+  &__dismiss {
+    @include m3-typography.label-large;
+
+    appearance: none;
+    display: inline-flex;
+    align-items: center;
+    background: transparent;
+    border: none;
+    color: inherit;
+    cursor: pointer;
+    margin: 0;
+    outline: none;
+    position: relative;
+    z-index: 0;
+    overflow: hidden;
+  }
+
+  &__action {
+    min-height: 32px;
+    min-width: 0;
+    padding: 0 16px;
+    color: var(--chip-label-color);
+    flex: 1 1 auto;
+    border-radius: inherit;
+  }
+
+  &_has-leading-icon &__action,
+  &_has-checkmark &__action {
+    padding-left: 12px;
+  }
+
+  &_has-trailing-icon &__action {
+    padding-right: 12px;
+  }
+
+  &__dismiss {
+    width: 32px;
+    min-height: 32px;
+    justify-content: center;
+    color: var(--chip-label-color);
+    flex: 0 0 32px;
+    border-radius: 0 8px 8px 0;
+  }
+
+  &_dismissible &__action {
+    border-radius: 8px 0 0 8px;
+  }
+
+  &_dismissible &__dismiss::before {
+    content: ' ';
+    width: 1px;
+    position: absolute;
+    left: 0;
+    top: 8px;
+    bottom: 8px;
+    background: color-mix(in srgb, var(--chip-outline-color) 60%, transparent);
+  }
+
+  &__state {
+    width: 100%;
+    height: 100%;
+    background: var(--chip-state-color);
+    border-radius: inherit;
+    overflow: hidden;
+    opacity: 0;
+    position: absolute;
+    inset: 0;
+    transition:
+      m3-motion.timing-standard(background-color),
+      m3-motion.timing-standard(opacity)
+    ;
+    pointer-events: none;
+  }
+
+  &__content {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    min-width: 0;
+    position: relative;
+    z-index: 1;
+  }
+
+  &__icon,
+  &__label {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  &__icon {
+    flex: 0 0 auto;
+  }
+
+  &__label {
+    min-width: 0;
+    padding-top: 1px;
+    white-space: nowrap;
+  }
+
+  &__action:hover &__state,
+  &__dismiss:hover &__state {
+    opacity: 0.08;
+  }
+
+  &__action:focus-visible &__state,
+  &__dismiss:focus-visible &__state,
+  &__action:active &__state,
+  &__dismiss:active &__state {
+    opacity: 0.12;
+  }
+
+  &_disabled {
+    --m3-ripple-opacity: 0;
+    --chip-container-color: color-mix(in srgb, var(--chip-container-color) 100%, transparent);
+    --chip-outline-color: color-mix(in srgb, var(--m3-sys-on-surface) 12%, transparent);
+    --chip-label-color: color-mix(in srgb, var(--m3-sys-on-surface) 38%, transparent);
+    --chip-state-color: transparent;
+    --chip-shadow: none;
+  }
+
+  &_disabled &__action,
+  &_disabled &__dismiss {
+    cursor: default;
+  }
+
+  &_disabled &__dismiss::before {
+    background: color-mix(in srgb, var(--m3-sys-on-surface) 12%, transparent);
+  }
+
+  &_disabled &__state {
+    opacity: 0;
+  }
+}
diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index 7e6c9db..c0fd8c2 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -1,6 +1,7 @@
 @use 'badge';
 @use 'button';
 @use 'card';
+@use 'chip';
 @use 'checkbox';
 @use 'dialog';
 @use 'fab-button';
diff --git a/m3-foundation/types/components/chip.d.ts b/m3-foundation/types/components/chip.d.ts
new file mode 100644
index 0000000..a4499d8
--- /dev/null
+++ b/m3-foundation/types/components/chip.d.ts
@@ -0,0 +1 @@
+export type Variant = 'assist' | 'filter' | 'input' | 'suggestion'
diff --git a/m3-react/src/components/chip/M3Chip.tsx b/m3-react/src/components/chip/M3Chip.tsx
new file mode 100644
index 0000000..49e2b7e
--- /dev/null
+++ b/m3-react/src/components/chip/M3Chip.tsx
@@ -0,0 +1,181 @@
+import type {
+  ButtonHTMLAttributes,
+  ForwardRefRenderFunction,
+  MouseEventHandler,
+  ReactNode,
+} from 'react'
+
+import type { Variant } from '@modulify/m3-foundation/types/components/chip'
+import type {
+  Clickable,
+  Focusable,
+} from '@modulify/m3-foundation'
+
+import type { M3RippleMethods } from '@/components/ripple'
+
+import {
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+} from 'react'
+
+import { M3Icon } from '@/components/icon'
+import { M3Ripple } from '@/components/ripple'
+
+import {
+  useElementEffect,
+  useTarget,
+} from '@/hooks'
+
+import { normalize } from '@/utils/content'
+import { toClassName } from '@/utils/styling'
+
+export interface M3ChipProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onToggle'> {
+  variant?: Variant;
+  selected?: boolean;
+  showCheckmark?: boolean;
+  dismissible?: boolean;
+  dismissLabel?: string;
+  onToggle?: (selected: boolean) => void;
+  onDismiss?: () => void;
+}
+
+export interface M3ChipMethods extends Clickable, Focusable {}
+
+const M3Chip: ForwardRefRenderFunction<M3ChipMethods, M3ChipProps> = ({
+  type = 'button',
+  variant = 'assist',
+  selected = false,
+  showCheckmark = true,
+  dismissible = false,
+  dismissLabel = 'Remove',
+  disabled = false,
+  className = '',
+  style,
+  children = [],
+  onClick = () => {},
+  onKeyUp = () => {},
+  onToggle = () => {},
+  onDismiss,
+  ...actionAttrs
+}, ref) => {
+  const action = useRef<HTMLButtonElement | null>(null)
+  const dismiss = useRef<HTMLButtonElement | null>(null)
+  const actionRipple = useRef<M3RippleMethods | null>(null)
+  const dismissRipple = useRef<M3RippleMethods | null>(null)
+
+  const [actionRippleTarget, setActionRippleTarget] = useTarget<HTMLButtonElement>()
+  const [dismissRippleTarget, setDismissRippleTarget] = useTarget<HTMLButtonElement>()
+
+  useElementEffect(action, setActionRippleTarget)
+  useElementEffect(dismiss, setDismissRippleTarget)
+
+  useImperativeHandle(ref, () => ({
+    click: () => action.current?.click(),
+    focus: () => action.current?.focus(),
+    blur: () => action.current?.blur(),
+  }))
+
+  const content = useMemo(() => normalize(children), [children])
+
+  const hasText = useMemo(() => content.some(([, isIcon]) => !isIcon), [content])
+  const [, hasLeadingIcon] = content[0] ?? [null, false]
+  const [, hasTrailingIcon] = content[content.length - 1] ?? [null, false]
+
+  const hasCheckmark = variant === 'filter' && selected && showCheckmark && !hasLeadingIcon
+  const hasDismiss = dismissible || typeof onDismiss === 'function'
+
+  const renderItem = useCallback((child: ReactNode, isIcon: boolean, key: string) => (
+    <span
+      key={key}
+      className={toClassName({
+        'm3-chip__icon': isIcon,
+        'm3-chip__label': !isIcon,
+      })}
+    >
+      {child}
+    </span>
+  ), [])
+
+  return (
+    <span
+      className={toClassName([className, {
+        'm3-chip': true,
+        ['m3-chip_' + variant]: true,
+        'm3-chip_selected': selected,
+        'm3-chip_disabled': disabled,
+        'm3-chip_dismissible': hasDismiss,
+        'm3-chip_has-leading-icon': hasText && hasLeadingIcon,
+        'm3-chip_has-trailing-icon': hasText && hasTrailingIcon,
+        'm3-chip_has-checkmark': hasCheckmark,
+      }])}
+      style={style}
+    >
+      <button
+        ref={action}
+        type={type}
+        className="m3-chip__action"
+        disabled={disabled}
+        aria-pressed={variant === 'filter' ? selected : undefined}
+        onClick={(event) => {
+          onClick(event)
+
+          if (!event.defaultPrevented && variant === 'filter') {
+            onToggle(!selected)
+          }
+        }}
+        onKeyUp={event => {
+          if (event.code === 'Enter') {
+            actionRipple.current?.activate(event.nativeEvent)
+          }
+
+          onKeyUp(event)
+        }}
+        {...actionAttrs}
+      >
+        <M3Ripple ref={actionRipple} owner={actionRippleTarget} />
+        <span className="m3-chip__state" />
+        <span className="m3-chip__content">
+          {hasCheckmark ? (
+            <span className="m3-chip__icon m3-chip__icon_selection">
+              <M3Icon name="check" />
+            </span>
+          ) : null}
+
+          {content.map(([child, isIcon], index) => renderItem(child, isIcon, `chip-content-${index}`))}
+        </span>
+      </button>
+
+      {hasDismiss ? (
+        <button
+          ref={dismiss}
+          type="button"
+          className="m3-chip__dismiss"
+          disabled={disabled}
+          aria-label={dismissLabel}
+          onClick={(event) => {
+            event.stopPropagation()
+            onDismiss?.()
+          }}
+          onKeyUp={event => {
+            if (event.code === 'Enter') {
+              dismissRipple.current?.activate(event.nativeEvent)
+            }
+          }}
+        >
+          <M3Ripple ref={dismissRipple} owner={dismissRippleTarget} centered={true} />
+          <span className="m3-chip__state" />
+          <span className="m3-chip__content">
+            <span className="m3-chip__icon">
+              <M3Icon name="close" />
+            </span>
+          </span>
+        </button>
+      ) : null}
+    </span>
+  )
+}
+
+export default forwardRef(M3Chip)
diff --git a/m3-react/src/components/chip/index.ts b/m3-react/src/components/chip/index.ts
new file mode 100644
index 0000000..06c82da
--- /dev/null
+++ b/m3-react/src/components/chip/index.ts
@@ -0,0 +1,5 @@
+export { default as M3Chip } from './M3Chip'
+export type {
+  M3ChipMethods,
+  M3ChipProps,
+} from './M3Chip'
diff --git a/m3-react/src/index.ts b/m3-react/src/index.ts
index a48cb10..4956b2d 100644
--- a/m3-react/src/index.ts
+++ b/m3-react/src/index.ts
@@ -15,6 +15,11 @@ export type {
   M3CheckboxProps,
 } from '@/components/checkbox'
 
+export type {
+  M3ChipMethods,
+  M3ChipProps,
+} from '@/components/chip'
+
 export type {
   M3IconProps,
 } from '@/components/icon'
@@ -113,6 +118,10 @@ export {
   M3Checkbox,
 } from '@/components/checkbox'
 
+export {
+  M3Chip,
+} from '@/components/chip'
+
 export {
   M3FabButton,
 } from '@/components/fab-button'
diff --git a/m3-react/storybook/components/M3Chip.mdx b/m3-react/storybook/components/M3Chip.mdx
new file mode 100644
index 0000000..b8d45e8
--- /dev/null
+++ b/m3-react/storybook/components/M3Chip.mdx
@@ -0,0 +1,75 @@
+import { Meta, Unstyled } from '@storybook/addon-docs/blocks'
+
+import ChipShowcase from '../examples/chip/ChipShowcase'
+import * as M3ChipStories from './M3Chip.stories'
+
+<Meta of={M3ChipStories} />
+
+# Chips
+
+Chips help people enter information, make selections, filter content, or trigger actions. Material 3 distinguishes four chip types: assist, filter, input, and suggestion.
+
+## API
+
+### When to use
+
+Use `M3Chip` for compact, contextual actions or selections that should stay visible inside the surrounding content. If the action needs stronger emphasis or more copy, prefer buttons.
+
+### Variants
+
+- `assist` for quick contextual actions such as "Remind later"
+- `filter` for toggleable filters that stay visible as active constraints
+- `input` for entered entities or tokens that can usually be removed
+- `suggestion` for lightweight recommendations that help users continue a flow
+
+### Selection and dismissal
+
+This implementation keeps `filter` chips controlled through `selected` and `onToggle`. Input chips can expose a separate dismiss affordance through `dismissible` and `onDismiss`.
+
+## Accessibility semantics
+
+- There is no special ARIA chip role here; the primary surface uses native button semantics.
+- Filter chips expose toggle state through `aria-pressed`.
+- If a chip exposes a remove affordance, the trailing dismiss button should keep an explicit accessible label.
+- Chip labels should stay short and scannable because they are often read in dense horizontal clusters.
+
+### Variant panel
+
+<Unstyled className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <ChipShowcase mode="matrix" />
+</Unstyled>
+
+### Filter set
+
+<Unstyled className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <ChipShowcase mode="filters" />
+</Unstyled>
+
+### Input tokens
+
+<Unstyled className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <ChipShowcase mode="inputs" />
+</Unstyled>
+
+## Story guide
+
+- [Standard](?path=/story/components-m3chip--standard)
+- [Variant Matrix](?path=/story/components-m3chip--variant-matrix)
+- [Filter Set](?path=/story/components-m3chip--filter-set)
+- [Input Tokens](?path=/story/components-m3chip--input-tokens)
+
+## Usage guidance
+
+### Keep chip copy brief
+
+Chips work best with short labels that can be scanned in rows. If the label turns into a sentence, the interaction usually wants a button or list row instead.
+
+### Match semantics to intent
+
+Use assist and suggestion chips as action affordances. Use filter chips only when the selected state matters. Use input chips when the item itself becomes part of the current form or scope.
+
+## Resources
+
+- [M3 Chips overview](https://m3.material.io/components/chips/overview)
+- [M3 Chips guidelines](https://m3.material.io/components/chips/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-react/storybook/components/M3Chip.stories.tsx b/m3-react/storybook/components/M3Chip.stories.tsx
new file mode 100644
index 0000000..aed4ae0
--- /dev/null
+++ b/m3-react/storybook/components/M3Chip.stories.tsx
@@ -0,0 +1,90 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3Chip } from '@/components/chip'
+import { M3Icon } from '@/components/icon'
+import ChipShowcase from '../examples/chip/ChipShowcase'
+
+import {
+  useEffect,
+  useState,
+} from 'react'
+
+const meta = {
+  title: 'Components/M3Chip',
+
+  component: M3Chip,
+
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['assist', 'filter', 'input', 'suggestion'],
+    },
+
+    selected: {
+      control: 'boolean',
+    },
+
+    disabled: {
+      control: 'boolean',
+    },
+
+    dismissible: {
+      control: 'boolean',
+    },
+
+    showCheckmark: {
+      control: 'boolean',
+    },
+  },
+
+  args: {
+    variant: 'assist',
+    selected: false,
+    disabled: false,
+    dismissible: false,
+    showCheckmark: true,
+  },
+
+  render: (args) => {
+    const [selected, setSelected] = useState(args.selected)
+
+    useEffect(() => {
+      setSelected(args.selected)
+    }, [args.selected])
+
+    return (
+      <M3Chip
+        {...args}
+        selected={selected}
+        onToggle={setSelected}
+      >
+        {args.variant === 'assist' || args.variant === 'suggestion'
+          ? <M3Icon name={args.variant === 'assist' ? 'schedule' : 'lightbulb'} />
+          : null}
+        {args.variant === 'input' ? 'Project Alpha' : 'Remind later'}
+      </M3Chip>
+    )
+  },
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Chip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {}
+
+export const VariantMatrix: Story = {
+  render: () => <ChipShowcase mode="matrix" />,
+}
+
+export const FilterSet: Story = {
+  render: () => <ChipShowcase mode="filters" />,
+}
+
+export const InputTokens: Story = {
+  render: () => <ChipShowcase mode="inputs" />,
+}
diff --git a/m3-react/storybook/examples/chip/ChipShowcase.tsx b/m3-react/storybook/examples/chip/ChipShowcase.tsx
new file mode 100644
index 0000000..6e2f292
--- /dev/null
+++ b/m3-react/storybook/examples/chip/ChipShowcase.tsx
@@ -0,0 +1,89 @@
+import type { FC } from 'react'
+
+import { M3Chip } from '@/components/chip'
+import { M3Icon } from '@/components/icon'
+
+import { useState } from 'react'
+
+export interface ChipShowcaseProps {
+  mode?: 'matrix' | 'filters' | 'inputs';
+}
+
+const wrapStyle = {
+  display: 'flex',
+  flexWrap: 'wrap' as const,
+  gap: '12px',
+}
+
+const ChipShowcase: FC<ChipShowcaseProps> = ({
+  mode = 'matrix',
+}) => {
+  const [filters, setFilters] = useState<string[]>(['Assigned to me', 'Urgent'])
+  const [tokens, setTokens] = useState<string[]>(['Onboarding', 'Billing', 'Design review'])
+
+  if (mode === 'filters') {
+    const options = ['Assigned to me', 'Urgent', 'Needs review']
+
+    return (
+      <div style={wrapStyle}>
+        {options.map(option => (
+          <M3Chip
+            key={option}
+            variant="filter"
+            selected={filters.includes(option)}
+            onToggle={selected => {
+              setFilters(current => {
+                return selected
+                  ? [...current, option]
+                  : current.filter(value => value !== option)
+              })
+            }}
+          >
+            {option}
+          </M3Chip>
+        ))}
+      </div>
+    )
+  }
+
+  if (mode === 'inputs') {
+    return (
+      <div style={wrapStyle}>
+        {tokens.map(token => (
+          <M3Chip
+            key={token}
+            variant="input"
+            dismissible={true}
+            onDismiss={() => setTokens(current => current.filter(value => value !== token))}
+          >
+            {token}
+          </M3Chip>
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <div style={wrapStyle}>
+      <M3Chip variant="assist">
+        <M3Icon name="schedule" />
+        Remind later
+      </M3Chip>
+
+      <M3Chip variant="filter" selected={true}>
+        Updates
+      </M3Chip>
+
+      <M3Chip variant="input" dismissible={true}>
+        Project Alpha
+      </M3Chip>
+
+      <M3Chip variant="suggestion">
+        <M3Icon name="lightbulb" />
+        Draft summary
+      </M3Chip>
+    </div>
+  )
+}
+
+export default ChipShowcase
diff --git a/m3-react/tests/M3Chip.test.tsx b/m3-react/tests/M3Chip.test.tsx
new file mode 100644
index 0000000..1e506f8
--- /dev/null
+++ b/m3-react/tests/M3Chip.test.tsx
@@ -0,0 +1,60 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react'
+
+import { M3Chip } from '@/components/chip'
+
+describe('m3-react/chip', () => {
+  test('toggles selected state for filter chips via aria-pressed', () => {
+    const onToggle = vi.fn()
+
+    render(
+      <M3Chip variant="filter" selected={false} onToggle={onToggle}>
+        Updates
+      </M3Chip>
+    )
+
+    const button = screen.getByRole('button', { name: 'Updates' })
+
+    expect(button.getAttribute('aria-pressed')).toBe('false')
+
+    fireEvent.click(button)
+
+    expect(onToggle).toHaveBeenCalledWith(true)
+  })
+
+  test('renders dismiss affordance independently from the main action', () => {
+    const onClick = vi.fn()
+    const onDismiss = vi.fn()
+
+    render(
+      <M3Chip
+        variant="input"
+        dismissible={true}
+        onClick={onClick}
+        onDismiss={onDismiss}
+      >
+        Project Alpha
+      </M3Chip>
+    )
+
+    const dismiss = screen.getByRole('button', { name: 'Remove' })
+
+    fireEvent.click(dismiss)
+
+    expect(onDismiss).toHaveBeenCalledTimes(1)
+    expect(onClick).not.toHaveBeenCalled()
+  })
+
+  test('shows selection icon for selected filter chips without a leading icon', () => {
+    const { container } = render(
+      <M3Chip variant="filter" selected={true}>
+        Assigned to me
+      </M3Chip>
+    )
+
+    expect(container.querySelector('.m3-chip__icon_selection')).not.toBeNull()
+  })
+})
diff --git a/m3-vue/src/components/chip/M3Chip.vue b/m3-vue/src/components/chip/M3Chip.vue
new file mode 100644
index 0000000..d48545b
--- /dev/null
+++ b/m3-vue/src/components/chip/M3Chip.vue
@@ -0,0 +1,210 @@
+<template>
+    <span
+        :class="rootClass"
+        :style="rootStyle"
+    >
+        <button
+            ref="action"
+            :type="type"
+            class="m3-chip__action"
+            :disabled="disabled"
+            :aria-pressed="variant === 'filter' ? selected : undefined"
+            v-bind="actionAttrs"
+            @click="onActionClick"
+            @keyup="onActionKeyup"
+        >
+            <M3Ripple
+                ref="actionRipple"
+                :owner="ref(action)"
+            />
+
+            <span class="m3-chip__state" />
+            <span class="m3-chip__content">
+                <span v-if="hasCheckmark" class="m3-chip__icon m3-chip__icon_selection">
+                    <M3Icon name="check" />
+                </span>
+
+                <M3ChipContent />
+            </span>
+        </button>
+
+        <button
+            v-if="dismissible"
+            ref="dismiss"
+            type="button"
+            class="m3-chip__dismiss"
+            :disabled="disabled"
+            :aria-label="dismissLabel"
+            @click="onDismissClick"
+            @keyup="onDismissKeyup"
+        >
+            <M3Ripple
+                ref="dismissRipple"
+                :owner="ref(dismiss)"
+                centered
+            />
+
+            <span class="m3-chip__state" />
+            <span class="m3-chip__content">
+                <span class="m3-chip__icon">
+                    <M3Icon name="close" />
+                </span>
+            </span>
+        </button>
+    </span>
+</template>
+
+<script lang="ts" setup>
+import type { Interactive } from '@modulify/m3-foundation'
+import type {
+  PropType,
+  StyleValue,
+} from 'vue'
+
+import { M3Icon } from '@/components/icon'
+import { M3Ripple } from '@/components/ripple'
+
+import {
+  computed,
+  h,
+  ref,
+  useAttrs,
+  useSlots,
+} from 'vue'
+
+import { normalize } from '@/utils/runtime'
+
+import * as properties from './properties'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+const props = defineProps({
+  type: {
+    type: String as PropType<HTMLButtonElement['type']>,
+    default: 'button',
+  },
+
+  variant: properties.variant,
+
+  selected: {
+    type: Boolean,
+    default: false,
+  },
+
+  showCheckmark: {
+    type: Boolean,
+    default: true,
+  },
+
+  dismissible: {
+    type: Boolean,
+    default: false,
+  },
+
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+
+  dismissLabel: {
+    type: String,
+    default: 'Remove',
+  },
+})
+
+const emit = defineEmits([
+  'click',
+  'dismiss',
+  'toggle',
+  'update:selected',
+])
+
+const attrs = useAttrs() as Record<string, unknown>
+const slots = useSlots()
+
+const content = computed(() => normalize(slots.default?.() ?? []))
+
+const hasCheckmark = computed(() => {
+  const [, hasLeadingIcon] = content.value[0] ?? [null, false]
+
+  return props.variant === 'filter'
+    && props.selected
+    && props.showCheckmark
+    && !hasLeadingIcon
+})
+
+const rootClass = computed(() => {
+  const hasText = content.value.some(([, isIcon]) => !isIcon)
+  const [, hasLeadingIcon] = content.value[0] ?? [null, false]
+  const [, hasTrailingIcon] = content.value[content.value.length - 1] ?? [null, false]
+
+  return [attrs.class, {
+    'm3-chip': true,
+    ['m3-chip_' + props.variant]: true,
+    'm3-chip_selected': props.selected,
+    'm3-chip_disabled': props.disabled,
+    'm3-chip_dismissible': props.dismissible,
+    'm3-chip_has-leading-icon': hasText && hasLeadingIcon,
+    'm3-chip_has-trailing-icon': hasText && hasTrailingIcon,
+    'm3-chip_has-checkmark': hasCheckmark.value,
+  }]
+})
+const rootStyle = computed(() => attrs.style as StyleValue | undefined)
+
+const action = ref<HTMLButtonElement | null>(null)
+const actionAttrs = computed(() => {
+  const {
+    class: _class,
+    style: _style,
+    ...rest
+  } = attrs
+
+  return rest
+})
+const actionRipple = ref<InstanceType<typeof M3Ripple> | null>(null)
+
+const onActionClick = (event: MouseEvent) => {
+  emit('click', event)
+
+  if (!event.defaultPrevented && props.variant === 'filter') {
+    emit('toggle', !props.selected)
+    emit('update:selected', !props.selected)
+  }
+}
+
+const onActionKeyup = (event: KeyboardEvent) => {
+  if (event.code === 'Enter') {
+    actionRipple.value?.activate(event)
+  }
+}
+
+const dismiss = ref<HTMLButtonElement | null>(null)
+const dismissRipple = ref<InstanceType<typeof M3Ripple> | null>(null)
+
+const onDismissClick = (event: MouseEvent) => {
+  event.stopPropagation()
+  emit('dismiss')
+}
+
+const onDismissKeyup = (event: KeyboardEvent) => {
+  if (event.code === 'Enter') {
+    dismissRipple.value?.activate(event)
+  }
+}
+
+const M3ChipContent = () => content.value.map(([node, isIcon], index) => h('span', {
+  class: {
+    'm3-chip__icon': isIcon,
+    'm3-chip__label': !isIcon,
+  },
+  key: `chip-content-${index}`,
+}, { ...node }))
+
+defineExpose({
+  click: () => action.value?.click(),
+  focus: () => action.value?.focus(),
+  blur: () => action.value?.blur(),
+} satisfies Interactive)
+</script>
diff --git a/m3-vue/src/components/chip/index.ts b/m3-vue/src/components/chip/index.ts
new file mode 100644
index 0000000..03bc42e
--- /dev/null
+++ b/m3-vue/src/components/chip/index.ts
@@ -0,0 +1 @@
+export { default as M3Chip } from './M3Chip.vue'
diff --git a/m3-vue/src/components/chip/properties.ts b/m3-vue/src/components/chip/properties.ts
new file mode 100644
index 0000000..b481ace
--- /dev/null
+++ b/m3-vue/src/components/chip/properties.ts
@@ -0,0 +1,13 @@
+import type {
+  Prop,
+  PropType,
+} from 'vue'
+import type { Variant } from '@modulify/m3-foundation/types/components/chip'
+
+import { variants } from './values'
+
+export const variant: Prop<Variant, 'assist'> = {
+  type: String as PropType<Variant>,
+  validator: (value: string) => variants.includes(value as Variant),
+  default: 'assist',
+}
diff --git a/m3-vue/src/components/chip/values.ts b/m3-vue/src/components/chip/values.ts
new file mode 100644
index 0000000..0837eb8
--- /dev/null
+++ b/m3-vue/src/components/chip/values.ts
@@ -0,0 +1,3 @@
+import type { Variant } from '@modulify/m3-foundation/types/components/chip'
+
+export const variants: Variant[] = ['assist', 'filter', 'input', 'suggestion']
diff --git a/m3-vue/src/index.ts b/m3-vue/src/index.ts
index 5f0ef64..33d67eb 100644
--- a/m3-vue/src/index.ts
+++ b/m3-vue/src/index.ts
@@ -17,6 +17,10 @@ export {
   M3Checkbox,
 } from '@/components/checkbox'
 
+export {
+  M3Chip,
+} from '@/components/chip'
+
 export {
   M3FabButton,
 } from '@/components/fab-button'
diff --git a/m3-vue/storybook/components/M3Chip.mdx b/m3-vue/storybook/components/M3Chip.mdx
new file mode 100644
index 0000000..8ffd6a1
--- /dev/null
+++ b/m3-vue/storybook/components/M3Chip.mdx
@@ -0,0 +1,75 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import Inline from './Inline'
+import ChipShowcase from '../examples/chip/ChipShowcase.vue'
+import * as M3ChipStories from './M3Chip.stories'
+
+<Meta of={M3ChipStories} />
+
+# Chips
+
+Chips help people enter information, make selections, filter content, or trigger actions. Material 3 distinguishes four chip types: assist, filter, input, and suggestion.
+
+## API
+
+### When to use
+
+Use `M3Chip` for compact, contextual actions or selections that should stay visible inside the surrounding content. If the action needs stronger emphasis or more copy, prefer buttons.
+
+### Variants
+
+- `assist` for quick contextual actions such as "Remind later"
+- `filter` for toggleable filters that stay visible as active constraints
+- `input` for entered entities or tokens that can usually be removed
+- `suggestion` for lightweight recommendations that help users continue a flow
+
+### Selection and dismissal
+
+This implementation keeps `filter` chips controlled through `selected` and `update:selected`. Input chips can expose a separate dismiss affordance through `dismissible` and `dismiss`.
+
+## Accessibility semantics
+
+- There is no special ARIA chip role here; the primary surface uses native button semantics.
+- Filter chips expose toggle state through `aria-pressed`.
+- If a chip exposes a remove affordance, the trailing dismiss button should keep an explicit accessible label.
+- Chip labels should stay short and scannable because they are often read in dense horizontal clusters.
+
+### Variant panel
+
+<div className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <Inline is={ChipShowcase} mode="matrix" />
+</div>
+
+### Filter set
+
+<div className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <Inline is={ChipShowcase} mode="filters" />
+</div>
+
+### Input tokens
+
+<div className="m3-panel m3-panel_elevated-1" style={{ padding: '16px' }}>
+  <Inline is={ChipShowcase} mode="inputs" />
+</div>
+
+## Story guide
+
+- [Standard](?path=/story/components-m3chip--standard)
+- [Variant Matrix](?path=/story/components-m3chip--variant-matrix)
+- [Filter Set](?path=/story/components-m3chip--filter-set)
+- [Input Tokens](?path=/story/components-m3chip--input-tokens)
+
+## Usage guidance
+
+### Keep chip copy brief
+
+Chips work best with short labels that can be scanned in rows. If the label turns into a sentence, the interaction usually wants a button or list row instead.
+
+### Match semantics to intent
+
+Use assist and suggestion chips as action affordances. Use filter chips only when the selected state matters. Use input chips when the item itself becomes part of the current form or scope.
+
+## Resources
+
+- [M3 Chips overview](https://m3.material.io/components/chips/overview)
+- [M3 Chips guidelines](https://m3.material.io/components/chips/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Chip.stories.ts b/m3-vue/storybook/components/M3Chip.stories.ts
new file mode 100644
index 0000000..b80d1be
--- /dev/null
+++ b/m3-vue/storybook/components/M3Chip.stories.ts
@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3Chip } from '@/components/chip'
+import { M3Icon } from '@/components/icon'
+import ChipShowcase from '../examples/chip/ChipShowcase.vue'
+
+import { ref, watch } from 'vue'
+
+const standardTemplate = `
+  <M3Chip
+      v-bind="args"
+      :selected="selected"
+      @update:selected="selected = $event"
+  >
+      <M3Icon
+          v-if="args.variant === 'assist' || args.variant === 'suggestion'"
+          :name="args.variant === 'assist' ? 'schedule' : 'lightbulb'"
+      />
+
+      {{ args.variant === 'input' ? 'Project Alpha' : 'Remind later' }}
+  </M3Chip>
+`
+
+const renderStandard = (args: Record<string, unknown>) => ({
+  components: {
+    M3Chip,
+    M3Icon,
+  },
+
+  setup: () => {
+    const selected = ref(Boolean(args.selected))
+
+    watch(() => args.selected, value => selected.value = Boolean(value), { immediate: true })
+
+    return {
+      args,
+      selected,
+    }
+  },
+
+  template: standardTemplate,
+})
+
+const meta = {
+  title: 'Components/M3Chip',
+
+  component: M3Chip,
+
+  args: {
+    variant: 'assist',
+    selected: false,
+    disabled: false,
+    dismissible: false,
+    showCheckmark: true,
+  },
+
+  render: renderStandard,
+
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof M3Chip>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Standard: Story = {}
+
+export const VariantMatrix: Story = {
+  render: () => ({
+    components: {
+      ChipShowcase,
+    },
+
+    template: '<ChipShowcase mode="matrix" />',
+  }),
+}
+
+export const FilterSet: Story = {
+  render: () => ({
+    components: {
+      ChipShowcase,
+    },
+
+    template: '<ChipShowcase mode="filters" />',
+  }),
+}
+
+export const InputTokens: Story = {
+  render: () => ({
+    components: {
+      ChipShowcase,
+    },
+
+    template: '<ChipShowcase mode="inputs" />',
+  }),
+}
diff --git a/m3-vue/storybook/examples/chip/ChipShowcase.vue b/m3-vue/storybook/examples/chip/ChipShowcase.vue
new file mode 100644
index 0000000..a66378c
--- /dev/null
+++ b/m3-vue/storybook/examples/chip/ChipShowcase.vue
@@ -0,0 +1,87 @@
+<template>
+    <div class="m3-chip-showcase">
+        <template v-if="mode === 'filters'">
+            <M3Chip
+                v-for="option in filterOptions"
+                :key="option"
+                variant="filter"
+                :selected="filters.includes(option)"
+                @update:selected="onToggleFilter(option, $event)"
+            >
+                {{ option }}
+            </M3Chip>
+        </template>
+
+        <template v-else-if="mode === 'inputs'">
+            <M3Chip
+                v-for="token in tokens"
+                :key="token"
+                variant="input"
+                dismissible
+                @dismiss="removeToken(token)"
+            >
+                {{ token }}
+            </M3Chip>
+        </template>
+
+        <template v-else>
+            <M3Chip variant="assist">
+                <M3Icon name="schedule" />
+                Remind later
+            </M3Chip>
+
+            <M3Chip variant="filter" :selected="true">
+                Updates
+            </M3Chip>
+
+            <M3Chip variant="input" dismissible>
+                Project Alpha
+            </M3Chip>
+
+            <M3Chip variant="suggestion">
+                <M3Icon name="lightbulb" />
+                Draft summary
+            </M3Chip>
+        </template>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+
+import { M3Chip } from '@/components/chip'
+import { M3Icon } from '@/components/icon'
+
+defineProps({
+  mode: {
+    type: String as () => 'matrix' | 'filters' | 'inputs',
+    default: 'matrix',
+  },
+})
+
+const filterOptions = ['Assigned to me', 'Urgent', 'Needs review']
+
+const filters = ref<string[]>(['Assigned to me', 'Urgent'])
+const tokens = ref<string[]>(['Onboarding', 'Billing', 'Design review'])
+
+const onToggleFilter = (option: string, selected: boolean) => {
+  if (selected) {
+    filters.value = [...filters.value, option]
+    return
+  }
+
+  filters.value = filters.value.filter(value => value !== option)
+}
+
+const removeToken = (token: string) => {
+  tokens.value = tokens.value.filter(value => value !== token)
+}
+</script>
+
+<style scoped>
+.m3-chip-showcase {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+}
+</style>
diff --git a/m3-vue/tests/M3Chip.test.ts b/m3-vue/tests/M3Chip.test.ts
new file mode 100644
index 0000000..533a23f
--- /dev/null
+++ b/m3-vue/tests/M3Chip.test.ts
@@ -0,0 +1,63 @@
+import {
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/vue'
+
+import { M3Chip } from '@/components/chip'
+
+describe('m3-vue/chip', () => {
+  test('toggles selected state for filter chips via aria-pressed', async () => {
+    const view = render(M3Chip, {
+      props: {
+        variant: 'filter',
+        selected: false,
+      },
+      slots: {
+        default: 'Updates',
+      },
+    })
+
+    const button = screen.getByRole('button', { name: 'Updates' })
+
+    expect(button.getAttribute('aria-pressed')).toBe('false')
+
+    await fireEvent.click(button)
+
+    expect(view.emitted().toggle?.[0]).toEqual([true])
+    expect(view.emitted()['update:selected']?.[0]).toEqual([true])
+  })
+
+  test('renders dismiss affordance independently from the main action', async () => {
+    const view = render(M3Chip, {
+      props: {
+        variant: 'input',
+        dismissible: true,
+      },
+      slots: {
+        default: 'Project Alpha',
+      },
+    })
+
+    const dismiss = screen.getByRole('button', { name: 'Remove' })
+
+    await fireEvent.click(dismiss)
+
+    expect(view.emitted().dismiss?.length).toBe(1)
+    expect(view.emitted().click).toBeUndefined()
+  })
+
+  test('shows selection icon for selected filter chips without a leading icon', () => {
+    const { container } = render(M3Chip, {
+      props: {
+        variant: 'filter',
+        selected: true,
+      },
+      slots: {
+        default: 'Assigned to me',
+      },
+    })
+
+    expect(container.querySelector('.m3-chip__icon_selection')).not.toBeNull()
+  })
+})

From 8cc8a507568c57462910a3ac533141985c8378dc Mon Sep 17 00:00:00 2001
From: Kirill Zaytsev <zaytsev.cmath10@gmail.com>
Date: Mon, 9 Mar 2026 23:50:57 +0400
Subject: [PATCH 37/37] chore: Eslint max-lines limit was raised

---
 m3-foundation/eslint.config.js                      | 2 +-
 m3-react/eslint.config.js                           | 2 +-
 m3-vue/eslint.config.js                             | 2 +-
 m3-vue/src/components/button/M3Button.ts            | 1 -
 m3-vue/src/components/fab-button/M3FabButton.ts     | 1 -
 m3-vue/storybook/components/M3Button.stories.ts     | 1 -
 m3-vue/storybook/components/M3Card.stories.ts       | 2 --
 m3-vue/storybook/components/M3FabButton.stories.ts  | 1 -
 m3-vue/storybook/components/M3IconButton.stories.ts | 1 -
 m3-vue/storybook/components/M3Navigation.stories.ts | 1 -
 m3-vue/storybook/components/M3ScrollRail.stories.ts | 1 -
 m3-vue/storybook/components/M3Select.stories.ts     | 2 --
 12 files changed, 3 insertions(+), 14 deletions(-)

diff --git a/m3-foundation/eslint.config.js b/m3-foundation/eslint.config.js
index 8f49a1c..9b63781 100644
--- a/m3-foundation/eslint.config.js
+++ b/m3-foundation/eslint.config.js
@@ -47,7 +47,7 @@ export default [
         SwitchCase: 1,
       }],
       'linebreak-style': [2, 'unix'],
-      'max-lines-per-function': ['error', 30],
+      'max-lines-per-function': ['error', 50],
       'max-nested-callbacks': ['error', 3],
       'no-console': 'off',
       'no-constant-condition': 'off',
diff --git a/m3-react/eslint.config.js b/m3-react/eslint.config.js
index e2bac2b..a6ff438 100644
--- a/m3-react/eslint.config.js
+++ b/m3-react/eslint.config.js
@@ -53,7 +53,7 @@ export default [
         SwitchCase: 1,
       }],
       'linebreak-style': [2, 'unix'],
-      'max-lines-per-function': ['error', 30],
+      'max-lines-per-function': ['error', 50],
       'max-nested-callbacks': ['error', 3],
       'no-console': 'off',
       'no-constant-condition': 'off',
diff --git a/m3-vue/eslint.config.js b/m3-vue/eslint.config.js
index d1083e4..e119d9b 100644
--- a/m3-vue/eslint.config.js
+++ b/m3-vue/eslint.config.js
@@ -50,7 +50,7 @@ export default [
         SwitchCase: 1,
       }],
       'linebreak-style': [2, 'unix'],
-      'max-lines-per-function': ['error', 30],
+      'max-lines-per-function': ['error', 50],
       'max-nested-callbacks': ['error', 3],
       'no-console': 'off',
       'no-constant-condition': 'off',
diff --git a/m3-vue/src/components/button/M3Button.ts b/m3-vue/src/components/button/M3Button.ts
index f6a1c9f..1f63282 100644
--- a/m3-vue/src/components/button/M3Button.ts
+++ b/m3-vue/src/components/button/M3Button.ts
@@ -48,7 +48,6 @@ export default defineComponent({
     },
   },
 
-  // eslint-disable-next-line max-lines-per-function
   setup (props, { attrs, expose, slots }) {
     const root = ref<M3LinkInstance | null>(null)
     const rootElement = computed(() => root.value?.el() ?? null)
diff --git a/m3-vue/src/components/fab-button/M3FabButton.ts b/m3-vue/src/components/fab-button/M3FabButton.ts
index 0d24775..774c0e5 100644
--- a/m3-vue/src/components/fab-button/M3FabButton.ts
+++ b/m3-vue/src/components/fab-button/M3FabButton.ts
@@ -54,7 +54,6 @@ export default defineComponent({
     },
   },
 
-  // eslint-disable-next-line max-lines-per-function
   setup (props, { attrs, expose, slots }) {
     const root = ref<M3LinkInstance | null>(null)
     const rootElement = computed(() => root.value?.el() ?? null)
diff --git a/m3-vue/storybook/components/M3Button.stories.ts b/m3-vue/storybook/components/M3Button.stories.ts
index 369f569..eaf4524 100644
--- a/m3-vue/storybook/components/M3Button.stories.ts
+++ b/m3-vue/storybook/components/M3Button.stories.ts
@@ -70,7 +70,6 @@ export const WithLeadingIcon: Story = {
 }
 
 export const AppearanceMatrix: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: () => ({
     components: {
       M3Button,
diff --git a/m3-vue/storybook/components/M3Card.stories.ts b/m3-vue/storybook/components/M3Card.stories.ts
index 7084269..b1b44a6 100644
--- a/m3-vue/storybook/components/M3Card.stories.ts
+++ b/m3-vue/storybook/components/M3Card.stories.ts
@@ -92,7 +92,6 @@ export const LandscapeWithoutMedia: Story = {
 }
 
 export const Portrait: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: (args: unknown) => ({
     components: {
       M3Button,
@@ -134,7 +133,6 @@ export const Portrait: Story = {
 }
 
 export const AppearanceMatrix: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: () => ({
     components: {
       M3Card,
diff --git a/m3-vue/storybook/components/M3FabButton.stories.ts b/m3-vue/storybook/components/M3FabButton.stories.ts
index 6e22250..d8dc9c5 100644
--- a/m3-vue/storybook/components/M3FabButton.stories.ts
+++ b/m3-vue/storybook/components/M3FabButton.stories.ts
@@ -83,7 +83,6 @@ export const Extended: Story = {
 }
 
 export const VariantMatrix: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: () => ({
     components: {
       M3FabButton,
diff --git a/m3-vue/storybook/components/M3IconButton.stories.ts b/m3-vue/storybook/components/M3IconButton.stories.ts
index 330e77d..05c0890 100644
--- a/m3-vue/storybook/components/M3IconButton.stories.ts
+++ b/m3-vue/storybook/components/M3IconButton.stories.ts
@@ -92,7 +92,6 @@ export const Toggleable: Story = {
 }
 
 export const AppearanceMatrix: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: () => ({
     components: {
       M3Icon,
diff --git a/m3-vue/storybook/components/M3Navigation.stories.ts b/m3-vue/storybook/components/M3Navigation.stories.ts
index 28b5779..b884bce 100644
--- a/m3-vue/storybook/components/M3Navigation.stories.ts
+++ b/m3-vue/storybook/components/M3Navigation.stories.ts
@@ -137,7 +137,6 @@ export const NavigationRail: Story = {
 }
 
 export const ModalNavigationDrawer: Story = {
-  // eslint-disable-next-line max-lines-per-function
   render: (args: unknown) => ({
     name: 'M3ModalNavigationDrawerStory',
 
diff --git a/m3-vue/storybook/components/M3ScrollRail.stories.ts b/m3-vue/storybook/components/M3ScrollRail.stories.ts
index fccaa15..b729526 100644
--- a/m3-vue/storybook/components/M3ScrollRail.stories.ts
+++ b/m3-vue/storybook/components/M3ScrollRail.stories.ts
@@ -22,7 +22,6 @@ const meta = {
     disabled: false,
   },
 
-  // eslint-disable-next-line max-lines-per-function
   render: (args: unknown) => ({
     name: 'M3ScrollRailStory',
 
diff --git a/m3-vue/storybook/components/M3Select.stories.ts b/m3-vue/storybook/components/M3Select.stories.ts
index 0593983..2729635 100644
--- a/m3-vue/storybook/components/M3Select.stories.ts
+++ b/m3-vue/storybook/components/M3Select.stories.ts
@@ -29,7 +29,6 @@ const meta = {
     },
   },
 
-  // eslint-disable-next-line max-lines-per-function
   render: (args: unknown) => ({
     name: 'M3SelectStory',
 
@@ -83,7 +82,6 @@ export const WithIcons: Story = {
     label: 'Country',
   },
 
-  // eslint-disable-next-line max-lines-per-function
   render: (args: unknown) => ({
     name: 'M3SelectStory',