@antfu/design 0.1.0

package/components/Layout/LayoutToolbar.stories.ts

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { ref } from 'vue'
+import ActionIconButton from '../Action/ActionIconButton.vue'
+import FormSearchField from '../Form/FormSearchField.vue'
+import LayoutToolbar from './LayoutToolbar.vue'
+
+const meta = {
+  title: 'Layout/LayoutToolbar',
+  component: LayoutToolbar,
+  tags: ['autodocs'],
+  argTypes: {
+    sticky: { control: 'boolean' },
+    glass: { control: 'boolean' },
+  },
+  args: { sticky: true, glass: true },
+} satisfies Meta<typeof LayoutToolbar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => ({
+    components: { LayoutToolbar, ActionIconButton, FormSearchField },
+    setup() {
+      return { search: ref('') }
+    },
+    template: `<div class="border border-base rounded-lg w-full overflow-hidden">
+      <LayoutToolbar>
+        <template #start>
+          <span class="i-catppuccin:folder-app text-lg" aria-hidden="true" />
+          <span class="text-sm color-base font-medium">Project</span>
+        </template>
+        <template #search>
+          <FormSearchField v-model="search" placeholder="Search files…" />
+        </template>
+        <template #end>
+          <ActionIconButton icon="i-catppuccin:folder-config" tooltip="Settings" />
+          <ActionIconButton icon="i-catppuccin:git" tooltip="Repository" />
+        </template>
+      </LayoutToolbar>
+      <div class="text-sm color-muted p-4">Page content…</div>
+    </div>`,
+  }),
+}
+
+export const Opaque: Story = {
+  render: () => ({
+    components: { LayoutToolbar, ActionIconButton },
+    template: `<div class="border border-base rounded-lg w-full overflow-hidden">
+      <LayoutToolbar :glass="false" :sticky="false">
+        <template #start>
+          <span class="text-sm color-base font-medium">Dashboard</span>
+        </template>
+        <template #end>
+          <ActionIconButton icon="i-catppuccin:folder-config" tooltip="Settings" />
+        </template>
+      </LayoutToolbar>
+    </div>`,
+  }),
+}

package/components/Layout/LayoutToolbar.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    /** Stick to the top of the scroll container with `z-nav`. */
+    sticky?: boolean
+    /** Translucent `bg-glass` surface; set `false` for an opaque `bg-base`. */
+    glass?: boolean
+  }>(),
+  { sticky: true, glass: true },
+)
+</script>
+
+<template>
+  <div
+    class="px-3 py-2 border-b border-base flex gap-3 items-center"
+    :class="[sticky ? 'sticky top-0 z-nav' : '', glass ? 'bg-glass' : 'bg-base']"
+  >
+    <slot name="start">
+      <slot />
+    </slot>
+    <div v-if="$slots.search" class="flex-1 min-w-0">
+      <slot name="search" />
+    </div>
+    <div v-if="$slots.end" class="flex gap-1 items-center">
+      <slot name="end" />
+    </div>
+  </div>
+</template>

package/components/Layout/LayoutVirtualList.stories.ts

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import LayoutVirtualList from './LayoutVirtualList.vue'
+
+// `component` is omitted: this is a generic SFC, which doesn't fit Storybook's
+// `Meta<typeof Component>` typing. The render below uses it directly.
+const meta = {
+  title: 'Layout/LayoutVirtualList',
+  tags: ['autodocs'],
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+export const Default: Story = {
+  render: () => ({
+    components: { LayoutVirtualList },
+    setup() {
+      return { items: Array.from({ length: 10000 }, (_, i) => `Row ${i + 1}`) }
+    },
+    template: `<div class="border border-base rounded-lg h-72 w-72">
+      <LayoutVirtualList :items="items" class="h-full" :estimate-size="32">
+        <template #default="{ item, index }">
+          <div class="text-sm font-mono px-3 py-1.5 border-b border-base flex h-8 items-center" :class="{ 'bg-secondary': index % 2 }">
+            {{ item }}
+          </div>
+        </template>
+      </LayoutVirtualList>
+    </div>`,
+  }),
+}

package/components/Layout/LayoutVirtualList.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts" generic="T">
+import { useVirtualizer, useWindowVirtualizer } from '@tanstack/vue-virtual'
+import { computed, onMounted, ref } from 'vue'
+
+const props = withDefaults(
+  defineProps<{
+    items: T[]
+    /** Estimated item extent in px (the fixed size unless `dynamic`). */
+    estimateSize?: number
+    overscan?: number
+    horizontal?: boolean
+    /** Measure each rendered row for variable heights (vs a fixed estimate). */
+    dynamic?: boolean
+    /** Virtualize against window scroll instead of an inner scroll box (set once). */
+    windowScroll?: boolean
+  }>(),
+  { estimateSize: 36, overscan: 8 },
+)
+
+const parentRef = ref<HTMLElement | null>(null)
+const scrollMargin = ref(0)
+onMounted(() => {
+  if (props.windowScroll && parentRef.value)
+    scrollMargin.value = parentRef.value.offsetTop
+})
+
+const common = computed(() => ({
+  count: props.items.length,
+  estimateSize: () => props.estimateSize,
+  overscan: props.overscan,
+  horizontal: props.horizontal,
+}))
+
+const virtualizer = props.windowScroll
+  ? useWindowVirtualizer(computed(() => ({ ...common.value, scrollMargin: scrollMargin.value })))
+  : useVirtualizer(computed(() => ({ ...common.value, getScrollElement: () => parentRef.value })))
+
+const rows = computed(() => virtualizer.value.getVirtualItems())
+const totalSize = computed(() => virtualizer.value.getTotalSize())
+
+function offsetOf(start: number): number {
+  return start - (props.windowScroll ? scrollMargin.value : 0)
+}
+
+function measure(el: Element | null): void {
+  if (props.dynamic && el instanceof Element)
+    virtualizer.value.measureElement(el)
+}
+
+defineExpose({
+  /** Scroll a row into view by index. */
+  scrollToIndex: (index: number, options?: { align?: 'start' | 'center' | 'end' | 'auto' }) =>
+    virtualizer.value.scrollToIndex(index, options),
+  /** Scroll to a pixel offset. */
+  scrollToOffset: (offset: number, options?: { align?: 'start' | 'center' | 'end' | 'auto' }) =>
+    virtualizer.value.scrollToOffset(offset, options),
+  /** The underlying TanStack virtualizer. */
+  virtualizer,
+})
+</script>
+
+<template>
+  <div ref="parentRef" :class="windowScroll ? '' : 'overflow-auto'">
+    <div :style="{ position: 'relative', [horizontal ? 'width' : 'height']: `${totalSize}px` }">
+      <div
+        v-for="row in rows"
+        :key="row.index"
+        :ref="dynamic ? (el) => measure(el as Element | null) : undefined"
+        :style="{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          [horizontal ? 'height' : 'width']: '100%',
+          transform: horizontal ? `translateX(${offsetOf(row.start)}px)` : `translateY(${offsetOf(row.start)}px)`,
+        }"
+        :data-index="row.index"
+      >
+        <slot :item="items[row.index]" :index="row.index" />
+      </div>
+    </div>
+  </div>
+</template>

package/components/Overlay/OverlayDrawer.stories.ts

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { ref } from 'vue'
+import ActionButton from '../Action/ActionButton.vue'
+import OverlayDrawer from './OverlayDrawer.vue'
+
+const meta = {
+  title: 'Overlay/OverlayDrawer',
+  component: OverlayDrawer,
+  tags: ['autodocs'],
+  argTypes: {
+    side: { control: 'inline-radio', options: ['left', 'right', 'top', 'bottom'] },
+  },
+  args: { title: 'Filters', side: 'right' },
+} satisfies Meta<typeof OverlayDrawer>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => ({
+    components: { OverlayDrawer, ActionButton },
+    setup() {
+      return { open: ref(false) }
+    },
+    template: `<div>
+      <ActionButton @click="open = true">Open drawer</ActionButton>
+      <OverlayDrawer v-model:open="open" title="Filters">
+        <p class="text-sm color-muted">Drawer content slides from the edge.</p>
+      </OverlayDrawer>
+    </div>`,
+  }),
+}
+
+export const LeftSide: Story = {
+  render: () => ({
+    components: { OverlayDrawer, ActionButton },
+    setup() {
+      return { open: ref(false) }
+    },
+    template: `<div>
+      <ActionButton @click="open = true">Open left drawer</ActionButton>
+      <OverlayDrawer v-model:open="open" title="Navigation" side="left">
+        <p class="text-sm color-muted">Slides in from the left.</p>
+      </OverlayDrawer>
+    </div>`,
+  }),
+}

package/components/Overlay/OverlayDrawer.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
+
+withDefaults(
+  defineProps<{
+    title?: string
+    side?: 'left' | 'right' | 'top' | 'bottom'
+  }>(),
+  { side: 'right' },
+)
+
+const open = defineModel<boolean>('open')
+
+const SIDE_CLASS = {
+  right: 'right-0 top-0 h-full w-80 max-w-[90vw] border-l',
+  left: 'left-0 top-0 h-full w-80 max-w-[90vw] border-r',
+  top: 'top-0 inset-x-0 h-1/3 border-b',
+  bottom: 'bottom-0 inset-x-0 h-1/3 border-t',
+} as const
+</script>
+
+<template>
+  <DialogRoot v-model:open="open">
+    <DialogTrigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </DialogTrigger>
+    <DialogPortal>
+      <DialogOverlay class="bg-black/40 inset-0 fixed z-drawer-backdrop backdrop-blur-sm" data-af-animate />
+      <DialogContent
+        class="outline-none border-base bg-base flex flex-col shadow-2xl fixed z-drawer-content"
+        :class="SIDE_CLASS[side]"
+        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">
+            <svg width="1em" height="1em" viewBox="0 0 24 24" aria-hidden="true">
+              <path fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" d="M6 6l12 12M18 6L6 18" />
+            </svg>
+          </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>

package/components/Overlay/OverlayDropdown.stories.ts

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import ActionButton from '../Action/ActionButton.vue'
+import OverlayDropdown from './OverlayDropdown.vue'
+import OverlayDropdownItem from './OverlayDropdownItem.vue'
+
+const meta = {
+  title: 'Overlay/OverlayDropdown',
+  component: OverlayDropdown,
+  tags: ['autodocs'],
+} satisfies Meta<typeof OverlayDropdown>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => ({
+    components: { OverlayDropdown, OverlayDropdownItem, ActionButton },
+    template: `<OverlayDropdown>
+      <template #trigger><ActionButton icon="i-ph:gear">Menu</ActionButton></template>
+      <OverlayDropdownItem icon="i-ph:folder">Open</OverlayDropdownItem>
+      <OverlayDropdownItem icon="i-ph:pencil-simple">Rename</OverlayDropdownItem>
+      <OverlayDropdownItem icon="i-ph:trash">Delete</OverlayDropdownItem>
+    </OverlayDropdown>`,
+  }),
+}

package/components/Overlay/OverlayDropdown.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import { DropdownMenuContent, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuTrigger } from 'reka-ui'
+
+withDefaults(
+  defineProps<{
+    placement?: 'top' | 'right' | 'bottom' | 'left'
+    align?: 'start' | 'center' | 'end'
+  }>(),
+  { placement: 'bottom', align: 'start' },
+)
+</script>
+
+<template>
+  <DropdownMenuRoot>
+    <DropdownMenuTrigger as-child>
+      <slot name="trigger" />
+    </DropdownMenuTrigger>
+    <DropdownMenuPortal>
+      <DropdownMenuContent
+        :side="placement"
+        :align="align"
+        :side-offset="6"
+        class="p-1 outline-none border border-base rounded-lg bg-base min-w-40 shadow-lg z-dropdown"
+        data-af-animate
+      >
+        <slot />
+      </DropdownMenuContent>
+    </DropdownMenuPortal>
+  </DropdownMenuRoot>
+</template>

package/components/Overlay/OverlayDropdownItem.stories.ts

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import ActionButton from '../Action/ActionButton.vue'
+import OverlayDropdown from './OverlayDropdown.vue'
+import OverlayDropdownItem from './OverlayDropdownItem.vue'
+
+const meta = {
+  title: 'Overlay/OverlayDropdownItem',
+  component: OverlayDropdownItem,
+  tags: ['autodocs'],
+} satisfies Meta<typeof OverlayDropdownItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// DropdownItem only renders meaningfully inside a Dropdown menu.
+export const InDropdown: Story = {
+  render: () => ({
+    components: { OverlayDropdown, OverlayDropdownItem, ActionButton },
+    template: `<OverlayDropdown>
+      <template #trigger><ActionButton icon="i-ph:gear">Actions</ActionButton></template>
+      <OverlayDropdownItem icon="i-ph:folder">Open</OverlayDropdownItem>
+      <OverlayDropdownItem icon="i-ph:pencil-simple">Rename</OverlayDropdownItem>
+      <OverlayDropdownItem icon="i-ph:trash" disabled>Delete (disabled)</OverlayDropdownItem>
+    </OverlayDropdown>`,
+  }),
+}

package/components/Overlay/OverlayDropdownItem.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { DropdownMenuItem } from 'reka-ui'
+import DisplayKbd from '../Display/DisplayKbd.vue'
+
+withDefaults(
+  defineProps<{
+    icon?: string
+    disabled?: boolean
+    /** `danger` tints the item red for destructive actions. */
+    variant?: 'default' | 'danger'
+    /** Keyboard-shortcut hint shown trailing (a chord string, e.g. `mod+c`). */
+    shortcut?: string
+  }>(),
+  { variant: 'default' },
+)
+
+const emit = defineEmits<{ select: [] }>()
+</script>
+
+<template>
+  <DropdownMenuItem
+    :disabled="disabled"
+    class="text-sm px-2 py-1.5 outline-none rounded-md flex gap-2 cursor-pointer select-none transition items-center data-[highlighted]:bg-active data-[disabled]:op50 data-[disabled]:pointer-events-none"
+    :class="variant === 'danger' ? 'text-red-600 dark:text-red-400 data-[highlighted]:bg-red-500/10' : 'color-base'"
+    @select="emit('select')"
+  >
+    <span v-if="icon" :class="icon" class="op-fade" aria-hidden="true" />
+    <span class="flex-1"><slot /></span>
+    <DisplayKbd v-if="shortcut" :keys="shortcut" class="op-fade" />
+  </DropdownMenuItem>
+</template>

package/components/Overlay/OverlayDropdownLabel.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { DropdownMenuLabel } from 'reka-ui'
+</script>
+
+<template>
+  <DropdownMenuLabel class="text-micro color-faint tracking-wide font-medium px-2 py-1 select-none uppercase">
+    <slot />
+  </DropdownMenuLabel>
+</template>

package/components/Overlay/OverlayDropdownSeparator.vue

@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import { DropdownMenuSeparator } from 'reka-ui'
+</script>
+
+<template>
+  <DropdownMenuSeparator class="mx--1 my-1 border-t border-base" />
+</template>

package/components/Overlay/OverlayModal.stories.ts

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { ref } from 'vue'
+import ActionButton from '../Action/ActionButton.vue'
+import OverlayModal from './OverlayModal.vue'
+
+const meta = {
+  title: 'Overlay/OverlayModal',
+  component: OverlayModal,
+  tags: ['autodocs'],
+  args: { title: 'Confirm action', description: 'This cannot be undone.' },
+} satisfies Meta<typeof OverlayModal>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => ({
+    components: { OverlayModal, ActionButton },
+    setup() {
+      return { open: ref(false) }
+    },
+    template: `<div>
+      <ActionButton @click="open = true">Open modal</ActionButton>
+      <OverlayModal v-model:open="open" title="Confirm action" description="This cannot be undone.">
+        <p class="text-sm color-muted">Modal body content goes here.</p>
+        <template #footer>
+          <ActionButton variant="text" @click="open = false">Cancel</ActionButton>
+          <ActionButton variant="primary" @click="open = false">Confirm</ActionButton>
+        </template>
+      </OverlayModal>
+    </div>`,
+  }),
+}

package/components/Overlay/OverlayModal.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { DialogClose, DialogContent, DialogDescription, DialogOverlay, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from 'reka-ui'
+
+defineProps<{
+  title?: string
+  description?: string
+}>()
+
+const open = defineModel<boolean>('open')
+</script>
+
+<template>
+  <DialogRoot v-model:open="open">
+    <DialogTrigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </DialogTrigger>
+    <DialogPortal>
+      <DialogOverlay class="bg-black/40 inset-0 fixed z-modal-backdrop backdrop-blur-sm" data-af-animate />
+      <DialogContent
+        class="outline-none border border-base rounded-xl bg-base max-w-lg w-[90vw] shadow-2xl left-1/2 top-1/2 fixed z-modal-content -translate-x-1/2 -translate-y-1/2"
+        data-af-modal
+      >
+        <header v-if="title || description || $slots.header" class="px-4 py-3 border-b border-base flex gap-4 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">
+            <svg width="1em" height="1em" viewBox="0 0 24 24" aria-hidden="true">
+              <path fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" d="M6 6l12 12M18 6L6 18" />
+            </svg>
+          </DialogClose>
+        </header>
+        <div class="p-4">
+          <slot />
+        </div>
+        <footer v-if="$slots.footer" class="px-4 py-3 border-t border-base flex gap-2 justify-end">
+          <slot name="footer" />
+        </footer>
+      </DialogContent>
+    </DialogPortal>
+  </DialogRoot>
+</template>

package/components/Overlay/OverlayTooltip.stories.ts

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import ActionButton from '../Action/ActionButton.vue'
+import OverlayTooltip from './OverlayTooltip.vue'
+
+const meta = {
+  title: 'Overlay/OverlayTooltip',
+  component: OverlayTooltip,
+  tags: ['autodocs'],
+  args: { content: 'Tooltip content' },
+} satisfies Meta<typeof OverlayTooltip>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render: () => ({
+    components: { OverlayTooltip, ActionButton },
+    template: `<OverlayTooltip content="Tooltip content"><ActionButton>Hover me</ActionButton></OverlayTooltip>`,
+  }),
+}
+
+export const RichContent: Story = {
+  render: () => ({
+    components: { OverlayTooltip, ActionButton },
+    template: `<OverlayTooltip placement="bottom">
+      <ActionButton>Hover for rich content</ActionButton>
+      <template #content>
+        <div class="font-medium">Title</div>
+        <div class="text-xs op75">A richer popper body.</div>
+      </template>
+    </OverlayTooltip>`,
+  }),
+}

package/components/Overlay/OverlayTooltip.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { Tooltip as VTooltip } from 'floating-vue'
+
+withDefaults(
+  defineProps<{
+    /** Tooltip text (use the `content` slot for rich content). */
+    content?: string
+    placement?: string
+    distance?: number
+    /** Show/hide delay in ms, or `{ show, hide }`. */
+    delay?: number | { show?: number, hide?: number }
+    /** What triggers the tooltip, e.g. `['hover', 'focus']` or `['click']`. */
+    triggers?: string[]
+    /** Programmatic open state (bypasses triggers when set). */
+    shown?: boolean
+    disabled?: boolean
+  }>(),
+  { placement: 'top', distance: 6 },
+)
+</script>
+
+<template>
+  <VTooltip
+    :placement="placement as any"
+    :distance="distance"
+    :delay="delay as any"
+    :triggers="triggers as any"
+    :shown="shown"
+    :disabled="disabled"
+  >
+    <slot />
+    <template #popper>
+      <slot name="content">
+        {{ content }}
+      </slot>
+    </template>
+  </VTooltip>
+</template>

package/composables/colorScheme.ts

@@ -0,0 +1,58 @@
+/**
+ * Opt-in color-scheme context.
+ *
+ * The package is stateless: most components flip light/dark automatically from
+ * the `html.dark` class + `--af-*` tokens, and the handful that compute colors in
+ * JS (badges/labels/proportion bars) take a `colorScheme` prop. Threading that
+ * prop everywhere is tedious, so this provides an *opt-in* context: call
+ * {@link provideColorScheme} once near the app root (feeding it your own
+ * app-owned dark ref), and scheme-aware components fall back to it when their
+ * prop is omitted. The package itself owns no state — the context only *reads* a
+ * ref you pass in.
+ */
+import type { ComputedRef, InjectionKey, MaybeRefOrGetter, Ref } from 'vue'
+import { computed, inject, provide, toRef } from 'vue'
+
+export type ColorScheme = 'light' | 'dark'
+
+/** Injection key for the active {@link ColorScheme}. */
+export const colorSchemeKey: InjectionKey<Ref<ColorScheme>> = Symbol('antfu-design-color-scheme')
+
+/**
+ * Provide the active color scheme to descendant components (call in `setup`).
+ *
+ * Accepts a ref, a getter, or a plain value — pass a getter/ref bound to your own
+ * dark-mode state so the context stays reactive. The package stays stateless: it
+ * only reads the value you provide.
+ *
+ * @param scheme - The current scheme as a ref, getter, or value.
+ * @returns The resolved {@link ColorScheme} ref that was provided.
+ *
+ * @example
+ * const isDark = useDark()
+ * provideColorScheme(() => isDark.value ? 'dark' : 'light')
+ */
+export function provideColorScheme(scheme: MaybeRefOrGetter<ColorScheme>): Ref<ColorScheme> {
+  const ref = toRef(scheme) as Ref<ColorScheme>
+  provide(colorSchemeKey, ref)
+  return ref
+}
+
+/**
+ * Resolve the effective color scheme: explicit prop → provided context → `'light'`.
+ *
+ * Components pass a getter for their own `colorScheme` prop so an explicit prop
+ * always wins; otherwise the value from {@link provideColorScheme} is used, and
+ * finally `'light'` as the default.
+ *
+ * @param prop - Getter for the component's own `colorScheme` prop (optional).
+ * @returns A computed {@link ColorScheme}.
+ *
+ * @example
+ * const scheme = useColorScheme(() => props.colorScheme)
+ * const dark = computed(() => scheme.value === 'dark')
+ */
+export function useColorScheme(prop?: () => ColorScheme | undefined): ComputedRef<ColorScheme> {
+  const injected = inject(colorSchemeKey, undefined)
+  return computed<ColorScheme>(() => prop?.() ?? injected?.value ?? 'light')
+}