From bfcc0439fe86ebb05206a4579f2a653e41c2822b Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 1 Oct 2026 00:40:04 +0000
Subject: [PATCH] feat: keep every portaled component inside a shadow root

Selects, comboboxes, menus, hover cards, context menus and toasts now resolve
their teleport target through usePortalTarget like the dialogs already did,
and expose a `to` override. The shadow-root container mirrors the nearest
dark/light scheme class so dark tokens still apply to portaled content, and
`shimmer` no longer hard-codes html.dark.

Closes #30
---
 AGENTS.md                                     |   4 +
 packages/design/README.md                     |  30 +--
 .../components/Feedback/FeedbackToasts.vue    |  14 +-
 .../design/components/Form/FormCombobox.vue   |  26 +--
 .../design/components/Form/FormSelect.vue     |   9 +-
 .../components/Layout/LayoutMenubar.vue       |  11 +-
 .../components/Overlay/OverlayConfirm.vue     |  74 +++----
 .../components/Overlay/OverlayContextMenu.vue |   9 +-
 .../components/Overlay/OverlayDrawer.vue      |  75 ++++---
 .../components/Overlay/OverlayDropdown.vue    |   9 +-
 .../components/Overlay/OverlayDropdownSub.vue |   9 +-
 .../components/Overlay/OverlayHoverCard.vue   |   9 +-
 .../components/Overlay/OverlayModal.vue       |  90 ++++----
 packages/design/components/Overview.mdx       |   5 +
 .../components/Utility/ShadowRoot.stories.ts  | 145 +++++++++++++
 packages/design/composables/portalTarget.ts   |  47 ++--
 packages/design/test/overlay-portal.test.ts   |  66 ------
 packages/design/test/portal.test.ts           | 200 ++++++++++++++++++
 packages/design/test/scroll-fade.test.ts      |   2 +-
 packages/design/unocss/shimmer.ts             |   2 +-
 20 files changed, 582 insertions(+), 254 deletions(-)
 create mode 100644 packages/design/components/Utility/ShadowRoot.stories.ts
 delete mode 100644 packages/design/test/overlay-portal.test.ts
 create mode 100644 packages/design/test/portal.test.ts

diff --git a/AGENTS.md b/AGENTS.md
index d1fdc74..e9dc1db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,6 +13,10 @@ still apply).
   the Phosphor set already installed via `presetIcons`) on a `<span class="i-ph:..." aria-hidden="true" />`.
   Exception: purely data-driven/generative vector graphics (e.g. `DisplayDonut`'s
   progress ring) aren't icons and stay inline `<svg>`.
+- Anything that teleports (a reka `*Portal`, a `<Teleport>`) must route its target
+  through `usePortalTarget(() => props.to)` and expose the `to?: string | HTMLElement`
+  prop, so the content stays inside an enclosing shadow root. Add the component to
+  the `cases` list in `test/portal.test.ts` and to the `Utilities/ShadowRoot` story.
 
 ## Keep the Storybook Overview up to date
 
diff --git a/packages/design/README.md b/packages/design/README.md
index bc7791d..e3f36b1 100644
--- a/packages/design/README.md
+++ b/packages/design/README.md
@@ -132,7 +132,7 @@ contrast scan in light + dark after each step.
 ## Embedding in a shadow root
 
 Mounting the components inside a shadow root — a web component, a devtools dock,
-an injected overlay — is supported, but three things do not cross the boundary on
+an injected overlay — is supported, but two things do not cross the boundary on
 their own:
 
 - **The scheme class goes on an _ancestor_, never on the element you style.** The
@@ -142,25 +142,6 @@ their own:
   wrapper — `display: contents` works, so it costs no layout — and put the surface
   utilities on its child. `:host(.dark)` is not an alternative: these are
   descendant selectors, and they can't reach across the boundary.
-- **Portaled overlays need a target inside the root.** reka-ui teleports
-  `Select`/`Combobox`/dropdown/menu content to `document.body` by default, i.e.
-  *outside* the shadow root that holds your stylesheet — so the popup renders
-  unstyled and positions against a trigger in another tree. Wrap once in reka's
-  `ConfigProvider` with `teleport-to` pointing at a container inside the root, and
-  put that container *outside* your scroll container so the popper isn't clipped:
-
-  ```vue
-  <ConfigProvider :teleport-to="portalTarget">
-    <div ref="portalTarget" />
-    <div class="of-auto"><!-- scrolling content --></div>
-  </ConfigProvider>
-  ```
-
-  The dialog family (`OverlayModal`, `OverlayDrawer`, `OverlayConfirm`) needs no
-  such setup: it detects the enclosing shadow root and teleports into it on its
-  own, so it works out of the box under `defineCustomElement`. Pass an explicit
-  `to` (a selector or element) to override the target.
-
 - **Global CSS can't pierce the boundary — inline the styles.** `@antfu/design/styles/*`
   (scrollbar, reka-ui animations, vue-afloat, …) must be part of the sheet you
   inject into the root, alongside the UnoCSS output. They're written with `*` /
@@ -168,6 +149,15 @@ their own:
   `scrollbar-gutter: stable` on your own scroll container if you want the gutter
   reserved.
 
+Portaled content needs no setup. Every component that teleports — the dialogs
+(`OverlayModal`, `OverlayDrawer`, `OverlayConfirm`), the poppers (`FormSelect`,
+`FormCombobox`, `OverlayDropdown`, `OverlayHoverCard`, `OverlayContextMenu`,
+`LayoutMenubar`) and `FeedbackToasts` — detects the enclosing shadow root and
+teleports into a container appended to it, which also mirrors the `dark`/`light`
+class of the nearest scheme wrapper so dark-mode tokens keep resolving there. Pass
+an explicit `to` (a selector or element) to override the target. The
+**Utilities/ShadowRoot** story mounts them all inside a shadow root.
+
 ## Accessibility
 
 A color-contrast scan (axe-core + Playwright) runs a URL in light **and** dark
diff --git a/packages/design/components/Feedback/FeedbackToasts.vue b/packages/design/components/Feedback/FeedbackToasts.vue
index c767bf7..76dd051 100644
--- a/packages/design/components/Feedback/FeedbackToasts.vue
+++ b/packages/design/components/Feedback/FeedbackToasts.vue
@@ -1,5 +1,7 @@
 <!-- @description a presentational toast stack (`items`, `position`) — the app owns the list and ids via its own `useToast()`. -->
-<script lang="ts">
+<script setup lang="ts">
+import { usePortalTarget } from '../../composables/portalTarget'
+
 export type ToastType = 'info' | 'success' | 'warning' | 'error'
 
 /** A single toast. The **app** owns the list and the ids — this component is presentational. */
@@ -18,14 +20,14 @@ export interface ToastItem {
   /** Optional action button label; pressing it fires the `action` event. */
   action?: string
 }
-</script>
 
-<script setup lang="ts">
-withDefaults(
+const props = withDefaults(
   defineProps<{
     /** The toast list — owned and mutated by the app (e.g. a local `ref`). */
     items: ToastItem[]
     position?: 'top-right' | 'bottom-right' | 'top-left' | 'bottom-left'
+    /** Teleport target for the stack; defaults to the enclosing shadow root, else `document.body`. */
+    to?: string | HTMLElement
   }>(),
   { position: 'bottom-right' },
 )
@@ -37,6 +39,8 @@ const emit = defineEmits<{
   action: [id: string | number]
 }>()
 
+const portalTo = usePortalTarget(() => props.to)
+
 const POSITION = {
   'top-right': 'top-4 right-4',
   'bottom-right': 'bottom-4 right-4',
@@ -53,7 +57,7 @@ const TYPE_CLASS: Record<ToastType, string> = {
 </script>
 
 <template>
-  <Teleport to="body">
+  <Teleport :to="portalTo ?? 'body'">
     <div
       class="flex flex-col gap-2 max-w-[calc(100vw-2rem)] w-80 fixed z-toast"
       :class="POSITION[position]"
diff --git a/packages/design/components/Form/FormCombobox.vue b/packages/design/components/Form/FormCombobox.vue
index bc18bec..553f911 100644
--- a/packages/design/components/Form/FormCombobox.vue
+++ b/packages/design/components/Form/FormCombobox.vue
@@ -1,6 +1,7 @@
 <!-- @description a searchable, filterable select (reka-ui `Combobox`) over an `options` list. -->
 <script setup lang="ts">
 import { ComboboxAnchor, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxPortal, ComboboxRoot, ComboboxViewport } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
 export interface ComboboxOption {
   value: string
@@ -13,21 +14,22 @@ export interface ComboboxOption {
 // visible. Route them to the anchor, which *is* the field.
 defineOptions({ inheritAttrs: false })
 
-withDefaults(
-  defineProps<{
-    /** Selectable options. `label` falls back to `value`; `disabled` blocks selection. */
-    options: ComboboxOption[]
-    /** Placeholder shown in the search input while empty. */
-    placeholder?: string
-    /** Disable the whole combobox. */
-    disabled?: boolean
-  }>(),
-  {},
-)
+const props = defineProps<{
+  /** Selectable options. `label` falls back to `value`; `disabled` blocks selection. */
+  options: ComboboxOption[]
+  /** Placeholder shown in the search input while empty. */
+  placeholder?: string
+  /** Disable the whole combobox. */
+  disabled?: boolean
+  /** Teleport target for the list; defaults to the enclosing shadow root, else `document.body`. */
+  to?: string | HTMLElement
+}>()
 
 /** The selected option's `value`. */
 const model = defineModel<string>()
 
+const portalTo = usePortalTarget(() => props.to)
+
 // reka-ui filters items by their `textValue` against the typed query, so we
 // surface the visible label as the search text — this keeps filtering correct
 // even when the `#option` slot customises rendering.
@@ -48,7 +50,7 @@ function optionLabel(option: ComboboxOption) {
         class="color-base outline-none bg-transparent flex-1 min-w-0 placeholder:op-mute"
       />
     </ComboboxAnchor>
-    <ComboboxPortal>
+    <ComboboxPortal :to="portalTo">
       <ComboboxContent
         position="popper"
         :side-offset="6"
diff --git a/packages/design/components/Form/FormSelect.vue b/packages/design/components/Form/FormSelect.vue
index babec26..99df714 100644
--- a/packages/design/components/Form/FormSelect.vue
+++ b/packages/design/components/Form/FormSelect.vue
@@ -1,6 +1,7 @@
 <!-- @description a native-feeling select bound with `v-model`. -->
 <script setup lang="ts">
 import { SelectContent, SelectIcon, SelectItem, SelectItemIndicator, SelectItemText, SelectPortal, SelectRoot, SelectTrigger, SelectValue, SelectViewport } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
 export interface SelectOption {
   value: string
@@ -13,13 +14,17 @@ export interface SelectOption {
 // trigger — the element a caller means when they style "the select".
 defineOptions({ inheritAttrs: false })
 
-defineProps<{
+const props = defineProps<{
   options: SelectOption[]
   placeholder?: string
   disabled?: boolean
+  /** Teleport target for the list; defaults to the enclosing shadow root, else `document.body`. */
+  to?: string | HTMLElement
 }>()
 
 const model = defineModel<string>()
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -33,7 +38,7 @@ const model = defineModel<string>()
         <span class="i-ph:caret-down" aria-hidden="true" />
       </SelectIcon>
     </SelectTrigger>
-    <SelectPortal>
+    <SelectPortal :to="portalTo">
       <SelectContent
         position="popper"
         :side-offset="6"
diff --git a/packages/design/components/Layout/LayoutMenubar.vue b/packages/design/components/Layout/LayoutMenubar.vue
index 9aa0d9f..1fb7510 100644
--- a/packages/design/components/Layout/LayoutMenubar.vue
+++ b/packages/design/components/Layout/LayoutMenubar.vue
@@ -1,6 +1,7 @@
 <!-- @description a desktop-style menu bar from a `menus` list of `MenubarMenuEntry`. -->
 <script setup lang="ts">
 import { MenubarContent, MenubarItem, MenubarMenu, MenubarPortal, MenubarRoot, MenubarSeparator, MenubarTrigger } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 import DisplayKbd from '../Display/DisplayKbd.vue'
 
 export interface MenubarItemEntry {
@@ -19,8 +20,14 @@ export interface MenubarMenuEntry {
   items: MenubarItemEntry[]
 }
 
-defineProps<{ menus: MenubarMenuEntry[] }>()
+const props = defineProps<{
+  menus: MenubarMenuEntry[]
+  /** Teleport target for the menus; defaults to the enclosing shadow root, else `document.body`. */
+  to?: string | HTMLElement
+}>()
 const emit = defineEmits<{ select: [menu: string, item: string] }>()
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -29,7 +36,7 @@ const emit = defineEmits<{ select: [menu: string, item: string] }>()
       <MenubarTrigger class="text-sm px-2 py-1 outline-none rounded-md select-none data-[highlighted]:bg-hover data-[state=open]:bg-active focus-visible:ring-2 focus-visible:ring-primary-500/40">
         {{ menu.label }}
       </MenubarTrigger>
-      <MenubarPortal>
+      <MenubarPortal :to="portalTo">
         <MenubarContent
           :side-offset="6"
           align="start"
diff --git a/packages/design/components/Overlay/OverlayConfirm.vue b/packages/design/components/Overlay/OverlayConfirm.vue
index 8a17382..cfd127a 100644
--- a/packages/design/components/Overlay/OverlayConfirm.vue
+++ b/packages/design/components/Overlay/OverlayConfirm.vue
@@ -1,7 +1,6 @@
 <!-- @description an AlertDialog for a confirm/cancel decision, `variant="danger"` for destructive actions. -->
 <script setup lang="ts">
 import { AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogOverlay, AlertDialogPortal, AlertDialogRoot, AlertDialogTitle, AlertDialogTrigger } from 'reka-ui'
-import { ref } from 'vue'
 import { usePortalTarget } from '../../composables/portalTarget'
 
 const props = withDefaults(
@@ -21,45 +20,42 @@ const props = withDefaults(
 const emit = defineEmits<{ confirm: [], cancel: [] }>()
 const open = defineModel<boolean>('open')
 
-const anchor = ref<HTMLElement>()
-const portalTo = usePortalTarget(anchor, () => props.to)
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
-  <div ref="anchor" style="display: contents">
-    <AlertDialogRoot v-model:open="open">
-      <AlertDialogTrigger v-if="$slots.trigger" as-child>
-        <slot name="trigger" />
-      </AlertDialogTrigger>
-      <AlertDialogPortal :to="portalTo">
-        <AlertDialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
-        <!-- Centered by the wrapper, whose padding is also the minimum margin — see OverlayModal. -->
-        <div class="p-4 flex pointer-events-none items-center inset-0 justify-center fixed z-modal-content sm:p-6">
-          <AlertDialogContent
-            class="p-4 outline-none border border-base rounded-xl bg-base max-h-full max-w-sm w-full pointer-events-auto shadow-2xl overflow-auto"
-            data-af-modal
-          >
-            <AlertDialogTitle v-if="title" class="color-base font-medium">
-              {{ title }}
-            </AlertDialogTitle>
-            <AlertDialogDescription v-if="description" class="text-sm mt-1 op-fade">
-              {{ description }}
-            </AlertDialogDescription>
-            <div class="mt-4 flex gap-2 justify-end">
-              <AlertDialogCancel class="btn-action" @click="emit('cancel')">
-                {{ cancelLabel }}
-              </AlertDialogCancel>
-              <AlertDialogAction
-                class="btn-primary"
-                :class="variant === 'danger' ? 'bg-red-500! hover:bg-red-600!' : ''"
-                @click="emit('confirm')"
-              >
-                {{ confirmLabel }}
-              </AlertDialogAction>
-            </div>
-          </AlertDialogContent>
-        </div>
-      </AlertDialogPortal>
-    </AlertDialogRoot>
-  </div>
+  <AlertDialogRoot v-model:open="open">
+    <AlertDialogTrigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </AlertDialogTrigger>
+    <AlertDialogPortal :to="portalTo">
+      <AlertDialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
+      <!-- Centered by the wrapper, whose padding is also the minimum margin — see OverlayModal. -->
+      <div class="p-4 flex pointer-events-none items-center inset-0 justify-center fixed z-modal-content sm:p-6">
+        <AlertDialogContent
+          class="p-4 outline-none border border-base rounded-xl bg-base max-h-full max-w-sm w-full pointer-events-auto shadow-2xl overflow-auto"
+          data-af-modal
+        >
+          <AlertDialogTitle v-if="title" class="color-base font-medium">
+            {{ title }}
+          </AlertDialogTitle>
+          <AlertDialogDescription v-if="description" class="text-sm mt-1 op-fade">
+            {{ description }}
+          </AlertDialogDescription>
+          <div class="mt-4 flex gap-2 justify-end">
+            <AlertDialogCancel class="btn-action" @click="emit('cancel')">
+              {{ cancelLabel }}
+            </AlertDialogCancel>
+            <AlertDialogAction
+              class="btn-primary"
+              :class="variant === 'danger' ? 'bg-red-500! hover:bg-red-600!' : ''"
+              @click="emit('confirm')"
+            >
+              {{ confirmLabel }}
+            </AlertDialogAction>
+          </div>
+        </AlertDialogContent>
+      </div>
+    </AlertDialogPortal>
+  </AlertDialogRoot>
 </template>
diff --git a/packages/design/components/Overlay/OverlayContextMenu.vue b/packages/design/components/Overlay/OverlayContextMenu.vue
index a3283f6..65b0ced 100644
--- a/packages/design/components/Overlay/OverlayContextMenu.vue
+++ b/packages/design/components/Overlay/OverlayContextMenu.vue
@@ -1,10 +1,15 @@
 <!-- @description a right-click menu. -->
 <script setup lang="ts">
 import { ContextMenuContent, ContextMenuPortal, ContextMenuRoot, ContextMenuTrigger } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
-defineProps<{
+const props = defineProps<{
   disabled?: boolean
+  /** Teleport target for the menu; defaults to the enclosing shadow root, else `document.body`. */
+  to?: string | HTMLElement
 }>()
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -12,7 +17,7 @@ defineProps<{
     <ContextMenuTrigger :disabled="disabled" as-child>
       <slot name="trigger" />
     </ContextMenuTrigger>
-    <ContextMenuPortal>
+    <ContextMenuPortal :to="portalTo">
       <ContextMenuContent
         :collision-padding="8"
         class="p-1 outline-none border border-base rounded-lg bg-glass:75 min-w-40 shadow-lg z-dropdown"
diff --git a/packages/design/components/Overlay/OverlayDrawer.vue b/packages/design/components/Overlay/OverlayDrawer.vue
index 8540175..8ea860d 100644
--- a/packages/design/components/Overlay/OverlayDrawer.vue
+++ b/packages/design/components/Overlay/OverlayDrawer.vue
@@ -1,7 +1,7 @@
 <!-- @description a slide-in panel from any `side` (left/right/top/bottom), sized by `width`. -->
 <script setup lang="ts">
 import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
-import { computed, ref } from 'vue'
+import { computed } from 'vue'
 import { usePortalTarget } from '../../composables/portalTarget'
 
 const props = withDefaults(
@@ -23,8 +23,7 @@ const props = withDefaults(
 
 const open = defineModel<boolean>('open')
 
-const anchor = ref<HTMLElement>()
-const portalTo = usePortalTarget(anchor, () => props.to)
+const portalTo = usePortalTarget(() => props.to)
 
 const SIDE_CLASS = {
   right: 'right-0 top-0 h-full w-80 max-w-[90vw] border-l',
@@ -42,40 +41,38 @@ const style = computed(() => {
 </script>
 
 <template>
-  <div ref="anchor" style="display: contents">
-    <DialogRoot v-model:open="open">
-      <DialogTrigger v-if="$slots.trigger" as-child>
-        <slot name="trigger" />
-      </DialogTrigger>
-      <DialogPortal :to="portalTo">
-        <DialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-drawer-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
-        <DialogContent
-          class="outline-none border-base bg-base flex flex-col shadow-2xl fixed z-drawer-content"
-          :class="SIDE_CLASS[side]"
-          :style="style"
-          data-af-drawer
-          :data-side="side"
-        >
-          <header class="px-4 py-3 border-b border-base flex shrink-0 gap-4 items-center justify-between">
-            <DialogTitle v-if="title" class="color-base font-medium">
-              {{ title }}
-            </DialogTitle>
-            <DialogDescription v-if="$slots.description" class="sr-only">
-              <slot name="description" />
-            </DialogDescription>
-            <slot name="header" />
-            <DialogClose class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
-              <span class="i-ph:x" aria-hidden="true" />
-            </DialogClose>
-          </header>
-          <div class="p-4 flex-1 overflow-auto">
-            <slot />
-          </div>
-          <footer v-if="$slots.footer" class="px-4 py-3 border-t border-base flex shrink-0 gap-2 items-center justify-end">
-            <slot name="footer" />
-          </footer>
-        </DialogContent>
-      </DialogPortal>
-    </DialogRoot>
-  </div>
+  <DialogRoot v-model:open="open">
+    <DialogTrigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </DialogTrigger>
+    <DialogPortal :to="portalTo">
+      <DialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-drawer-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
+      <DialogContent
+        class="outline-none border-base bg-base flex flex-col shadow-2xl fixed z-drawer-content"
+        :class="SIDE_CLASS[side]"
+        :style="style"
+        data-af-drawer
+        :data-side="side"
+      >
+        <header class="px-4 py-3 border-b border-base flex shrink-0 gap-4 items-center justify-between">
+          <DialogTitle v-if="title" class="color-base font-medium">
+            {{ title }}
+          </DialogTitle>
+          <DialogDescription v-if="$slots.description" class="sr-only">
+            <slot name="description" />
+          </DialogDescription>
+          <slot name="header" />
+          <DialogClose class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
+            <span class="i-ph:x" aria-hidden="true" />
+          </DialogClose>
+        </header>
+        <div class="p-4 flex-1 overflow-auto">
+          <slot />
+        </div>
+        <footer v-if="$slots.footer" class="px-4 py-3 border-t border-base flex shrink-0 gap-2 items-center justify-end">
+          <slot name="footer" />
+        </footer>
+      </DialogContent>
+    </DialogPortal>
+  </DialogRoot>
 </template>
diff --git a/packages/design/components/Overlay/OverlayDropdown.vue b/packages/design/components/Overlay/OverlayDropdown.vue
index 2ccb0d6..feca2ac 100644
--- a/packages/design/components/Overlay/OverlayDropdown.vue
+++ b/packages/design/components/Overlay/OverlayDropdown.vue
@@ -1,14 +1,19 @@
 <!-- @description a trigger-anchored dropdown menu. -->
 <script setup lang="ts">
 import { DropdownMenuContent, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuTrigger } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
-withDefaults(
+const props = withDefaults(
   defineProps<{
     placement?: 'top' | 'right' | 'bottom' | 'left'
     align?: 'start' | 'center' | 'end'
+    /** Teleport target for the menu; defaults to the enclosing shadow root, else `document.body`. */
+    to?: string | HTMLElement
   }>(),
   { placement: 'bottom', align: 'start' },
 )
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -16,7 +21,7 @@ withDefaults(
     <DropdownMenuTrigger as-child>
       <slot name="trigger" />
     </DropdownMenuTrigger>
-    <DropdownMenuPortal>
+    <DropdownMenuPortal :to="portalTo">
       <DropdownMenuContent
         :side="placement"
         :align="align"
diff --git a/packages/design/components/Overlay/OverlayDropdownSub.vue b/packages/design/components/Overlay/OverlayDropdownSub.vue
index d213d9d..03025b5 100644
--- a/packages/design/components/Overlay/OverlayDropdownSub.vue
+++ b/packages/design/components/Overlay/OverlayDropdownSub.vue
@@ -1,13 +1,18 @@
 <script setup lang="ts">
 import { DropdownMenuPortal, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
-defineProps<{
+const props = defineProps<{
   /** Submenu trigger label (or use the `trigger` slot for rich content). */
   label?: string
   /** Optional leading icon class for the trigger. */
   icon?: string
   disabled?: boolean
+  /** Teleport target for the submenu; defaults to the enclosing shadow root, else `document.body`. */
+  to?: string | HTMLElement
 }>()
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -20,7 +25,7 @@ defineProps<{
       <span class="flex-1"><slot name="trigger">{{ label }}</slot></span>
       <span class="i-ph:caret-right op-fade" aria-hidden="true" />
     </DropdownMenuSubTrigger>
-    <DropdownMenuPortal>
+    <DropdownMenuPortal :to="portalTo">
       <DropdownMenuSubContent
         :side-offset="4"
         :align-offset="-4"
diff --git a/packages/design/components/Overlay/OverlayHoverCard.vue b/packages/design/components/Overlay/OverlayHoverCard.vue
index 9939bf1..2d8ba31 100644
--- a/packages/design/components/Overlay/OverlayHoverCard.vue
+++ b/packages/design/components/Overlay/OverlayHoverCard.vue
@@ -1,16 +1,21 @@
 <!-- @description a hover-triggered popover with configurable `openDelay`/`closeDelay`. -->
 <script setup lang="ts">
 import { HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from 'reka-ui'
+import { usePortalTarget } from '../../composables/portalTarget'
 
-withDefaults(
+const props = withDefaults(
   defineProps<{
     placement?: 'top' | 'right' | 'bottom' | 'left'
     align?: 'start' | 'center' | 'end'
     openDelay?: number
     closeDelay?: number
+    /** Teleport target for the card; defaults to the enclosing shadow root, else `document.body`. */
+    to?: string | HTMLElement
   }>(),
   { placement: 'bottom', align: 'center', openDelay: 200, closeDelay: 150 },
 )
+
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
@@ -18,7 +23,7 @@ withDefaults(
     <HoverCardTrigger as-child>
       <slot name="trigger" />
     </HoverCardTrigger>
-    <HoverCardPortal>
+    <HoverCardPortal :to="portalTo">
       <HoverCardContent
         :side="placement"
         :align="align"
diff --git a/packages/design/components/Overlay/OverlayModal.vue b/packages/design/components/Overlay/OverlayModal.vue
index 45a6bba..5c35d90 100644
--- a/packages/design/components/Overlay/OverlayModal.vue
+++ b/packages/design/components/Overlay/OverlayModal.vue
@@ -1,7 +1,6 @@
 <!-- @description a centered dialog (`title`, `description`, `#trigger` slot). -->
 <script setup lang="ts">
 import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
-import { ref } from 'vue'
 import { usePortalTarget } from '../../composables/portalTarget'
 
 const props = defineProps<{
@@ -13,54 +12,51 @@ const props = defineProps<{
 
 const open = defineModel<boolean>('open')
 
-const anchor = ref<HTMLElement>()
-const portalTo = usePortalTarget(anchor, () => props.to)
+const portalTo = usePortalTarget(() => props.to)
 </script>
 
 <template>
-  <div ref="anchor" style="display: contents">
-    <DialogRoot v-model:open="open">
-      <DialogTrigger v-if="$slots.trigger" as-child>
-        <slot name="trigger" />
-      </DialogTrigger>
-      <DialogPortal :to="portalTo">
-        <DialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
-        <!--
-          Centering lives on this wrapper rather than on the content itself: a
-          `left-1/2 -translate-x-1/2` content box double-shifts under Wind4 (whose
-          translate utilities use the native `translate` property, which stacks on
-          top of the animation's `transform`). The padding here doubles as the
-          modal's minimum margin, and makes `max-h-full` mean "viewport minus that
-          margin", so tall content scrolls in the body instead of overflowing.
-        -->
-        <div class="p-4 flex pointer-events-none items-center inset-0 justify-center fixed z-modal-content">
-          <DialogContent
-            class="outline-none border border-base rounded-lg bg-base flex flex-col max-h-full max-w-lg w-full pointer-events-auto shadow-xl overflow-hidden"
-            data-af-modal
-          >
-            <header v-if="title || description || $slots.header" class="px-3 py-2 border-b border-base flex shrink-0 gap-2 items-start justify-between">
-              <div class="min-w-0">
-                <DialogTitle v-if="title" class="color-base font-medium">
-                  {{ title }}
-                </DialogTitle>
-                <DialogDescription v-if="description" class="text-sm op-fade">
-                  {{ description }}
-                </DialogDescription>
-                <slot name="header" />
-              </div>
-              <DialogClose class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
-                <span class="i-ph:x" aria-hidden="true" />
-              </DialogClose>
-            </header>
-            <div class="p-3 flex-1 overflow-auto">
-              <slot />
+  <DialogRoot v-model:open="open">
+    <DialogTrigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </DialogTrigger>
+    <DialogPortal :to="portalTo">
+      <DialogOverlay class="bg-[#ddd]/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm dark:bg-black/40" data-af-animate />
+      <!--
+        Centering lives on this wrapper rather than on the content itself: a
+        `left-1/2 -translate-x-1/2` content box double-shifts under Wind4 (whose
+        translate utilities use the native `translate` property, which stacks on
+        top of the animation's `transform`). The padding here doubles as the
+        modal's minimum margin, and makes `max-h-full` mean "viewport minus that
+        margin", so tall content scrolls in the body instead of overflowing.
+      -->
+      <div class="p-4 flex pointer-events-none items-center inset-0 justify-center fixed z-modal-content">
+        <DialogContent
+          class="outline-none border border-base rounded-lg bg-base flex flex-col max-h-full max-w-lg w-full pointer-events-auto shadow-xl overflow-hidden"
+          data-af-modal
+        >
+          <header v-if="title || description || $slots.header" class="px-3 py-2 border-b border-base flex shrink-0 gap-2 items-start justify-between">
+            <div class="min-w-0">
+              <DialogTitle v-if="title" class="color-base font-medium">
+                {{ title }}
+              </DialogTitle>
+              <DialogDescription v-if="description" class="text-sm op-fade">
+                {{ description }}
+              </DialogDescription>
+              <slot name="header" />
             </div>
-            <footer v-if="$slots.footer" class="px-2 py-2 border-t border-base flex shrink-0 gap-2 justify-end">
-              <slot name="footer" />
-            </footer>
-          </DialogContent>
-        </div>
-      </DialogPortal>
-    </DialogRoot>
-  </div>
+            <DialogClose class="btn-icon shrink-0 h-7 w-7" aria-label="Close">
+              <span class="i-ph:x" aria-hidden="true" />
+            </DialogClose>
+          </header>
+          <div class="p-3 flex-1 overflow-auto">
+            <slot />
+          </div>
+          <footer v-if="$slots.footer" class="px-2 py-2 border-t border-base flex shrink-0 gap-2 justify-end">
+            <slot name="footer" />
+          </footer>
+        </DialogContent>
+      </div>
+    </DialogPortal>
+  </DialogRoot>
 </template>
diff --git a/packages/design/components/Overview.mdx b/packages/design/components/Overview.mdx
index 324b806..63d6181 100644
--- a/packages/design/components/Overview.mdx
+++ b/packages/design/components/Overview.mdx
@@ -64,6 +64,7 @@ import * as OverlayHoverCard from './Overlay/OverlayHoverCard.stories'
 import * as OverlayModal from './Overlay/OverlayModal.stories'
 import * as OverlayTooltip from './Overlay/OverlayTooltip.stories'
 import * as ScrollFade from './Utility/ScrollFade.stories'
+import * as ShadowRoot from './Utility/ShadowRoot.stories'
 import * as Shimmer from './Utility/Shimmer.stories'
 
 <Meta title="Overview" />
@@ -454,6 +455,10 @@ A composable, token-driven design system for devtools-style Vue apps. Each tile
 <Canvas of={ScrollFade.FadeSize} />
 <Canvas of={ScrollFade.Disabled} />
 
+### [ShadowRoot](/?path=/docs/utility-shadowroot--docs)
+
+<Canvas of={ShadowRoot.Default} />
+
 ### [Shimmer](/?path=/docs/utility-shimmer--docs)
 
 <Canvas of={Shimmer.Default} />
diff --git a/packages/design/components/Utility/ShadowRoot.stories.ts b/packages/design/components/Utility/ShadowRoot.stories.ts
new file mode 100644
index 0000000..230086a
--- /dev/null
+++ b/packages/design/components/Utility/ShadowRoot.stories.ts
@@ -0,0 +1,145 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { createApp, defineComponent, h, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useToast } from '../../composables/toast'
+import ActionButton from '../Action/ActionButton.vue'
+import FeedbackToasts from '../Feedback/FeedbackToasts.vue'
+import FormCombobox from '../Form/FormCombobox.vue'
+import FormSelect from '../Form/FormSelect.vue'
+import LayoutMenubar from '../Layout/LayoutMenubar.vue'
+import OverlayConfirm from '../Overlay/OverlayConfirm.vue'
+import OverlayContextMenu from '../Overlay/OverlayContextMenu.vue'
+import OverlayContextMenuItem from '../Overlay/OverlayContextMenuItem.vue'
+import OverlayDrawer from '../Overlay/OverlayDrawer.vue'
+import OverlayDropdown from '../Overlay/OverlayDropdown.vue'
+import OverlayDropdownItem from '../Overlay/OverlayDropdownItem.vue'
+import OverlayDropdownSub from '../Overlay/OverlayDropdownSub.vue'
+import OverlayHoverCard from '../Overlay/OverlayHoverCard.vue'
+import OverlayModal from '../Overlay/OverlayModal.vue'
+
+// Every component that portals content (selects, menus, dialogs, toasts) must
+// keep it inside the shadow root that holds the stylesheet. This mounts them
+// all in one, the way a devtools overlay built with `defineCustomElement` would.
+
+const options = ['TypeScript', 'Vue', 'UnoCSS', 'Vite'].map(value => ({ value }))
+const menus = [
+  { value: 'file', label: 'File', items: [{ value: 'new', label: 'New', shortcut: 'mod+n' }, { value: 'open', label: 'Open…', shortcut: 'mod+o' }] },
+  { value: 'edit', label: 'Edit', items: [{ value: 'undo', label: 'Undo', shortcut: 'mod+z' }, { value: 'redo', label: 'Redo', shortcut: 'mod+shift+z' }] },
+]
+
+const Embedded = defineComponent({
+  components: {
+    ActionButton,
+    FeedbackToasts,
+    FormCombobox,
+    FormSelect,
+    LayoutMenubar,
+    OverlayConfirm,
+    OverlayContextMenu,
+    OverlayContextMenuItem,
+    OverlayDrawer,
+    OverlayDropdown,
+    OverlayDropdownItem,
+    OverlayDropdownSub,
+    OverlayHoverCard,
+    OverlayModal,
+  },
+  setup() {
+    const toast = useToast()
+    return { options, menus, toast, selected: ref('Vue'), searched: ref<string>() }
+  },
+  template: `<div class="p-4 border border-base rounded-lg bg-base color-base flex flex-col gap-4 w-120 font-sans">
+    <LayoutMenubar :menus="menus" @select="(m, i) => toast.info(m + ' › ' + i)" />
+    <div class="flex gap-2 flex-wrap items-center">
+      <FormSelect v-model="selected" :options="options" />
+      <FormCombobox v-model="searched" :options="options" placeholder="Search…" />
+    </div>
+    <div class="flex gap-2 flex-wrap items-center">
+      <OverlayDropdown>
+        <template #trigger><ActionButton icon="i-ph:gear">Dropdown</ActionButton></template>
+        <OverlayDropdownItem icon="i-ph:folder">Open</OverlayDropdownItem>
+        <OverlayDropdownSub label="Share" icon="i-ph:share-network">
+          <OverlayDropdownItem icon="i-ph:link">Copy link</OverlayDropdownItem>
+          <OverlayDropdownItem icon="i-ph:envelope">Email</OverlayDropdownItem>
+        </OverlayDropdownSub>
+        <OverlayDropdownItem icon="i-ph:trash" variant="danger">Delete</OverlayDropdownItem>
+      </OverlayDropdown>
+      <OverlayHoverCard>
+        <template #trigger><ActionButton variant="text" icon="i-ph:info">Hover card</ActionButton></template>
+        Rendered inside the shadow root, so the glass surface and border tokens apply.
+      </OverlayHoverCard>
+      <OverlayModal title="Modal" description="Teleported into the shadow root.">
+        <template #trigger><ActionButton>Modal</ActionButton></template>
+        <p class="text-sm color-muted">Scheme, surface and border tokens all resolve here.</p>
+      </OverlayModal>
+      <OverlayDrawer title="Drawer">
+        <template #trigger><ActionButton>Drawer</ActionButton></template>
+        <p class="text-sm color-muted">Slides in over the host page, styled from the root's sheet.</p>
+      </OverlayDrawer>
+      <OverlayConfirm title="Delete project?" description="This cannot be undone." variant="danger" confirm-label="Delete" @confirm="toast.error('Deleted')">
+        <template #trigger><ActionButton variant="text" icon="i-ph:trash">Confirm</ActionButton></template>
+      </OverlayConfirm>
+      <ActionButton variant="text" icon="i-ph:bell" @click="toast.success('Saved', { icon: 'i-ph:check-circle' })">Toast</ActionButton>
+    </div>
+    <OverlayContextMenu>
+      <template #trigger>
+        <div class="h-20 grid place-items-center border border-base rounded-lg border-dashed color-faint text-sm select-none">Right-click here</div>
+      </template>
+      <OverlayContextMenuItem icon="i-ph:copy" shortcut="mod+c">Copy</OverlayContextMenuItem>
+      <OverlayContextMenuItem icon="i-ph:scissors" shortcut="mod+x">Cut</OverlayContextMenuItem>
+      <OverlayContextMenuItem icon="i-ph:trash" variant="danger" shortcut="del">Delete</OverlayContextMenuItem>
+    </OverlayContextMenu>
+    <FeedbackToasts :items="toast.toasts.value" @dismiss="toast.dismiss" />
+  </div>`,
+})
+
+// The raw CSS source, not CSSOM `cssText`: Chromium serializes shorthands
+// holding `var()` (the icon `mask`) as empty, which would break every icon.
+async function documentCss(): Promise<string> {
+  const sources = Array.from(document.querySelectorAll('style, link[rel="stylesheet"]'), el =>
+    el instanceof HTMLLinkElement ? fetch(el.href).then(r => r.text()) : el.textContent ?? '')
+  return (await Promise.all(sources)).join('\n')
+}
+
+/** Mounts {@link Embedded} in a shadow root, with the document's sheets injected the way `defineCustomElement({ styles })` would. */
+const ShadowHost = defineComponent({
+  props: { dark: Boolean },
+  setup(props) {
+    const host = ref<HTMLElement>()
+    const app = createApp(Embedded)
+
+    // The scheme wrapper the README asks for: the class on an ancestor, the
+    // surface utilities on its child.
+    const wrapper = document.createElement('div')
+    wrapper.style.display = 'contents'
+    watch(() => props.dark, (dark) => {
+      wrapper.className = dark ? 'dark' : 'light'
+    }, { immediate: true })
+
+    onMounted(async () => {
+      const shadow = host.value!.attachShadow({ mode: 'open' })
+      const style = document.createElement('style')
+      style.textContent = await documentCss()
+      shadow.append(style, wrapper)
+      app.mount(wrapper)
+    })
+    onBeforeUnmount(() => app.unmount())
+    return () => h('div', { ref: host })
+  },
+})
+
+const meta = {
+  title: 'Utilities/ShadowRoot',
+  component: ShadowHost,
+  tags: ['autodocs'],
+} satisfies Meta<typeof ShadowHost>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: (_, { globals }) => ({
+    components: { ShadowHost },
+    setup: () => ({ dark: globals.theme === 'dark' }),
+    template: `<ShadowHost :dark="dark" />`,
+  }),
+}
diff --git a/packages/design/composables/portalTarget.ts b/packages/design/composables/portalTarget.ts
index 734a2ba..b159f90 100644
--- a/packages/design/composables/portalTarget.ts
+++ b/packages/design/composables/portalTarget.ts
@@ -2,39 +2,62 @@
  * Teleport target for portaled overlays inside a shadow root.
  *
  * reka-ui teleports overlay content to `document.body` by default, which is
- * outside the shadow root that holds the injected stylesheet — so a modal
+ * outside the shadow root that holds the injected stylesheet — so a popup
  * mounted via `defineCustomElement` renders unstyled and outside the tree it
  * belongs to. This resolves a target that keeps the overlay inside the root:
  * an explicit `to` wins, otherwise a container appended to the enclosing
  * `ShadowRoot` (when there is one), otherwise `undefined` so reka falls back to
  * its own `ConfigProvider`/`body` resolution unchanged.
+ *
+ * The container also mirrors the `dark`/`light` class of the component's
+ * nearest scheme wrapper: `dark:` utilities compile to a descendant selector
+ * (`.dark .x`), and a child of the `ShadowRoot` has no `.dark` ancestor of its
+ * own.
  */
-import type { ComputedRef, MaybeRefOrGetter } from 'vue'
-import { computed, onBeforeUnmount, onMounted, shallowRef, toValue } from 'vue'
+import type { ComputedRef } from 'vue'
+import { computed, getCurrentInstance, onBeforeUnmount, onMounted, shallowRef } from 'vue'
 
 /**
- * Resolve the teleport target for an overlay's portal.
+ * Resolve the teleport target for the calling component's portal.
+ *
+ * Call it in `setup`: the enclosing {@link ShadowRoot} is detected from the
+ * component's own root node once mounted.
  *
- * @param anchor - An element rendered in the component's normal tree (not the
- * portaled content), used to detect the enclosing {@link ShadowRoot}.
  * @param explicit - Getter for a caller-provided `to` override.
- * @returns The target to pass to reka's `*Portal` `to` prop.
+ * @returns The target to pass to reka's `*Portal` (or `<Teleport>`) `to` prop.
  */
 export function usePortalTarget(
-  anchor: MaybeRefOrGetter<Element | null | undefined>,
   explicit?: () => string | HTMLElement | undefined,
 ): ComputedRef<string | HTMLElement | undefined> {
+  const instance = getCurrentInstance()
   const container = shallowRef<HTMLElement>()
+  let observer: MutationObserver | undefined
 
   onMounted(() => {
-    const root = toValue(anchor)?.getRootNode()
-    if (root instanceof ShadowRoot) {
-      container.value = document.createElement('div')
-      root.append(container.value)
+    // For fragment/teleport roots `$el` is Vue's placeholder node, which still
+    // sits in the component's own tree — enough to find the root.
+    const el: Node | undefined = instance?.proxy?.$el
+    const root = el?.getRootNode()
+    if (!(root instanceof ShadowRoot))
+      return
+
+    const target = document.createElement('div')
+    root.append(target)
+    container.value = target
+
+    const scheme = (el instanceof Element ? el : el?.parentElement)?.closest('.dark, .light')
+    if (scheme) {
+      const sync = (): void => {
+        target.className = scheme.classList.contains('dark') ? 'dark' : 'light'
+      }
+      sync()
+      observer = new MutationObserver(sync)
+      observer.observe(scheme, { attributeFilter: ['class'] })
     }
   })
 
   onBeforeUnmount(() => {
+    observer?.disconnect()
     container.value?.remove()
     container.value = undefined
   })
diff --git a/packages/design/test/overlay-portal.test.ts b/packages/design/test/overlay-portal.test.ts
deleted file mode 100644
index 3a9b809..0000000
--- a/packages/design/test/overlay-portal.test.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-import type { Component } from 'vue'
-import { mount } from '@vue/test-utils'
-import { afterEach, describe, expect, it } from 'vitest'
-import { nextTick } from 'vue'
-import Confirm from '../components/Overlay/OverlayConfirm.vue'
-import Drawer from '../components/Overlay/OverlayDrawer.vue'
-import Modal from '../components/Overlay/OverlayModal.vue'
-
-const dialogs: [name: string, component: Component, marker: string][] = [
-  ['modal', Modal, '[data-af-modal]'],
-  ['drawer', Drawer, '[data-af-drawer]'],
-  ['confirm', Confirm, '[data-af-modal]'],
-]
-
-afterEach(() => {
-  document.body.innerHTML = ''
-})
-
-describe('dialog portals default to document.body', () => {
-  it.each(dialogs)('%s teleports its content to the body', async (_name, component, marker) => {
-    mount(component, { props: { open: true } })
-    await nextTick()
-    await nextTick()
-    expect(document.body.querySelector(marker)).toBeTruthy()
-  })
-})
-
-describe('dialog portals stay inside a shadow root', () => {
-  it.each(dialogs)('%s teleports its content into the enclosing shadow root, not the body', async (_name, component, marker) => {
-    const host = document.createElement('div')
-    document.body.append(host)
-    const shadow = host.attachShadow({ mode: 'open' })
-    const mountPoint = document.createElement('div')
-    shadow.append(mountPoint)
-
-    mount(component, { attachTo: mountPoint, props: { open: true } })
-    await nextTick()
-    await nextTick()
-
-    expect(shadow.querySelector(marker)).toBeTruthy()
-    // The whole point: it must not escape to the light-DOM body, where the
-    // shadow root's stylesheet can't reach it.
-    expect(document.body.querySelector(marker)).toBeNull()
-  })
-})
-
-describe('an explicit `to` wins over auto-detection', () => {
-  it('teleports into the given container', async () => {
-    const host = document.createElement('div')
-    document.body.append(host)
-    const shadow = host.attachShadow({ mode: 'open' })
-    const mountPoint = document.createElement('div')
-    shadow.append(mountPoint)
-
-    const target = document.createElement('div')
-    target.id = 'target'
-    document.body.append(target)
-
-    mount(Modal, { attachTo: mountPoint, props: { open: true, to: target } })
-    await nextTick()
-    await nextTick()
-
-    expect(target.querySelector('[data-af-modal]')).toBeTruthy()
-    expect(shadow.querySelector('[data-af-modal]')).toBeNull()
-  })
-})
diff --git a/packages/design/test/portal.test.ts b/packages/design/test/portal.test.ts
new file mode 100644
index 0000000..bbaea37
--- /dev/null
+++ b/packages/design/test/portal.test.ts
@@ -0,0 +1,200 @@
+import type { VueWrapper } from '@vue/test-utils'
+import type { Component } from 'vue'
+import { mount as mountComponent } from '@vue/test-utils'
+import { afterEach, describe, expect, it } from 'vitest'
+import { h, nextTick } from 'vue'
+import Toasts from '../components/Feedback/FeedbackToasts.vue'
+import Combobox from '../components/Form/FormCombobox.vue'
+import Select from '../components/Form/FormSelect.vue'
+import Menubar from '../components/Layout/LayoutMenubar.vue'
+import Confirm from '../components/Overlay/OverlayConfirm.vue'
+import ContextMenu from '../components/Overlay/OverlayContextMenu.vue'
+import Drawer from '../components/Overlay/OverlayDrawer.vue'
+import Dropdown from '../components/Overlay/OverlayDropdown.vue'
+import DropdownItem from '../components/Overlay/OverlayDropdownItem.vue'
+import DropdownSub from '../components/Overlay/OverlayDropdownSub.vue'
+import HoverCard from '../components/Overlay/OverlayHoverCard.vue'
+import Modal from '../components/Overlay/OverlayModal.vue'
+
+const settle = () => new Promise(resolve => setTimeout(resolve, 10))
+
+const options = [{ value: 'a' }, { value: 'b' }]
+const trigger = () => h('button', { 'data-trigger': '' }, 'open')
+const marker = () => h('span', { 'data-marker': '' }, 'content')
+
+interface Case {
+  name: string
+  component: Component
+  props?: Record<string, unknown>
+  slots?: Record<string, () => ReturnType<typeof h>>
+  /** Portaled-content selector. */
+  marker: string
+  /** Open the popup from its trigger inside `root`. */
+  open?: (root: ParentNode) => Promise<void>
+}
+
+async function fire(root: ParentNode, selector: string, event: Event) {
+  root.querySelector(selector)!.dispatchEvent(event)
+  await nextTick()
+  await settle()
+}
+
+const cases: Case[] = [
+  { name: 'modal', component: Modal, props: { open: true }, marker: '[data-af-modal]' },
+  { name: 'drawer', component: Drawer, props: { open: true }, marker: '[data-af-drawer]' },
+  { name: 'confirm', component: Confirm, props: { open: true }, marker: '[data-af-modal]' },
+  { name: 'toasts', component: Toasts, props: { items: [{ id: 1, message: 'hi' }] }, marker: '[role="region"]' },
+  {
+    name: 'select',
+    component: Select,
+    props: { options },
+    marker: '[role="listbox"]',
+    open: root => fire(root, '[role="combobox"]', new KeyboardEvent('keydown', { key: 'Enter', bubbles: true })),
+  },
+  {
+    name: 'combobox',
+    component: Combobox,
+    props: { options },
+    marker: '[role="listbox"]',
+    open: root => fire(root, 'input', new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true })),
+  },
+  {
+    name: 'menubar',
+    component: Menubar,
+    props: { menus: [{ value: 'file', label: 'File', items: [{ value: 'new', label: 'New' }] }] },
+    marker: '[role="menu"]',
+    open: root => fire(root, '[role="menuitem"]', new PointerEvent('pointerdown', { button: 0, bubbles: true })),
+  },
+  {
+    name: 'dropdown',
+    component: Dropdown,
+    slots: { trigger, default: marker },
+    marker: '[data-marker]',
+    open: root => fire(root, '[data-trigger]', new MouseEvent('click', { button: 0, bubbles: true })),
+  },
+  {
+    name: 'dropdown submenu',
+    component: Dropdown,
+    slots: {
+      trigger,
+      default: () => h(DropdownSub, { label: 'More' }, { default: () => h(DropdownItem, { label: 'Deep' }, { default: marker }) }),
+    },
+    marker: '[data-marker]',
+    open: async (root) => {
+      await fire(root, '[data-trigger]', new MouseEvent('click', { button: 0, bubbles: true }))
+      await fire(root, '[aria-haspopup="menu"][role="menuitem"]', new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }))
+    },
+  },
+  {
+    name: 'hover card',
+    component: HoverCard,
+    props: { openDelay: 0 },
+    slots: { trigger, default: marker },
+    marker: '[data-marker]',
+    open: root => fire(root, '[data-trigger]', new PointerEvent('pointerenter', { pointerType: 'mouse' })),
+  },
+  {
+    name: 'context menu',
+    component: ContextMenu,
+    slots: { trigger, default: marker },
+    marker: '[data-marker]',
+    open: root => fire(root, '[data-trigger]', new MouseEvent('contextmenu', { bubbles: true, cancelable: true })),
+  },
+]
+
+const mounted: VueWrapper[] = []
+const mount: typeof mountComponent = (...args) => {
+  const wrapper = mountComponent(...args)
+  mounted.push(wrapper)
+  return wrapper
+}
+
+function shadowMountPoint() {
+  const host = document.createElement('div')
+  document.body.append(host)
+  const shadow = host.attachShadow({ mode: 'open' })
+  const mountPoint = document.createElement('div')
+  shadow.append(mountPoint)
+  return { shadow, mountPoint }
+}
+
+afterEach(() => {
+  mounted.splice(0).forEach(wrapper => wrapper.unmount())
+  document.body.innerHTML = ''
+})
+
+/** The container `usePortalTarget` appended to the shadow root. */
+function portalContainer(shadow: ShadowRoot) {
+  return Array.from(shadow.children).find(child => child.querySelector('[data-af-modal]'))!
+}
+
+describe('portals default to document.body', () => {
+  it.each(cases)('$name teleports its content to the body', async ({ component, props, slots, marker, open }) => {
+    mount(component, { attachTo: document.body, props, slots })
+    await nextTick()
+    await open?.(document.body)
+    await nextTick()
+    expect(document.body.querySelector(marker)).toBeTruthy()
+  })
+})
+
+describe('portals stay inside a shadow root', () => {
+  it.each(cases)('$name teleports its content into the enclosing shadow root, not the body', async ({ component, props, slots, marker, open }) => {
+    const { shadow, mountPoint } = shadowMountPoint()
+
+    mount(component, { attachTo: mountPoint, props, slots })
+    await nextTick()
+    await open?.(shadow)
+    await nextTick()
+
+    expect(shadow.querySelector(marker)).toBeTruthy()
+    // The whole point: it must not escape to the light-DOM body, where the
+    // shadow root's stylesheet can't reach it.
+    expect(document.body.querySelector(marker)).toBeNull()
+  })
+})
+
+describe('an explicit `to` wins over auto-detection', () => {
+  it('teleports into the given container', async () => {
+    const { shadow, mountPoint } = shadowMountPoint()
+
+    const target = document.createElement('div')
+    document.body.append(target)
+
+    mount(Modal, { attachTo: mountPoint, props: { open: true, to: target } })
+    await nextTick()
+    await nextTick()
+
+    expect(target.querySelector('[data-af-modal]')).toBeTruthy()
+    expect(shadow.querySelector('[data-af-modal]')).toBeNull()
+  })
+})
+
+describe('the portal container mirrors the scheme wrapper', () => {
+  it('copies `dark`/`light` from the nearest scheme ancestor and follows toggles', async () => {
+    const { shadow, mountPoint } = shadowMountPoint()
+    mountPoint.className = 'dark'
+
+    mount(Modal, { attachTo: mountPoint, props: { open: true } })
+    await nextTick()
+    await nextTick()
+
+    const container = portalContainer(shadow)
+    expect(container.classList.contains('dark')).toBe(true)
+
+    mountPoint.className = 'light'
+    await settle()
+    expect(container.classList.contains('dark')).toBe(false)
+    expect(container.classList.contains('light')).toBe(true)
+  })
+
+  it('leaves the container bare when there is no scheme wrapper', async () => {
+    const { shadow, mountPoint } = shadowMountPoint()
+
+    mount(Modal, { attachTo: mountPoint, props: { open: true } })
+    await nextTick()
+    await nextTick()
+
+    expect(portalContainer(shadow).className).toBe('')
+  })
+})
diff --git a/packages/design/test/scroll-fade.test.ts b/packages/design/test/scroll-fade.test.ts
index 7d4dbb0..d7bdcb4 100644
--- a/packages/design/test/scroll-fade.test.ts
+++ b/packages/design/test/scroll-fade.test.ts
@@ -60,7 +60,7 @@ describe('shimmer (ported from shadcn/ui)', () => {
     const css = await generate('shimmer', true)
     expect(css).toContain('@keyframes tw-shimmer')
     expect(css).toContain('background-clip:text')
-    expect(css).toContain('html.dark')
+    expect(css).toContain(':where(.dark) .shimmer')
     expect(css).toContain('prefers-reduced-motion:reduce')
   })
 })
diff --git a/packages/design/unocss/shimmer.ts b/packages/design/unocss/shimmer.ts
index 27b4809..7b16a3d 100644
--- a/packages/design/unocss/shimmer.ts
+++ b/packages/design/unocss/shimmer.ts
@@ -32,7 +32,7 @@ export const shimmerRules: Rule[] = [
       'animation': 'tw-shimmer var(--shimmer-duration, 2s) linear infinite',
     },
     `@keyframes tw-shimmer{from{background-position:100% 0}to{background-position:0 0}}`,
-    `:where(html.dark) .shimmer{--_highlight:var(--shimmer-color,oklch(from currentColor max(0.8,calc(l + 0.4)) c h / calc(alpha + 0.4)))}`,
+    `:where(.dark) .shimmer{--_highlight:var(--shimmer-color,oklch(from currentColor max(0.8,calc(l + 0.4)) c h / calc(alpha + 0.4)))}`,
     `.shimmer:where([dir="rtl"],[dir="rtl"] *){animation-direction:reverse}`,
     `@media (prefers-reduced-motion:reduce){.shimmer{animation:none;background-image:none;-webkit-text-fill-color:currentColor}}`,
   ]],