From e01f750f9ebe2e5f3b37712c872c4476328f1ff5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:33:59 -0300
Subject: [PATCH 1/6] fix(drawer): share motion state and defer close for exit
 animation

Centralize useDrawerMotionState in drawer-portal and inject it into overlay
and content so enter/exit transitions stay in sync. Defer painting closed
state on exit so the slide-out animation can run.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../composables/use-drawer-motion-state.ts       | 16 ++++++++++++++--
 .../components/overlay/drawer/drawer-overlay.vue |  7 +++----
 .../components/overlay/drawer/drawer-portal.vue  |  9 +++++++--
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/webkit/src/components/overlay/drawer/composables/use-drawer-motion-state.ts b/packages/webkit/src/components/overlay/drawer/composables/use-drawer-motion-state.ts
index ed9bdae4a..c13f918a2 100644
--- a/packages/webkit/src/components/overlay/drawer/composables/use-drawer-motion-state.ts
+++ b/packages/webkit/src/components/overlay/drawer/composables/use-drawer-motion-state.ts
@@ -5,7 +5,9 @@ import type { DrawerMotionState } from '../presets/transitions'
 export type { DrawerMotionState }
 
 /**
- * Drives `data-state` for CSS transitions: paints `closed` first, then flips to `open` on the next frame.
+ * Drives `data-state` for CSS transitions.
+ * Enter: paints `closed` first, then `open` on the next frame.
+ * Exit: keeps `open` for one frame, then `closed` so the browser can interpolate.
  */
 export function useDrawerMotionState(isOpen: Ref<boolean>) {
   const motionState = ref<DrawerMotionState>('closed')
@@ -21,11 +23,21 @@ export function useDrawerMotionState(isOpen: Ref<boolean>) {
     })
   }
 
+  const paintClose = async () => {
+    await nextTick()
+
+    globalThis.requestAnimationFrame(() => {
+      if (!isOpen.value) {
+        motionState.value = 'closed'
+      }
+    })
+  }
+
   watch(
     isOpen,
     (open) => {
       if (!open) {
-        motionState.value = 'closed'
+        void paintClose()
         return
       }
 
diff --git a/packages/webkit/src/components/overlay/drawer/drawer-overlay.vue b/packages/webkit/src/components/overlay/drawer/drawer-overlay.vue
index 9808e17a2..7f528e9da 100644
--- a/packages/webkit/src/components/overlay/drawer/drawer-overlay.vue
+++ b/packages/webkit/src/components/overlay/drawer/drawer-overlay.vue
@@ -2,8 +2,7 @@
   import { computed, inject, useAttrs } from 'vue'
 
   import { cn } from '../../../utils/cn'
-  import { useDrawerMotionState } from './composables/use-drawer-motion-state'
-  import { DrawerInjectionKey } from './injection-key'
+  import { DrawerInjectionKey, DrawerMotionInjectionKey } from './injection-key'
   import { drawerOverlayTransitionClasses, getDrawerTransitionStyle } from './presets/transitions'
 
   defineOptions({
@@ -13,8 +12,8 @@
 
   const attrs = useAttrs()
   const ctx = inject(DrawerInjectionKey)
-  const isOpen = computed(() => ctx?.isOpen.value ?? false)
-  const { motionState } = useDrawerMotionState(isOpen)
+  const motionCtx = inject(DrawerMotionInjectionKey)
+  const motionState = computed(() => motionCtx?.motionState.value ?? 'closed')
 
   const handleClick = () => {
     if (!ctx?.closeable) return
diff --git a/packages/webkit/src/components/overlay/drawer/drawer-portal.vue b/packages/webkit/src/components/overlay/drawer/drawer-portal.vue
index 02523f9c7..feb34e776 100644
--- a/packages/webkit/src/components/overlay/drawer/drawer-portal.vue
+++ b/packages/webkit/src/components/overlay/drawer/drawer-portal.vue
@@ -1,7 +1,8 @@
 <script setup lang="ts">
-  import { computed, inject, onBeforeUnmount, ref, watch } from 'vue'
+  import { computed, inject, onBeforeUnmount, provide, ref, watch } from 'vue'
 
-  import { DrawerInjectionKey } from './injection-key'
+  import { useDrawerMotionState } from './composables/use-drawer-motion-state'
+  import { DrawerInjectionKey, DrawerMotionInjectionKey } from './injection-key'
   import { DRAWER_EXIT_MS } from './presets/transitions'
 
   defineOptions({
@@ -15,6 +16,10 @@
 
   const ctx = inject(DrawerInjectionKey)
   const isOpen = computed(() => ctx?.isOpen.value ?? false)
+  const { motionState } = useDrawerMotionState(isOpen)
+
+  provide(DrawerMotionInjectionKey, { motionState })
+
   const isPresent = ref(isOpen.value)
   let exitTimer: ReturnType<typeof setTimeout> | undefined
 

From 837b071f6e58eb32f71b3d4a1364b1621546d954 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:34:04 -0300
Subject: [PATCH 2/6] fix(drawer): apply size presets on shell and fluid panel
 width

Drive drawer max-width via inline shell styles and reactive size prop.
Use data-fluid on Panel to avoid medium cap conflicts, and md:w-full on the
shell so medium and large presets render at distinct widths.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .specs/drawer.md                              |  6 ++--
 .specs/panel.md                               |  4 +--
 .../overlay/drawer/drawer-content.vue         | 32 +++++++++++++------
 .../src/components/overlay/drawer/drawer.vue  |  4 +--
 .../overlay/drawer/injection-key.ts           | 14 +++++++-
 .../overlay/drawer/presets/sizes.js           | 27 ++++++++++++----
 .../src/components/overlay/panel/panel.vue    |  8 ++++-
 .../overlay/presets/mobile-position.js        |  3 +-
 8 files changed, 72 insertions(+), 26 deletions(-)

diff --git a/.specs/drawer.md b/.specs/drawer.md
index 7392bd45b..f7cd084a5 100644
--- a/.specs/drawer.md
+++ b/.specs/drawer.md
@@ -4,9 +4,9 @@ category: overlay
 structure: composition
 status: implemented
 spec_version: 1
-checksum: f236ede5538b80ceac858f16528e77b92cd84a979dee3ab640435575e0f426ba
+checksum: 380c8b7121907e3ac77be9b9ed690401b7bd0b22654667bee8ac6085948b5381
 created: 2026-05-22
-last_updated: 2026-05-22
+last_updated: 2026-05-29
 ---
 # Drawer — Component Spec
 
@@ -84,6 +84,8 @@ _none_
 ## Stories (Storybook)
 
 - Default
+- Sizes
+- ScrollContent — long `PanelContent` scrolls inside `ScrollArea`; header and footer stay in the panel flex layout (not sticky).
 
 ## Constraints — DO NOT
 
diff --git a/.specs/panel.md b/.specs/panel.md
index f812540e5..fd9ea814d 100644
--- a/.specs/panel.md
+++ b/.specs/panel.md
@@ -4,9 +4,9 @@ category: overlay
 structure: composition
 status: implemented
 spec_version: 1
-checksum: 45b27b09631c3ef06a0ac19b2a264aedbf06dc86dda5be9181d9eff32014280b
+checksum: 015f8188bde283cbb6e84bdd8639c3b1bea1ea95339d06bc1c518b42c7325f5f
 created: 2026-05-22
-last_updated: 2026-05-22
+last_updated: 2026-05-29
 ---
 # Panel — Component Spec
 
diff --git a/packages/webkit/src/components/overlay/drawer/drawer-content.vue b/packages/webkit/src/components/overlay/drawer/drawer-content.vue
index 65ab8fb32..3a135e5c5 100644
--- a/packages/webkit/src/components/overlay/drawer/drawer-content.vue
+++ b/packages/webkit/src/components/overlay/drawer/drawer-content.vue
@@ -1,17 +1,21 @@
 <script setup lang="ts">
   import { useEventListener, useScrollLock } from '@vueuse/core'
-  import { computed, inject, nextTick, ref, useAttrs, watch } from 'vue'
+  import { computed, inject, nextTick, provide, ref, unref, useAttrs, watch } from 'vue'
 
   import { useFocusTrap } from '../../../composables/use-focus-trap'
   import { cn } from '../../../utils/cn'
+  import { useOverlayMobile } from '../composables/use-overlay-mobile'
   import Panel from '../panel/panel.vue'
   import {
     drawerPanelPositionClasses,
     drawerShellPositionClasses
   } from '../presets/mobile-position'
-  import { useDrawerMotionState } from './composables/use-drawer-motion-state'
-  import { DrawerInjectionKey } from './injection-key'
-  import { drawerSizeClasses } from './presets/sizes'
+  import {
+    DrawerInjectionKey,
+    DrawerMotionInjectionKey,
+    DrawerPanelScrollInjectionKey
+  } from './injection-key'
+  import { getDrawerShellSizeStyle } from './presets/sizes'
   import {
     drawerPanelStateClasses,
     drawerPanelTransitionClasses,
@@ -31,7 +35,10 @@
   const ctx = inject(DrawerInjectionKey)
   const contentRef = ref<HTMLElement | null>(null)
   const isOpen = computed(() => ctx?.isOpen.value ?? false)
-  const { motionState } = useDrawerMotionState(isOpen)
+  const motionCtx = inject(DrawerMotionInjectionKey)
+  const motionState = computed(() => motionCtx?.motionState.value ?? 'closed')
+  const isMobileOverlay = useOverlayMobile()
+  const isDesktopDrawer = computed(() => !isMobileOverlay.value)
 
   const isScrollLocked = useScrollLock(document.body)
 
@@ -59,7 +66,9 @@
 
   const isLeft = computed(() => ctx?.side === 'left')
   const sideKey = computed(() => (isLeft.value ? 'left' : 'right'))
-  const drawerSize = computed(() => ctx?.size ?? 'medium')
+  const drawerSize = computed(() => unref(ctx?.size) ?? 'medium')
+
+  provide(DrawerPanelScrollInjectionKey, true)
 
   const shellClasses = computed(() =>
     cn(
@@ -73,12 +82,14 @@
     )
   )
 
-  const shellTransitionStyle = computed(() => getDrawerTransitionStyle(motionState.value, 'panel'))
+  const shellStyle = computed(() => ({
+    ...getDrawerTransitionStyle(motionState.value, 'panel'),
+    ...getDrawerShellSizeStyle(drawerSize.value, isDesktopDrawer.value)
+  }))
 
   const panelClasses = computed(() =>
     cn(
-      'pointer-events-auto flex w-full flex-col',
-      drawerSizeClasses[drawerSize.value],
+      'pointer-events-auto flex min-h-0 h-full flex-col',
       drawerPanelPositionClasses,
       isLeft.value
         ? 'md:rounded-r-[var(--shape-card)] md:rounded-l-[var(--shape-flat)]'
@@ -91,7 +102,7 @@
   <div
     ref="contentRef"
     :class="shellClasses"
-    :style="shellTransitionStyle"
+    :style="shellStyle"
     role="dialog"
     :aria-modal="true"
     :aria-labelledby="ctx?.titleId"
@@ -101,6 +112,7 @@
     tabindex="-1"
   >
     <Panel
+      data-fluid
       :class="panelClasses"
       :data-testid="`${ctx?.testId}__panel-shell`"
     >
diff --git a/packages/webkit/src/components/overlay/drawer/drawer.vue b/packages/webkit/src/components/overlay/drawer/drawer.vue
index 17089127d..987ce5f4f 100644
--- a/packages/webkit/src/components/overlay/drawer/drawer.vue
+++ b/packages/webkit/src/components/overlay/drawer/drawer.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { computed, provide, ref, useAttrs, useId } from 'vue'
+  import { computed, provide, ref, toRef, useAttrs, useId } from 'vue'
 
   import { useControllable } from '../../../composables/use-controllable'
   import { DrawerInjectionKey, type DrawerSide, type DrawerSize } from './injection-key'
@@ -71,7 +71,7 @@
     testId: testId.value,
     isOpen: computed(() => isOpen.value),
     closeable: props.closeable,
-    size: props.size,
+    size: toRef(props, 'size'),
     open: openDrawer,
     close: closeDrawer,
     titleId: `${uid}-title`,
diff --git a/packages/webkit/src/components/overlay/drawer/injection-key.ts b/packages/webkit/src/components/overlay/drawer/injection-key.ts
index 8a8c0bb80..2082fd002 100644
--- a/packages/webkit/src/components/overlay/drawer/injection-key.ts
+++ b/packages/webkit/src/components/overlay/drawer/injection-key.ts
@@ -1,13 +1,22 @@
 import type { InjectionKey, Ref } from 'vue'
 
+import type { DrawerMotionState } from './presets/transitions'
+
 export type DrawerSize = 'small' | 'medium' | 'large'
 export type DrawerSide = 'left' | 'right'
 
+export interface DrawerMotionContext {
+  motionState: Readonly<Ref<DrawerMotionState>>
+}
+
+export const DrawerMotionInjectionKey: InjectionKey<DrawerMotionContext> =
+  Symbol('DrawerMotionContext')
+
 export interface DrawerContext {
   testId: string
   isOpen: Readonly<Ref<boolean>>
   closeable: boolean
-  size: DrawerSize
+  size: Readonly<Ref<DrawerSize>>
   open: () => void
   close: () => void
   titleId: string
@@ -17,3 +26,6 @@ export interface DrawerContext {
 }
 
 export const DrawerInjectionKey: InjectionKey<DrawerContext> = Symbol('DrawerContext')
+
+/** Set by `drawer-content` so panel regions defer scrolling to its `ScrollArea`. */
+export const DrawerPanelScrollInjectionKey: InjectionKey<boolean> = Symbol('DrawerPanelScroll')
diff --git a/packages/webkit/src/components/overlay/drawer/presets/sizes.js b/packages/webkit/src/components/overlay/drawer/presets/sizes.js
index a5f8e2053..ee8b2b282 100644
--- a/packages/webkit/src/components/overlay/drawer/presets/sizes.js
+++ b/packages/webkit/src/components/overlay/drawer/presets/sizes.js
@@ -1,14 +1,29 @@
 /**
  * Drawer width presets — edge panels are always full viewport height;
- * `size` only controls max-width (`var(--container-*)` from theme).
+ * `size` prop controls max-width from `md` up.
  */
-export const drawerSizeClasses = {
-  small: 'max-w-[var(--container-sm)]',
-  medium: 'max-w-[var(--container-2xl)]',
-  large: 'max-w-[var(--container-6xl)]'
+export const drawerSizePixels = {
+  small: '384px',
+  medium: '672px',
+  large: '1024px'
 }
+
 export const drawerSizeSummaries = {
   small: '384px (container-sm)',
   medium: '672px (container-2xl)',
-  large: '1024px (container-6xl)'
+  large: '1024px (container-5xl)'
+}
+
+/**
+ * Desktop shell width — inline style (reliable across Tailwind JIT + Storybook `important`).
+ * @param {'small' | 'medium' | 'large'} size
+ * @param {boolean} isDesktop
+ */
+export const getDrawerShellSizeStyle = (size, isDesktop) => {
+  if (!isDesktop) return {}
+
+  return {
+    width: '100%',
+    maxWidth: drawerSizePixels[size] ?? drawerSizePixels.medium
+  }
 }
diff --git a/packages/webkit/src/components/overlay/panel/panel.vue b/packages/webkit/src/components/overlay/panel/panel.vue
index e0535dbdc..98c54b4f0 100644
--- a/packages/webkit/src/components/overlay/panel/panel.vue
+++ b/packages/webkit/src/components/overlay/panel/panel.vue
@@ -29,6 +29,8 @@
 
   const attrs = useAttrs()
 
+  const isFluid = computed(() => attrs['data-fluid'] !== undefined && attrs['data-fluid'] !== false)
+
   const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'overlay-panel')
 
   provide(PanelInjectionKey, {
@@ -41,7 +43,11 @@
       'rounded-[var(--shape-card)] border border-[length:var(--border-width-default)]',
       'border-[var(--border-muted)]',
       'bg-[var(--bg-surface)] shadow-[var(--shadow-2xl)]',
-      props.sizeAtMd ? dialogPanelSizeClasses[props.size] : panelSizeClasses[props.size],
+      isFluid.value
+        ? 'w-full max-w-none'
+        : props.sizeAtMd
+          ? dialogPanelSizeClasses[props.size]
+          : panelSizeClasses[props.size],
       attrs.class as string | undefined
     )
   )
diff --git a/packages/webkit/src/components/overlay/presets/mobile-position.js b/packages/webkit/src/components/overlay/presets/mobile-position.js
index dcf895500..3b080857c 100644
--- a/packages/webkit/src/components/overlay/presets/mobile-position.js
+++ b/packages/webkit/src/components/overlay/presets/mobile-position.js
@@ -17,12 +17,11 @@ export const drawerShellPositionClasses = [
   'max-md:inset-x-0 max-md:bottom-0 max-md:top-auto',
   'max-md:justify-center',
   ...overlayMobileFluidClasses,
-  'md:inset-y-0 md:h-full md:min-h-full md:w-auto'
+  'md:inset-y-0 md:h-full md:min-h-full md:w-full'
 ]
 export const drawerPanelPositionClasses = [
   ...overlayMobileFluidClasses,
   'max-md:max-w-none',
-  'max-md:overflow-y-auto',
   'max-md:rounded-b-[var(--shape-flat)] max-md:rounded-t-[var(--shape-card)]',
   'md:h-full md:min-h-0 md:max-h-full'
 ]

From 56069c0114376b3587f113db8a42631bd58d96fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:34:07 -0300
Subject: [PATCH 3/6] feat(drawer): scroll PanelContent with ScrollArea in
 drawer context

Render ScrollArea inside PanelContent when drawer-content provides scroll
host context so only the body scrolls while header and footer stay in the
panel flex layout.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../overlay/panel/panel-content.vue           | 35 +++++++++++++++++--
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/packages/webkit/src/components/overlay/panel/panel-content.vue b/packages/webkit/src/components/overlay/panel/panel-content.vue
index 66b04fae1..241ba4f8a 100644
--- a/packages/webkit/src/components/overlay/panel/panel-content.vue
+++ b/packages/webkit/src/components/overlay/panel/panel-content.vue
@@ -2,6 +2,8 @@
   import { computed, inject, useAttrs } from 'vue'
 
   import { cn } from '../../../utils/cn'
+  import ScrollArea from '../../layout/scroll-area/scroll-area.vue'
+  import { DrawerInjectionKey, DrawerPanelScrollInjectionKey } from '../drawer/injection-key'
   import { PanelInjectionKey } from './injection-key'
 
   defineOptions({
@@ -15,15 +17,42 @@
 
   const attrs = useAttrs()
   const ctx = inject(PanelInjectionKey)
+  const drawerCtx = inject(DrawerInjectionKey, null)
+  const drawerScrollHost = inject(DrawerPanelScrollInjectionKey, false)
 
-  const rootClasses = computed(() =>
-    cn('min-h-0 flex-1 overflow-y-auto p-[var(--spacing-xl)]', attrs.class as string | undefined)
+  const scrollAreaClasses = computed(() =>
+    cn('min-h-0 min-w-0 flex-1', drawerScrollHost ? (attrs.class as string | undefined) : undefined)
+  )
+
+  const contentClasses = computed(() =>
+    cn(
+      'p-[var(--spacing-xl)]',
+      !drawerScrollHost ? 'min-h-0 flex-1 overflow-y-auto' : undefined,
+      !drawerScrollHost ? (attrs.class as string | undefined) : undefined
+    )
+  )
+
+  const scrollTestId = computed(
+    () => `${drawerCtx?.testId ?? ctx?.testId ?? 'overlay-panel'}__scroll`
   )
 </script>
 
 <template>
+  <ScrollArea
+    v-if="drawerScrollHost"
+    :class="scrollAreaClasses"
+    :data-testid="scrollTestId"
+  >
+    <div
+      :class="contentClasses"
+      :data-testid="`${ctx?.testId}__content`"
+    >
+      <slot />
+    </div>
+  </ScrollArea>
   <div
-    :class="rootClasses"
+    v-else
+    :class="contentClasses"
     :data-testid="`${ctx?.testId}__content`"
   >
     <slot />

From 114b5a8368c8f3f9e14813455bea6b509c8eab36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:34:09 -0300
Subject: [PATCH 4/6] fix(panel): align header and footer horizontal padding to
 spacing-lg

Match panel header and footer inset tokens for consistent shell spacing.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 packages/webkit/src/components/overlay/panel/panel-footer.vue | 2 +-
 packages/webkit/src/components/overlay/panel/panel-header.vue | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/webkit/src/components/overlay/panel/panel-footer.vue b/packages/webkit/src/components/overlay/panel/panel-footer.vue
index ef63a798a..9783532f8 100644
--- a/packages/webkit/src/components/overlay/panel/panel-footer.vue
+++ b/packages/webkit/src/components/overlay/panel/panel-footer.vue
@@ -20,7 +20,7 @@
     cn(
       'flex min-h-16 shrink-0 items-center gap-[var(--spacing-sm)]',
       'border-t border-[length:var(--border-width-default)] border-[var(--border-muted)] bg-[var(--bg-surface)]',
-      'px-[var(--spacing-xl)] py-[var(--spacing-md)]',
+      'px-[var(--spacing-lg)] py-[var(--spacing-md)]',
       attrs.class as string | undefined
     )
   )
diff --git a/packages/webkit/src/components/overlay/panel/panel-header.vue b/packages/webkit/src/components/overlay/panel/panel-header.vue
index 6da2807cd..ed945f905 100644
--- a/packages/webkit/src/components/overlay/panel/panel-header.vue
+++ b/packages/webkit/src/components/overlay/panel/panel-header.vue
@@ -20,7 +20,7 @@
     cn(
       'flex min-h-14 shrink-0 items-center justify-between gap-[var(--spacing-xs)]',
       'border-b border-[length:var(--border-width-default)] border-[var(--border-muted)] bg-[var(--bg-surface)]',
-      'pl-[var(--spacing-xl)] pr-[var(--spacing-md)] py-[var(--spacing-md)]',
+      'pl-[var(--spacing-lg)] pr-[var(--spacing-md)] py-[var(--spacing-md)]',
       attrs.class as string | undefined
     )
   )

From bd464a0c17a7365ab1b1ffc25cb7afb9bce559c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:34:13 -0300
Subject: [PATCH 5/6] docs(storybook): document drawer and dialog panel shell
 usage

Add Usage blocks, Sizes and ScrollContent drawer stories, and align Dialog
Default with the shared PanelHeader, PanelContent, and PanelFooter anatomy.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../stories/webkit/overlay/Dialog.stories.js  | 133 ++++++----
 .../stories/webkit/overlay/Drawer.stories.js  | 233 ++++++++++++++++--
 2 files changed, 301 insertions(+), 65 deletions(-)

diff --git a/apps/storybook/src/stories/webkit/overlay/Dialog.stories.js b/apps/storybook/src/stories/webkit/overlay/Dialog.stories.js
index 78ec17faf..c9277a819 100644
--- a/apps/storybook/src/stories/webkit/overlay/Dialog.stories.js
+++ b/apps/storybook/src/stories/webkit/overlay/Dialog.stories.js
@@ -1,5 +1,3 @@
-import { ref } from 'vue'
-
 import Button from '@aziontech/webkit/button'
 import Dialog from '@aziontech/webkit/overlay/dialog'
 import DialogClose from '@aziontech/webkit/overlay/dialog-close'
@@ -12,10 +10,27 @@ import DialogTrigger from '@aziontech/webkit/overlay/dialog-trigger'
 import PanelContent from '@aziontech/webkit/overlay/panel-content'
 import PanelFooter from '@aziontech/webkit/overlay/panel-footer'
 import PanelHeader from '@aziontech/webkit/overlay/panel-header'
+import { ref } from 'vue'
 
 const sizes = ['small', 'medium', 'large']
 
-export default {
+const dialogStoryComponents = {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogOverlay,
+  DialogContent,
+  DialogTitle,
+  DialogDescription,
+  DialogClose,
+  PanelHeader,
+  PanelContent,
+  PanelFooter,
+  Button
+}
+
+/** @type {import('@storybook/vue3').Meta<typeof Dialog>} */
+const meta = {
   title: 'Webkit/Overlay/Dialog',
   component: Dialog,
   subcomponents: {
@@ -34,7 +49,6 @@ export default {
   parameters: {
     layout: 'fullscreen',
     backgrounds: { default: 'dark' },
-    actions: { argTypesRegex: '^on[A-Z].*' },
     a11y: {
       config: {
         rules: [{ id: 'color-contrast', enabled: true }]
@@ -42,8 +56,55 @@ export default {
     },
     docs: {
       description: {
-        component:
-          'Modal dialog built on the shared Panel shell. Figma Webkit Panel (node 482:935). Supports overlay backdrop, closeable behavior, and theme motion tokens (panel scale 0.98 → 1 + opacity fade, overlay fade).'
+        component: [
+          'Modal dialog built on the shared Panel shell. Supports overlay backdrop, closeable behavior, and theme motion tokens (panel scale + opacity fade, overlay fade).',
+          '',
+          '## Usage',
+          '',
+          '```vue',
+          '<script setup>',
+          "import { ref } from 'vue'",
+          "import Button from '@aziontech/webkit/button'",
+          "import Dialog from '@aziontech/webkit/overlay/dialog'",
+          "import DialogClose from '@aziontech/webkit/overlay/dialog-close'",
+          "import DialogContent from '@aziontech/webkit/overlay/dialog-content'",
+          "import DialogDescription from '@aziontech/webkit/overlay/dialog-description'",
+          "import DialogOverlay from '@aziontech/webkit/overlay/dialog-overlay'",
+          "import DialogPortal from '@aziontech/webkit/overlay/dialog-portal'",
+          "import DialogTitle from '@aziontech/webkit/overlay/dialog-title'",
+          "import DialogTrigger from '@aziontech/webkit/overlay/dialog-trigger'",
+          "import PanelContent from '@aziontech/webkit/overlay/panel-content'",
+          "import PanelFooter from '@aziontech/webkit/overlay/panel-footer'",
+          "import PanelHeader from '@aziontech/webkit/overlay/panel-header'",
+          '',
+          'const open = ref(false)',
+          '</script>',
+          '',
+          '<template>',
+          '  <Dialog v-model:open="open" closeable size="medium">',
+          '    <DialogTrigger>',
+          '      <Button label="Open dialog" kind="primary" />',
+          '    </DialogTrigger>',
+          '    <DialogPortal>',
+          '      <DialogOverlay />',
+          '      <DialogContent>',
+          '        <PanelHeader class="w-full">',
+          '          <DialogTitle>Dialog Title</DialogTitle>',
+          '          <DialogClose />',
+          '        </PanelHeader>',
+          '        <PanelContent>',
+          '          <DialogDescription>Modal content.</DialogDescription>',
+          '        </PanelContent>',
+          '        <PanelFooter class="flex-col md:flex-row md:justify-end">',
+          '          <Button class="w-full md:w-auto" label="Cancel" kind="outlined" @click="open = false" />',
+          '          <Button class="w-full md:w-auto" label="Save" kind="primary" />',
+          '        </PanelFooter>',
+          '      </DialogContent>',
+          '    </DialogPortal>',
+          '  </Dialog>',
+          '</template>',
+          '```'
+        ].join('\n')
       }
     }
   },
@@ -83,63 +144,43 @@ export default {
   }
 }
 
-const alertDialogTemplate = `
+export default meta
+
+const dialogTemplate = `
   <Dialog v-bind="args" v-model:open="open">
     <DialogTrigger>
-      <Button label="Open alert" kind="primary" />
+      <Button label="Open dialog" kind="primary" />
     </DialogTrigger>
     <DialogPortal>
       <DialogOverlay />
       <DialogContent>
-        <PanelContent class="p-0">
-          <div class="flex w-full flex-col">
-            <div
-              class="flex items-start gap-[var(--spacing-4)] px-[var(--spacing-6)] py-[var(--spacing-6)]"
-            >
-              <div class="flex min-w-0 flex-1 flex-col gap-[var(--spacing-2)]">
-                <DialogTitle>Cancel Scheduled Downgrade</DialogTitle>
-                <DialogDescription>
-                  Confirm to remove the scheduled downgrade. Your current plan will continue without changes.
-                </DialogDescription>
-              </div>
-              <DialogClose class="shrink-0" />
-            </div>
-            <div
-              class="flex flex-col gap-[var(--spacing-3)] border-t border-[length:var(--border-width-default)] border-[var(--border-muted)] px-[var(--spacing-6)] py-[var(--spacing-4)] md:flex-row md:justify-end"
-            >
-              <Button class="w-full md:w-auto" label="Cancel" size="medium" kind="outlined" @click="open = false" />
-              <Button class="w-full md:w-auto" kind="secondary" size="medium" label="Keep current plan" @click="open = false" />
-            </div>
-          </div>
+        <PanelHeader class="w-full">
+          <DialogTitle>Dialog Title</DialogTitle>
+          <DialogClose />
+        </PanelHeader>
+        <PanelContent>
+          <DialogDescription>
+            Modal content. Uses the shared Panel header, body, and footer regions.
+          </DialogDescription>
         </PanelContent>
+        <PanelFooter class="flex-col md:flex-row md:justify-end">
+          <Button class="w-full md:w-auto" label="Cancel" kind="outlined" @click="open = false" />
+          <Button class="w-full md:w-auto" label="Save" kind="primary" />
+        </PanelFooter>
       </DialogContent>
     </DialogPortal>
   </Dialog>
 `
 
+/** @type {import('@storybook/vue3').StoryObj<typeof Dialog>} */
 export const Default = {
-  args: {
-    defaultOpen: false,
-    closeable: true,
-    size: 'small'
-  },
   render: (args) => ({
-    components: {
-      Dialog,
-      DialogTrigger,
-      DialogPortal,
-      DialogOverlay,
-      DialogContent,
-      DialogTitle,
-      DialogDescription,
-      DialogClose,
-      PanelContent,
-      Button
-    },
+    components: dialogStoryComponents,
     setup() {
       const open = ref(args.defaultOpen)
+
       return { args, open }
     },
-    template: alertDialogTemplate
+    template: dialogTemplate
   })
 }
diff --git a/apps/storybook/src/stories/webkit/overlay/Drawer.stories.js b/apps/storybook/src/stories/webkit/overlay/Drawer.stories.js
index abcb60c63..7bd94f838 100644
--- a/apps/storybook/src/stories/webkit/overlay/Drawer.stories.js
+++ b/apps/storybook/src/stories/webkit/overlay/Drawer.stories.js
@@ -1,5 +1,3 @@
-import { ref } from 'vue'
-
 import Button from '@aziontech/webkit/button'
 import Drawer from '@aziontech/webkit/overlay/drawer'
 import DrawerClose from '@aziontech/webkit/overlay/drawer-close'
@@ -12,10 +10,37 @@ import DrawerTrigger from '@aziontech/webkit/overlay/drawer-trigger'
 import PanelContent from '@aziontech/webkit/overlay/panel-content'
 import PanelFooter from '@aziontech/webkit/overlay/panel-footer'
 import PanelHeader from '@aziontech/webkit/overlay/panel-header'
+import { reactive, ref, watch } from 'vue'
 
 const sizes = ['small', 'medium', 'large']
 const sides = ['left', 'right']
 
+const sizeLabels = {
+  small: 'Small (384px)',
+  medium: 'Medium (672px)',
+  large: 'Large (1024px)'
+}
+
+const scrollSections = Array.from({ length: 12 }, (_, index) => ({
+  title: `Section ${index + 1}`,
+  body: `Scrollable drawer body copy for section ${index + 1}. Only PanelContent scrolls; header and footer stay in the panel layout.`
+}))
+
+const drawerStoryComponents = {
+  Drawer,
+  DrawerTrigger,
+  DrawerPortal,
+  DrawerOverlay,
+  DrawerContent,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerClose,
+  PanelHeader,
+  PanelContent,
+  PanelFooter,
+  Button
+}
+
 export default {
   title: 'Webkit/Overlay/Drawer',
   component: Drawer,
@@ -35,7 +60,6 @@ export default {
   parameters: {
     layout: 'fullscreen',
     backgrounds: { default: 'dark' },
-    actions: { argTypesRegex: '^on[A-Z].*' },
     a11y: {
       config: {
         rules: [{ id: 'color-contrast', enabled: true }]
@@ -43,8 +67,55 @@ export default {
     },
     docs: {
       description: {
-        component:
-          'Edge drawer using the shared Panel shell. Panel and backdrop use CSS transitions from theme animate presets (`moderate-*` durations, `productive-*` curves).'
+        component: [
+          'Edge drawer using the shared Panel shell. Long body content scrolls inside `PanelContent` via `ScrollArea`; header and footer stay in the panel flex layout.',
+          '',
+          '## Usage',
+          '',
+          '```vue',
+          '<script setup>',
+          "import { ref } from 'vue'",
+          "import Button from '@aziontech/webkit/button'",
+          "import Drawer from '@aziontech/webkit/overlay/drawer'",
+          "import DrawerClose from '@aziontech/webkit/overlay/drawer-close'",
+          "import DrawerContent from '@aziontech/webkit/overlay/drawer-content'",
+          "import DrawerDescription from '@aziontech/webkit/overlay/drawer-description'",
+          "import DrawerOverlay from '@aziontech/webkit/overlay/drawer-overlay'",
+          "import DrawerPortal from '@aziontech/webkit/overlay/drawer-portal'",
+          "import DrawerTitle from '@aziontech/webkit/overlay/drawer-title'",
+          "import DrawerTrigger from '@aziontech/webkit/overlay/drawer-trigger'",
+          "import PanelContent from '@aziontech/webkit/overlay/panel-content'",
+          "import PanelFooter from '@aziontech/webkit/overlay/panel-footer'",
+          "import PanelHeader from '@aziontech/webkit/overlay/panel-header'",
+          '',
+          'const open = ref(false)',
+          '</script>',
+          '',
+          '<template>',
+          '  <Drawer v-model:open="open" closeable side="right" size="medium">',
+          '    <DrawerTrigger>',
+          '      <Button label="Open drawer" kind="primary" />',
+          '    </DrawerTrigger>',
+          '    <DrawerPortal>',
+          '      <DrawerOverlay />',
+          '      <DrawerContent>',
+          '        <PanelHeader class="w-full">',
+          '          <DrawerTitle>Drawer Title</DrawerTitle>',
+          '          <DrawerClose />',
+          '        </PanelHeader>',
+          '        <PanelContent>',
+          '          <DrawerDescription>Side panel content.</DrawerDescription>',
+          '        </PanelContent>',
+          '        <PanelFooter class="flex-col md:flex-row md:justify-end">',
+          '          <Button class="w-full md:w-auto" label="Cancel" kind="outlined" @click="open = false" />',
+          '          <Button class="w-full md:w-auto" label="Save" kind="primary" />',
+          '        </PanelFooter>',
+          '      </DrawerContent>',
+          '    </DrawerPortal>',
+          '  </Drawer>',
+          '</template>',
+          '```'
+        ].join('\n')
       }
     }
   },
@@ -120,20 +191,7 @@ const drawerTemplate = `
 
 export const Default = {
   render: (args) => ({
-    components: {
-      Drawer,
-      DrawerTrigger,
-      DrawerPortal,
-      DrawerOverlay,
-      DrawerContent,
-      DrawerTitle,
-      DrawerDescription,
-      DrawerClose,
-      PanelHeader,
-      PanelContent,
-      PanelFooter,
-      Button
-    },
+    components: drawerStoryComponents,
     setup() {
       const open = ref(args.defaultOpen)
       return { args, open }
@@ -141,3 +199,140 @@ export const Default = {
     template: drawerTemplate
   })
 }
+
+export const Sizes = {
+  parameters: {
+    viewport: {
+      defaultViewport: 'desktop'
+    },
+    docs: {
+      description: {
+        story: 'Small (384px), medium (672px), and large (1024px) max-width presets side by side.'
+      }
+    }
+  },
+  render: () => ({
+    components: drawerStoryComponents,
+    setup() {
+      const openBySize = reactive({
+        small: false,
+        medium: false,
+        large: false
+      })
+
+      watch(
+        openBySize,
+        () => {
+          const openKey = sizes.find((key) => openBySize[key])
+
+          if (!openKey) return
+
+          sizes.forEach((key) => {
+            if (key !== openKey) {
+              openBySize[key] = false
+            }
+          })
+        },
+        { deep: true }
+      )
+
+      return { sizes, sizeLabels, openBySize }
+    },
+    template: `
+      <div class="flex flex-wrap items-center justify-center gap-[var(--spacing-4)]">
+        <Drawer
+          v-for="size in sizes"
+          :key="size"
+          :size="size"
+          v-model:open="openBySize[size]"
+          closeable
+          side="right"
+          :data-testid="'overlay-drawer-' + size"
+        >
+          <DrawerTrigger>
+            <Button :label="sizeLabels[size]" kind="primary" />
+          </DrawerTrigger>
+          <DrawerPortal>
+            <DrawerOverlay />
+            <DrawerContent>
+              <PanelHeader class="w-full">
+                <DrawerTitle>{{ sizeLabels[size] }}</DrawerTitle>
+                <DrawerClose />
+              </PanelHeader>
+              <PanelContent>
+                <DrawerDescription>
+                  Panel max-width preset for the {{ size }} drawer. Height is always 100% viewport.
+                </DrawerDescription>
+              </PanelContent>
+              <PanelFooter class="flex-col md:flex-row md:justify-end">
+                <Button
+                  class="w-full md:w-auto"
+                  label="Cancel"
+                  kind="outlined"
+                  @click="openBySize[size] = false"
+                />
+                <Button class="w-full md:w-auto" label="Save" kind="primary" />
+              </PanelFooter>
+            </DrawerContent>
+          </DrawerPortal>
+        </Drawer>
+      </div>
+    `
+  })
+}
+
+export const ScrollContent = {
+  parameters: {
+    viewport: {
+      defaultViewport: 'desktop'
+    },
+    docs: {
+      description: {
+        story:
+          'Long content in `PanelContent` scrolls inside `ScrollArea`. Header and footer stay in the panel flex layout at the top and bottom; only the body scrolls.'
+      }
+    }
+  },
+  render: () => ({
+    components: drawerStoryComponents,
+    setup() {
+      const open = ref(false)
+
+      return { open, scrollSections }
+    },
+    template: `
+      <Drawer v-model:open="open" closeable side="right" size="medium">
+        <DrawerTrigger>
+          <Button label="Open scrollable drawer" kind="primary" />
+        </DrawerTrigger>
+        <DrawerPortal>
+          <DrawerOverlay />
+          <DrawerContent>
+            <PanelHeader class="w-full">
+              <DrawerTitle>Scrollable drawer</DrawerTitle>
+              <DrawerClose />
+            </PanelHeader>
+            <PanelContent class="flex flex-col gap-[var(--spacing-4)]">
+              <DrawerDescription>
+                Place long forms, lists, or settings inside PanelContent. Only the body scrolls inside
+                ScrollArea while header and footer stay in the panel layout.
+              </DrawerDescription>
+              <section
+                v-for="section in scrollSections"
+                :key="section.title"
+                class="flex flex-col gap-[var(--spacing-2)] rounded-[var(--shape-elements)] border border-[length:var(--border-width-default)] border-[var(--border-muted)] p-[var(--spacing-4)]"
+              >
+                <h3 class="m-0 text-body-md text-[var(--text-default)]">{{ section.title }}</h3>
+                <p class="m-0 text-body-sm text-[var(--text-muted)]">{{ section.body }}</p>
+              </section>
+            </PanelContent>
+            <PanelFooter class="flex-col md:flex-row md:justify-end">
+              <Button class="w-full md:w-auto" label="Cancel" kind="outlined" @click="open = false" />
+              <Button class="w-full md:w-auto" label="Save" kind="primary" />
+            </PanelFooter>
+          </DrawerContent>
+        </DrawerPortal>
+      </Drawer>
+    `
+  })
+}

From 5f94777397d2b4d233d5b850217d54ad80c93b85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Fri, 29 May 2026 18:34:13 -0300
Subject: [PATCH 6/6] docs(storybook): simplify ChangePlanDrawer to a single
 Default story

Use button-triggered drawer with the standard panel regions and drop extra
playground and accessibility variants from the template story.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../templates/ChangePlanDrawer.stories.js     | 60 ++++++-------------
 1 file changed, 17 insertions(+), 43 deletions(-)

diff --git a/apps/storybook/src/stories/webkit/templates/ChangePlanDrawer.stories.js b/apps/storybook/src/stories/webkit/templates/ChangePlanDrawer.stories.js
index 6aea19737..2ba8b23eb 100644
--- a/apps/storybook/src/stories/webkit/templates/ChangePlanDrawer.stories.js
+++ b/apps/storybook/src/stories/webkit/templates/ChangePlanDrawer.stories.js
@@ -10,7 +10,6 @@ import DrawerTrigger from '@aziontech/webkit/overlay/drawer-trigger'
 import PanelContent from '@aziontech/webkit/overlay/panel-content'
 import PanelHeader from '@aziontech/webkit/overlay/panel-header'
 import SegmentedButton from '@aziontech/webkit/segmented-button'
-import { expect, userEvent, within } from '@storybook/test'
 import { ref } from 'vue'
 
 const billingDetailMonthly = 'Billed annually or $25/mo billed monthly.'
@@ -141,7 +140,7 @@ const changePlanTemplate = `
   </Drawer>
 `
 
-const renderChangePlanDrawer = (args) => ({
+const Template = (args) => ({
   components: {
     Drawer,
     DrawerTrigger,
@@ -179,7 +178,6 @@ export default {
   parameters: {
     layout: 'fullscreen',
     backgrounds: { default: 'dark' },
-    actions: { argTypesRegex: '^on[A-Z].*' },
     a11y: {
       config: {
         rules: [{ id: 'color-contrast', enabled: true }]
@@ -188,35 +186,44 @@ export default {
     docs: {
       description: {
         component:
-          'Change Plan drawer template from console.azion.com Figma (node 314:31891). Composes Webkit Drawer with CardPricing plans and a billing period toggle.'
+          'Change Plan drawer template. Composes Webkit Drawer with CardPricing plans and a billing period toggle.'
       }
     }
   },
+  decorators: [
+    () => ({
+      template: '<div class="flex min-h-screen w-full items-center justify-center"><story /></div>'
+    })
+  ],
   argTypes: {
     defaultOpen: {
       control: 'boolean',
       description: 'Initial open state when uncontrolled',
-      table: { defaultValue: { summary: false } }
+      table: { defaultValue: { summary: false }, category: 'props' }
     },
     closeable: {
       control: 'boolean',
       description: 'When true, Escape and overlay click close the drawer',
-      table: { defaultValue: { summary: true } }
+      table: { defaultValue: { summary: true }, category: 'props' }
     },
     side: {
       control: 'select',
       options: ['left', 'right'],
       description: 'Edge the panel slides from',
-      table: { defaultValue: { summary: 'right' } }
+      table: { defaultValue: { summary: 'right' }, category: 'props' }
     },
     size: {
       control: 'select',
       options: ['small', 'medium', 'large'],
       description:
         'Panel max-width preset (`large` = 1024px). Drawer height is always 100% viewport.',
-      table: { defaultValue: { summary: 'large' } }
+      table: { defaultValue: { summary: 'large' }, category: 'props' }
     },
-    'update:open': { action: 'update:open' }
+    'onUpdate:open': {
+      action: 'update:open',
+      description: 'Emitted when open state changes',
+      table: { category: 'events' }
+    }
   },
   args: {
     defaultOpen: false,
@@ -227,38 +234,5 @@ export default {
 }
 
 export const Default = {
-  render: renderChangePlanDrawer
-}
-
-export const Open = {
-  args: { defaultOpen: true },
-  render: renderChangePlanDrawer
+  render: Template
 }
-
-export const Controlled = {
-  args: { defaultOpen: true },
-  render: renderChangePlanDrawer
-}
-
-export const LightDark = {
-  parameters: {
-    backgrounds: { default: 'light' }
-  },
-  args: { defaultOpen: true },
-  render: renderChangePlanDrawer
-}
-
-export const Accessibility = {
-  render: renderChangePlanDrawer,
-  play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement)
-    const trigger = canvas.getByRole('button', { name: /change plan/i })
-    await userEvent.click(trigger)
-    const dialog = await within(document.body).findByRole('dialog')
-    await expect(dialog).toBeInTheDocument()
-    await expect(within(dialog).getByRole('heading', { name: /change plan/i })).toBeInTheDocument()
-    await userEvent.keyboard('{Escape}')
-  }
-}
-
-export const Playground = Default